json_model_rb 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffcf41bdf354c5c3d979ca928d7d7c7c774c3c5506a8c6d96997309a2a9df6b1
-  data.tar.gz: 9f1f13bfde527fc6a4d1cac1a91ad9e85a34ccfd2fbcc8780e824128a11b18ce
+  metadata.gz: 91d9055f02d8e7422d6915d44620adbd1668ca5fcff577fe2cf0964412699153
+  data.tar.gz: 447bfbd423aa8e176faf3844079e48d3a1e01f5e367778ca48b8e0f659f51928
 SHA512:
-  metadata.gz: 107a70cadd0f6b9b373b71383f5200ab986c31570f27b9685488c3c37af4abe97347a76718c1ca1da1053dd573ca92e04679f3622f5554672bee99c0f7b61098
-  data.tar.gz: 0cf9afcc30d3344ed5371b1125c59f99132ac3f62c7d00d96c2257e01e8c847d60f4a76d3428b1dcc7f4a09b97bf251843f0814643a462b591ee185f602df175
+  metadata.gz: 7b99e2ddcbde5c4adec3138796292ff564ad19342ba32c7513bba90c7beac1b8522b6d1c62f7cf987840b08eadca5a2d3206ab892ba9cc36fa6760b71490f6bc
+  data.tar.gz: 87247c327a4bbf77e171c7bf89389f616109dbc8a6e0b37d6ceb177bf2a3d89cd5def0c585d614d8f10ce4b91da589af3a7f042e005bca1ae60d3b3ba2b83bad

data/README.md

@@ -0,0 +1,686 @@
+# JSON Model
+
+[![Gem Version](https://badge.fury.io/rb/json_model.svg)](https://badge.fury.io/rb/json_model)
+[![Ruby](https://github.com/gillesbergerp/json_model_rb/actions/workflows/ci.yml/badge.svg)](https://github.com/gillesbergerp/json_model_rb/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+A Ruby DSL for building JSON Schema definitions with a clean, declarative syntax. Define your schemas in Ruby and generate complete, standards-compliant JSON Schema documents.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'json_model'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install json_model
+```
+
+## Quick Start
+
+```ruby
+require 'json_model'
+
+class User
+  include JsonModel::Schema
+
+  schema_id "https://example.com/schemas/user.json"
+  title "User"
+  description "A registered user in the system"
+
+  property :name, type: String
+  property :email, type: String, format: :email
+  property :age, type: Integer, minimum: 0, maximum: 120, optional: true
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(User.as_schema)
+```
+
+**Output:**
+```json
+{
+  "$id": "https://example.com/schemas/user.json",
+  "additionalProperties": false,
+  "title": "User",
+  "description": "A registered user in the system",
+  "properties": {
+    "age": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 120
+    },
+    "email": {
+      "type": "string",
+      "format": "email"
+    },
+    "name": {
+      "type": "string"
+    }
+  },
+  "required": [
+    {
+      "json_class": "Symbol",
+      "s": "email"
+    },
+    {
+      "json_class": "Symbol",
+      "s": "name"
+    }
+  ],
+  "type": "object"
+}
+```
+
+## Schema Metadata
+
+You can set top-level schema metadata properties directly in your schema class:
+
+```ruby
+class Product
+  include JsonModel::Schema
+
+  # Schema metadata
+  schema_id "https://api.example.com/schemas/product.json"
+  schema_version :draft_2020_12
+  title "Product"
+  description "A product available in the catalog"
+  
+  # Properties
+  property :id, type: String
+  property :name, type: String
+  property :price, type: Float, minimum: 0
+  property :available, type: T::Boolean, default: true, optional: true
+end
+```
+
+### Available Metadata Keywords
+
+- **`schema_id`** - Sets the `$id` (unique URI identifier for the schema)
+- **`schema_version`** - Sets the `$schema` (JSON Schema version)
+- **`title`** - Human-readable title for the schema
+- **`description`** - Detailed explanation of the schema's purpose
+- **`additional_properties`** - Whether additional properties are allowed (default: `false`)
+
+## Data Types
+
+### String Type
+
+```ruby
+class StringExample
+  include JsonModel::Schema
+
+  # Basic string
+  property :simple_string, type: String
+
+  # String with length constraints
+  property :username, type: String, 
+    min_length: 3,
+    max_length: 20
+
+  # String with pattern (regex)
+  property :product_code, type: String, pattern: /\A[A-Z]{3}-\d{4}\z/
+
+  # String with format
+  property :email, type: String, format: :email
+  property :uri, type: String, format: :uri
+  property :hostname, type: String, format: :hostname
+  property :ipv4, type: String, format: :ipv4
+  property :ipv6, type: String, format: :ipv6
+  property :uuid, type: String, format: :uuid
+  property :date, type: String, format: :date
+  property :time, type: String, format: :time
+  property :datetime, type: String, format: :date_time
+  property :duration, type: String, format: :duration
+  
+  # String with enum
+  property :status, type: String, enum: ["draft", "published", "archived"]
+  
+  # String with const
+  property :api_version, type: String, const: "v1"
+  
+  # Optional string
+  property :nickname, type: String, optional: true
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(StringExample.as_schema)
+```
+
+**Output:**
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "date": {
+      "type": "string",
+      "format": "date"
+    },
+    "datetime": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "duration": {
+      "type": "string",
+      "format": "duration"
+    },
+    "email": {
+      "type": "string",
+      "format": "email"
+    },
+    "hostname": {
+      "type": "string",
+      "format": "hostname"
+    },
+    "ipv4": {
+      "type": "string",
+      "format": "ipv4"
+    },
+    "ipv6": {
+      "type": "string",
+      "format": "ipv6"
+    },
+    "product_code": {
+      "type": "string",
+      "pattern": "\\A[A-Z]{3}-\\d{4}\\z"
+    },
+    "simple_string": {
+      "type": "string"
+    },
+    "time": {
+      "type": "string",
+      "format": "time"
+    },
+    "uri": {
+      "type": "string",
+      "format": "uri"
+    },
+    "username": {
+      "type": "string",
+      "minLength": 3,
+      "maxLength": 20
+    },
+    "uuid": {
+      "type": "string",
+      "format": "uuid"
+    }
+  },
+  "required": [
+    "date",
+    "datetime",
+    "duration",
+    "email",
+    "hostname",
+    "ipv4",
+    "ipv6",
+    "product_code",
+    "simple_string",
+    "time",
+    "uri",
+    "username",
+    "uuid"
+  ],
+  "type": "object"
+}
+```
+
+### Number and Integer Types
+
+```ruby
+class NumericExample
+  include JsonModel::Schema
+
+  # Integer
+  property :count, type: Integer
+
+  # Integer with range
+  property :port, type: Integer, minimum: 1024, maximum: 65535
+
+  # Integer with exclusive bounds
+  property :positive_int, type: Integer, exclusive_minimum: 0
+
+  # Number (float/double)
+  property :price, type: Float, minimum: 0
+
+  # Number with multiple_of
+  property :quantity, type: Integer, multiple_of: 10
+
+  # Number with precision
+  property :temperature, type: Float, minimum: -273.15, maximum: 1000.0
+  
+  # Optional number
+  property :discount, type: Float, optional: true
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(NumericExample.as_schema)
+```
+
+**Output:**
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "count": {
+      "type": "integer"
+    },
+    "discount": {
+      "type": "number"
+    },
+    "port": {
+      "type": "integer",
+      "minimum": 1024,
+      "maximum": 65535
+    },
+    "positive_int": {
+      "type": "integer",
+      "exclusiveMinimum": 0
+    },
+    "price": {
+      "type": "number",
+      "minimum": 0
+    },
+    "quantity": {
+      "type": "integer",
+      "multipleOf": 10
+    },
+    "temperature": {
+      "type": "number",
+      "minimum": -273.15,
+      "maximum": 1000.0
+    }
+  },
+  "required": [
+    "count",
+    "port",
+    "positive_int",
+    "price",
+    "quantity",
+    "temperature"
+  ],
+  "type": "object"
+}
+```
+
+### Boolean Type
+
+```ruby
+class BooleanExample
+  include JsonModel::Schema
+
+  property :is_active, type: T::Boolean
+  property :has_agreed, type: T::Boolean, default: false
+  property :enabled, type: T::Boolean, optional: true
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(BooleanExample.as_schema)
+```
+
+**Output:**
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "enabled": {
+      "type": "boolean"
+    },
+    "has_agreed": {
+      "type": "boolean",
+      "default": false
+    },
+    "is_active": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "has_agreed",
+    "is_active"
+  ],
+  "type": "object"
+}
+```
+
+### Array Type
+
+```ruby
+class ArrayExample
+  include JsonModel::Schema
+
+  # Simple array
+  property :tags, type: T::Array[String]
+
+  # Array with constraints
+  property :numbers, type: T::Array[Integer], min_items: 1, max_items: 10, unique_items: true
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(ArrayExample.as_schema)
+```
+
+**Output:**
+```json
+{
+  "additionalProperties": false,
+  "properties": {
+    "numbers": {
+      "type": "array",
+      "items": {
+        "type": "integer"
+      },
+      "minItems": 1,
+      "maxItems": 10,
+      "uniqueItems": true
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "numbers",
+    "tags"
+  ],
+  "type": "object"
+}
+```
+
+## Schema Composition
+
+JSON Model supports powerful schema composition using `T::AllOf`, `T::AnyOf`, and `T::OneOf`:
+
+### AllOf - Must Match All Schemas
+
+Use `T::AllOf` when a value must validate against all provided schemas (intersection/combining schemas):
+
+```ruby
+class PersonBase
+  include JsonModel::Schema
+
+  property :name, type: String
+  property :age, type: Integer, minimum: 0, optional: true
+end
+
+class EmployeeDetails
+  include JsonModel::Schema
+
+  property :employee_id, type: String, pattern: /\AE-\d{4}\z/
+  property :department, type: String
+  property :salary, type: Float, minimum: 0, optional: true
+end
+
+class Employee
+  include JsonModel::Schema
+
+  title "Employee"
+  description "Combines person and employee-specific properties"
+
+  property :employee, type: T::AllOf[PersonBase, EmployeeDetails]
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(Employee.as_schema)
+```
+
+**Output:**
+```json
+{
+  "additionalProperties": false,
+  "title": "Employee",
+  "description": "Combines person and employee-specific properties",
+  "properties": {
+    "employee": {
+      "allOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "age": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "name": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "name"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "department": {
+              "type": "string"
+            },
+            "employee_id": {
+              "type": "string",
+              "pattern": "\\AE-\\d{4}\\z"
+            },
+            "salary": {
+              "type": "number",
+              "minimum": 0
+            }
+          },
+          "required": [
+            "department",
+            "employee_id"
+          ],
+          "type": "object"
+        }
+      ]
+    }
+  },
+  "required": [
+    "employee"
+  ],
+  "type": "object"
+}
+```
+
+### AnyOf - Must Match At Least One Schema
+
+Use `T::AnyOf` when a value must validate against one or more schemas (union/alternatives):
+
+```ruby
+class EmailContact
+  include JsonModel::Schema
+
+  property :email, type: String, format: :email
+end
+
+class PhoneContact
+  include JsonModel::Schema
+
+  property :phone, type: String, pattern: /\A\+?[1-9]\\d{1,14}\z/
+end
+
+class AddressContact
+  include JsonModel::Schema
+
+  property :street, type: String
+  property :city, type: String
+end
+
+class Contact
+  include JsonModel::Schema
+
+  title "Contact Method"
+  description "Must provide at least one contact method"
+
+  property :contact, type: T::AnyOf[EmailContact, PhoneContact, AddressContact]
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(Contact.as_schema)
+```
+
+**Output:**
+```json
+{
+  "additionalProperties": false,
+  "title": "Contact Method",
+  "description": "Must provide at least one contact method",
+  "properties": {
+    "contact": {
+      "anyOf": [
+        {
+          "additionalProperties": false,
+          "properties": {
+            "email": {
+              "type": "string",
+              "format": "email"
+            }
+          },
+          "required": [
+            "email"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "phone": {
+              "type": "string",
+              "pattern": "\\A\\+?[1-9]\\\\d{1,14}\\z"
+            }
+          },
+          "required": [
+            "phone"
+          ],
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "properties": {
+            "city": {
+              "type": "string"
+            },
+            "street": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "city",
+            "street"
+          ],
+          "type": "object"
+        }
+      ]
+    }
+  },
+  "required": [
+    "contact"
+  ],
+  "type": "object"
+}
+```
+
+### OneOf - Must Match Exactly One Schema
+
+Use `T::OneOf` when a value must validate against exactly one schema (exclusive alternatives):
+
+```ruby
+class CreditCardPayment
+  include JsonModel::Schema
+
+  property :payment_type, type: String, const: "credit_card"
+  property :card_number, type: String, pattern: /\A\d{16}\z/
+  property :cvv, type: String, pattern: /\A\d{3,4}\z/
+  property :expiry, type: String, pattern: /\A\d{2}\/\d{2}\z/
+end
+
+class PayPalPayment
+  include JsonModel::Schema
+
+  property :payment_type, type: String, const: "paypal"
+  property :paypal_email, type: String, format: :email
+end
+
+class BankTransferPayment
+  include JsonModel::Schema
+
+  property :payment_type, type: String, const: "bank_transfer"
+  property :iban, type: String, pattern: "^[A-Z]{2}\\d{2}[A-Z0-9]+$"
+  property :swift, type: String, optional: true
+end
+
+class PaymentMethod
+  include JsonModel::Schema
+
+  title "Payment Method"
+  description "Must specify exactly one payment method"
+
+  property :payment, type: T::OneOf[CreditCardPayment, PayPalPayment, BankTransferPayment]
+end
+
+# Generate the JSON Schema
+puts JSON.pretty_generate(PaymentMethod.as_schema)
+```
+
+**Output:**
+```json
+{
+  "additionalProperties": false,
+  "title": "Payment Method",
+  "description": "Must specify exactly one payment method",
+  "properties": {
+    "payment": {
+      "oneOf": [
+        {
+          "additionalProperties": false,
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "type": "object"
+        },
+        {
+          "additionalProperties": false,
+          "type": "object"
+        }
+      ]
+    }
+  },
+  "required": [
+    "payment"
+  ],
+  "type": "object"
+}
+```
+
+## Use Cases
+
+- **API Documentation**: Generate JSON schemas for API request/response validation
+- **Configuration Files**: Define and validate application configuration schemas
+- **Data Validation**: Validate incoming data against defined schemas
+- **Code Generation**: Use schemas to generate code in other languages
+- **OpenAPI/Swagger**: Generate OpenAPI schema definitions for your APIs
+- **Form Generation**: Generate forms from schema definitions
+
+## Resources
+
+- [JSON Schema Specification](https://json-schema.org/)
+- [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/)
+- [JSON Schema Validator](https://www.jsonschemavalidator.net/)
+- [Draft 7 Reference](https://json-schema.org/draft-07/json-schema-release-notes.html)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Developed and maintained by [gillesbergerp](https://github.com/gillesbergerp).

data/lib/json_model/type_spec/array.rb

@@ -46,9 +46,13 @@ module JsonModel
       end
 
       # @param [::Object] json
-      # @return [::Object]
+      # @return [::Object, nil]
       def cast(json)
-        json.map { |item| @type.cast(item) }
+        if json.is_a?(Enumerable)
+          json.map { |item| @type.cast(item) }
+        else
+          raise(Errors::TypeError, "Expected an array, got #{json.class} (#{json.inspect})")
+        end
       end
 
       private

data/lib/json_model/type_spec/composition/all_of.rb

@@ -11,7 +11,7 @@ module JsonModel
         end
 
         # @param [::Object] json
-        # @return [::Object]
+        # @return [::Object, nil]
         def cast(json)
           if json.nil?
             return nil

data/lib/json_model/type_spec/composition/any_of.rb

@@ -11,7 +11,7 @@ module JsonModel
         end
 
         # @param [::Object] json
-        # @return [::Object]
+        # @return [::Object, nil]
         def cast(json)
           if json.nil?
             return nil

data/lib/json_model/type_spec/composition/one_of.rb

@@ -11,7 +11,7 @@ module JsonModel
         end
 
         # @param [::Object] json
-        # @return [::Object]
+        # @return [::Object, nil]
         def cast(json)
           if json.nil?
             return nil

data/lib/json_model/type_spec/composition.rb

@@ -25,7 +25,7 @@ module JsonModel
       end
 
       # @param [::Object] json
-      # @return [::Object]
+      # @return [::Object, nil]
       def cast(json)
         raise(NotImplementedError)
       end

data/lib/json_model/type_spec/const.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module JsonModel
+  class TypeSpec
+    class Const < TypeSpec
+      # @param [String] value
+      def initialize(value)
+        super()
+        @value = value
+
+        if value.blank?
+          raise(ArgumentError, 'Const type spec requires a non-empty value')
+        end
+      end
+
+      # @param [Hash] _options
+      # @return [Hash]
+      def as_schema(**_options)
+        {
+          const: @value,
+        }.compact
+      end
+
+      # @param [Symbol] name
+      # @param [ActiveModel::Validations] klass
+      def register_validations(name, klass)
+        super
+
+        klass.validates(name, inclusion: { in: @value })
+      end
+    end
+  end
+end

data/lib/json_model/type_spec/object.rb

@@ -21,7 +21,7 @@ module JsonModel
       end
 
       # @param [::Object] json
-      # @return [::Object]
+      # @return [::Object, nil]
       def cast(json)
         @type.new(**json)
       end

data/lib/json_model/type_spec/primitive/string.rb

@@ -76,7 +76,6 @@ module JsonModel
           relative_json_pointer: ->(v) { v.match?(%r{\A(?:0|[1-9][0-9]*)(?:#|(?:/(?:[^~]|~[01])*))*\z}) },
         }.freeze
 
-
         # @param [Integer, nil] min_length
         # @param [Integer, nil] max_length
         # @param [Regexp, nil] pattern

data/lib/json_model/type_spec/primitive.rb

@@ -18,14 +18,14 @@ module JsonModel
       end
 
       # @param [::Object] json
-      # @return [::Object]
+      # @return [::Object, nil]
       def cast(json)
         if json.nil?
           nil
         elsif @types.any? { |type| json.is_a?(type) }
           json
         else
-          raise(Errors::TypeError, "Expected #{@type}, got #{json.class} (#{json.inspect})")
+          raise(Errors::TypeError, "Expected one of #{@type.join('/')}, got #{json.class} (#{json.inspect})")
         end
       end
     end

data/lib/json_model/type_spec.rb

@@ -2,6 +2,7 @@
 
 require_relative('type_spec/array')
 require_relative('type_spec/composition')
+require_relative('type_spec/const')
 require_relative('type_spec/enum')
 require_relative('type_spec/object')
 require_relative('type_spec/primitive')
@@ -24,7 +25,7 @@ module JsonModel
     end
 
     # @param [::Object] json
-    # @return [::Object]
+    # @return [::Object, nil]
     def cast(json)
       json
     end

data/lib/json_model/types/const.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module T
+  class Const
+    # @param [String] value
+    def initialize(value)
+      @value = value
+    end
+
+    # @return [JsonModel::TypeSpec::Const]
+    def to_type_spec(**options)
+      JsonModel::TypeSpec::Const.new(*@value, **options)
+    end
+
+    class << self
+      # @param [Array] args
+      # @return [Const]
+      def [](*args)
+        Const.new(*args)
+      end
+    end
+  end
+end

data/lib/json_model/types.rb

@@ -5,4 +5,5 @@ require_relative('types/any_of')
 require_relative('types/boolean')
 require_relative('types/one_of')
 require_relative('types/array')
+require_relative('types/const')
 require_relative('types/enum')

data/lib/json_model/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module JsonModel
-  VERSION = '0.1.5'
+  VERSION = '0.1.7'
 end

data/spec/type_spec/const_spec.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require('spec_helper')
+
+RSpec.describe(JsonModel::TypeSpec::Const) do
+  describe('#as_schema') do
+    it('returns a const schema') do
+      expect(described_class.new('a').as_schema)
+        .to(
+          eq(
+            {
+              const: 'a'
+            },
+          ),
+        )
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: json_model_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.7
 platform: ruby
 authors:
 - Paul Gillesberger
@@ -121,6 +121,7 @@ files:
 - lib/json_model/type_spec/composition/all_of.rb
 - lib/json_model/type_spec/composition/any_of.rb
 - lib/json_model/type_spec/composition/one_of.rb
+- lib/json_model/type_spec/const.rb
 - lib/json_model/type_spec/enum.rb
 - lib/json_model/type_spec/object.rb
 - lib/json_model/type_spec/primitive.rb
@@ -135,6 +136,7 @@ files:
 - lib/json_model/types/any_of.rb
 - lib/json_model/types/array.rb
 - lib/json_model/types/boolean.rb
+- lib/json_model/types/const.rb
 - lib/json_model/types/enum.rb
 - lib/json_model/types/one_of.rb
 - lib/json_model/version.rb
@@ -152,6 +154,7 @@ files:
 - spec/type_spec/composition/any_of_spec.rb
 - spec/type_spec/composition/one_of_spec.rb
 - spec/type_spec/composition_spec.rb
+- spec/type_spec/const_spec.rb
 - spec/type_spec/enum_spec.rb
 - spec/type_spec/primitive/boolean_spec.rb
 - spec/type_spec/primitive/integer_spec.rb