schematist 0.1.0 → 1.0.0

data/lib/schematist/dsl/complex_types.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    module ComplexTypes
+      def object(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, object_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def array(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, array_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def tuple(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, tuple_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def any_of(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, any_of_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def one_of(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, one_of_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def all_of(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, all_of_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def none_of(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, none_of_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      # Emits a schema fragment verbatim, for the corners of JSON Schema this DSL does not cover
+      def raw(name, schema, required: true, requires: nil)
+        add_property(name, schema, required: required, requires: requires)
+      end
+
+      def optional(name, description: nil, &block)
+        any_of(name, description: description) do
+          instance_eval(&block)
+          null
+        end
+      end
+    end
+  end
+end

data/lib/schematist/dsl/conditional_builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    class ConditionalBuilder
+      def requires(*fields)
+        required.concat(fields.map(&:to_s))
+      end
+
+      VALIDATES_KEY_MAP = {
+        type: :type,
+        const: :const,
+        enum: :enum,
+        not_value: :not,
+        min_length: :minLength,
+        max_length: :maxLength,
+        pattern: :pattern,
+        minimum: :minimum,
+        maximum: :maximum
+      }.freeze
+
+      def validates(field, **options)
+        constraints = {}
+
+        options.each do |key, value|
+          schema_key = VALIDATES_KEY_MAP[key]
+          raise ArgumentError, "unknown validates option: #{key.inspect}" unless schema_key
+
+          case key
+          when :type then constraints[:type] = value.to_s
+          when :not_value then constraints[:not] = {const: value}
+          when :pattern then constraints[:pattern] = value.is_a?(Regexp) ? value.source : value
+          else constraints[schema_key] = value
+          end
+        end
+
+        validations[field.to_s] = constraints
+      end
+
+      def to_schema
+        schema = {}
+
+        schema[:required] = required if required.any?
+        schema[:properties] = validations if validations.any?
+
+        schema
+      end
+
+      def empty?
+        required.empty? && validations.empty?
+      end
+
+      def required_fields
+        required.dup
+      end
+
+      def validations_empty?
+        validations.empty?
+      end
+
+      private
+
+      def required
+        @required ||= []
+      end
+
+      def validations
+        @validations ||= {}
+      end
+    end
+  end
+end

data/lib/schematist/dsl/conditional_context.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    class ConditionalContext
+      def initialize(then_builder, else_builder)
+        @then_builder = then_builder
+        @else_builder = else_builder
+      end
+
+      def requires(*fields)
+        @then_builder.requires(*fields)
+      end
+
+      def validates(field, **options)
+        @then_builder.validates(field, **options)
+      end
+
+      def otherwise(&block)
+        @else_builder.instance_eval(&block)
+      end
+    end
+  end
+end

data/lib/schematist/dsl/conditionals.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    module Conditionals
+      def conditions
+        @conditions ||= []
+      end
+
+      def dependencies
+        @dependencies ||= {}
+      end
+
+      def dependent(property, &block)
+        builder = ConditionalBuilder.new
+        builder.instance_eval(&block)
+
+        dependencies[property.to_s] = builder
+      end
+
+      def given(**properties, &block)
+        raise ArgumentError, "given requires at least one property condition" if properties.empty?
+
+        if_schema = {
+          properties: properties.transform_keys(&:to_s).transform_values { |v| coerce_condition(v) },
+          required: properties.keys.map(&:to_s)
+        }
+
+        then_builder = ConditionalBuilder.new
+        else_builder = ConditionalBuilder.new
+
+        context = ConditionalContext.new(then_builder, else_builder)
+        context.instance_eval(&block)
+
+        condition = {if: if_schema, then: then_builder.to_schema}
+        condition[:else] = else_builder.to_schema unless else_builder.empty?
+
+        conditions << condition
+      end
+
+      private
+
+      def merge_conditions(schema, schema_class)
+        if schema_class.respond_to?(:conditions) && schema_class.conditions.any?
+          if schema_class.conditions.length == 1
+            schema.merge!(schema_class.conditions.first)
+          else
+            schema[:allOf] = schema_class.conditions
+          end
+        end
+
+        if schema_class.respond_to?(:dependencies) && schema_class.dependencies.any?
+          dependent_required = {}
+          dependent_schemas = {}
+
+          schema_class.dependencies.each do |property, builder|
+            if builder.validations_empty?
+              dependent_required[property] = builder.required_fields
+            else
+              dependent_schemas[property] = builder.to_schema
+            end
+          end
+
+          schema[:dependentRequired] = dependent_required if dependent_required.any?
+          schema[:dependentSchemas] = dependent_schemas if dependent_schemas.any?
+        end
+
+        schema
+      end
+
+      def coerce_condition(value)
+        case value
+        when Array then {enum: value}
+        when Regexp then {pattern: value.source}
+        when Hash then value
+        else {const: value}
+        end
+      end
+    end
+  end
+end

data/lib/schematist/dsl/primitive_types.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    module PrimitiveTypes
+      def string(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, string_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def number(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, number_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def integer(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, integer_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def boolean(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, boolean_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def null(name, description: nil, required: true, requires: nil, **options, &block)
+        add_property(name, null_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+    end
+  end
+end

data/lib/schematist/dsl/schema_builders.rb

@@ -0,0 +1,306 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    module SchemaBuilders
+      # What a schema block yields: the schemas declared in it, and the keywords set on the enclosing node
+      SchemaBlock = Struct.new(:schemas, :keywords)
+
+      def string_schema(description: nil, enum: nil, const: nil, min_length: nil, max_length: nil, pattern: nil, format: nil, content_encoding: nil, content_media_type: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({
+          type: "string",
+          enum: enum,
+          const: const,
+          description: description,
+          minLength: min_length,
+          maxLength: max_length,
+          pattern: pattern,
+          format: format,
+          contentEncoding: content_encoding,
+          contentMediaType: content_media_type
+        }.compact, annotations, schema_block)
+      end
+
+      def number_schema(description: nil, minimum: nil, maximum: nil, greater_than: nil, less_than: nil, multiple_of: nil, enum: nil, const: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({
+          type: "number",
+          description: description,
+          minimum: minimum,
+          maximum: maximum,
+          exclusiveMinimum: greater_than,
+          exclusiveMaximum: less_than,
+          multipleOf: multiple_of,
+          enum: enum,
+          const: const
+        }.compact, annotations, schema_block)
+      end
+
+      def integer_schema(description: nil, minimum: nil, maximum: nil, greater_than: nil, less_than: nil, multiple_of: nil, enum: nil, const: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({
+          type: "integer",
+          description: description,
+          minimum: minimum,
+          maximum: maximum,
+          exclusiveMinimum: greater_than,
+          exclusiveMaximum: less_than,
+          multipleOf: multiple_of,
+          enum: enum,
+          const: const
+        }.compact, annotations, schema_block)
+      end
+
+      def boolean_schema(description: nil, const: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({type: "boolean", description: description, const: const}.compact, annotations, schema_block)
+      end
+
+      def null_schema(description: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({type: "null", description: description}.compact, annotations, schema_block)
+      end
+
+      def object_schema(description: nil, of: nil, reference: nil, min_properties: nil, max_properties: nil, unevaluated_properties: nil, **annotations, &block)
+        if reference
+          warn "[DEPRECATION] The `reference` option will be deprecated. Please use `of` instead."
+          of = reference
+        end
+
+        schema = of ? determine_object_reference(of, description) : build_object_schema(description, &block)
+
+        annotate(schema.merge({
+          minProperties: min_properties,
+          maxProperties: max_properties,
+          unevaluatedProperties: unevaluated_properties
+        }.compact), annotations)
+      end
+
+      def array_schema(description: nil, of: nil, min_items: nil, max_items: nil, unique: nil, unevaluated_items: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({
+          type: "array",
+          description: description,
+          items: determine_array_items(of, schema_block),
+          minItems: min_items,
+          maxItems: max_items,
+          uniqueItems: unique,
+          unevaluatedItems: unevaluated_items
+        }.compact, annotations, schema_block)
+      end
+
+      def tuple_schema(description: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+        schemas = schema_block.schemas
+
+        annotate({
+          type: "array",
+          description: description,
+          prefixItems: schemas,
+          minItems: schemas.length,
+          maxItems: schemas.length
+        }.compact, annotations, schema_block)
+      end
+
+      def any_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+
+        annotate({
+          description: description,
+          anyOf: schema_block.schemas,
+          unevaluatedProperties: unevaluated_properties
+        }.compact, annotations, schema_block)
+      end
+
+      def one_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+
+        annotate({
+          description: description,
+          oneOf: schema_block.schemas,
+          unevaluatedProperties: unevaluated_properties
+        }.compact, annotations, schema_block)
+      end
+
+      def all_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+
+        annotate({
+          description: description,
+          allOf: schema_block.schemas,
+          unevaluatedProperties: unevaluated_properties
+        }.compact, annotations, schema_block)
+      end
+
+      def none_of_schema(description: nil, unevaluated_properties: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+        schemas = schema_block.schemas
+
+        annotate({
+          description: description,
+          not: schemas.size == 1 ? schemas.first : {anyOf: schemas},
+          unevaluatedProperties: unevaluated_properties
+        }.compact, annotations, schema_block)
+      end
+
+      private
+
+      # Annotations set inside the block are defaults; options and keyword annotations win over them.
+      def annotate(schema, annotations, schema_block = nil)
+        unknown = annotations.keys - ANNOTATIONS.keys
+        raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" if unknown.any?
+
+        block_keywords = schema_block ? schema_block.keywords : {}
+        block_keywords.merge(schema).merge(annotations.transform_keys { |name| ANNOTATIONS.fetch(name) })
+      end
+
+      def build_object_schema(description, &block)
+        sub_schema = Class.new(Schema)
+        result = sub_schema.class_eval(&block)
+
+        # If the block returned a reference and no properties were added, use the reference
+        if result.is_a?(Hash) && result["$ref"] && sub_schema.properties.empty?
+          result.merge(description ? {description: description} : {})
+        # If the block returned a Schema class or instance, convert it to inline schema
+        elsif schema_class?(result) && sub_schema.properties.empty?
+          schema_class_to_inline_schema(result).merge(description ? {description: description} : {})
+        # Block didn't return reference or schema, so we build an inline object schema
+        else
+          schema = {
+            type: "object",
+            properties: sub_schema.properties,
+            required: sub_schema.required_properties,
+            additionalProperties: sub_schema.additional_properties,
+            description: description
+          }.compact
+
+          merge_schema_keywords(schema, sub_schema)
+        end
+      end
+
+      def determine_array_items(of, schema_block = nil)
+        return schema_block.schemas.first if schema_block
+        return send("#{of}_schema") if primitive_type?(of)
+        return reference(of) if of.is_a?(Symbol)
+        return schema_class_to_inline_schema(of) if schema_class?(of)
+
+        raise InvalidArrayTypeError, "Invalid array type: #{of.inspect}. Must be a primitive type (:string, :number, etc.), a symbol reference, a Schema class, or a Schema instance."
+      end
+
+      def determine_object_reference(of, description = nil)
+        result = case of
+                 when Symbol
+                   reference(of)
+                 when Class
+                   raise InvalidObjectTypeError, "Invalid object type: #{of.inspect}. Class must inherit from Schematist::Schema." unless schema_class?(of)
+
+                   schema_class_to_inline_schema(of)
+
+                 else
+                   raise InvalidObjectTypeError, "Invalid object type: #{of.inspect}. Must be a symbol reference, a Schema class, or a Schema instance." unless schema_class?(of)
+
+                   schema_class_to_inline_schema(of)
+
+                 end
+
+        description ? result.merge(description: description) : result
+      end
+
+      def collect_schemas_from_block(&)
+        collect_schema_block(&).schemas
+      end
+
+      def collect_schema_block(&block)
+        schema_block = SchemaBlock.new([], {})
+        schema_builder = self
+
+        context = Object.new
+
+        # Dynamically create methods for all schema builders
+        schema_builder.methods.grep(/_schema$/).each do |schema_method|
+          type_name = schema_method.to_s.sub(/_schema$/, "")
+
+          context.define_singleton_method(type_name) do |_name = nil, **options, &blk|
+            schema_block.schemas << schema_builder.send(schema_method, **options, &blk)
+          end
+        end
+
+        context.define_singleton_method(:contains) do |min: nil, max: nil, &blk|
+          schema_block.keywords.merge!({
+            contains: schema_builder.send(:collect_schemas_from_block, &blk).first,
+            minContains: min,
+            maxContains: max
+          }.compact)
+        end
+
+        # The two boolean schemas: true accepts every value, false accepts none
+        context.define_singleton_method(:any_schema) do
+          schema_block.schemas << true
+        end
+
+        context.define_singleton_method(:no_schema) do
+          schema_block.schemas << false
+        end
+
+        context.define_singleton_method(:raw) do |schema|
+          schema_block.schemas << schema
+        end
+
+        context.define_singleton_method(:content_schema) do |&blk|
+          schema_block.keywords[:contentSchema] = schema_builder.send(:collect_schemas_from_block, &blk).first
+        end
+
+        # Annotations and core keywords set here describe the schema the block belongs to,
+        # not the schemas declared inside it
+        ANNOTATIONS.merge(CORE_KEYWORDS).each do |name, keyword|
+          context.define_singleton_method(name) do |value|
+            schema_block.keywords[keyword] = value
+          end
+        end
+
+        # Allow Schema classes to be accessed in the context
+        context.define_singleton_method(:const_missing) do |name|
+          const_get(name) if const_defined?(name)
+        end
+
+        context.instance_eval(&block)
+        schema_block
+      end
+
+      def schema_class_to_inline_schema(schema_class_or_instance)
+        # Handle both Schema classes and Schema instances
+        schema_class = if schema_class_or_instance.is_a?(Class)
+                         schema_class_or_instance
+                       else
+                         schema_class_or_instance.class
+                       end
+
+        # Directly convert schema class to inline object schema
+        {
+          type: "object",
+          properties: schema_class.properties,
+          required: schema_class.required_properties,
+          additionalProperties: schema_class.additional_properties
+        }.tap do |schema|
+          # For instances, prefer instance description over class description
+          description = if schema_class_or_instance.is_a?(Class)
+                          schema_class.description
+                        else
+                          schema_class_or_instance.instance_variable_get(:@description) || schema_class.description
+                        end
+
+          schema[:description] = description if description
+
+          merge_schema_keywords(schema, schema_class)
+        end
+      end
+    end
+  end
+end

data/lib/schematist/dsl/utilities.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    module Utilities
+      # Schema definition and reference methods
+      def define(name, &)
+        sub_schema = Class.new(Schema)
+        sub_schema.class_eval(&)
+
+        schema = {
+          type: "object",
+          properties: sub_schema.properties,
+          required: sub_schema.required_properties,
+          additionalProperties: sub_schema.additional_properties
+        }
+
+        merge_schema_keywords(schema, sub_schema)
+
+        definitions[name] = schema
+      end
+
+      def object_keywords
+        @object_keywords ||= {}
+      end
+
+      # Constrains the names of properties matching a pattern, as JSON Schema patternProperties
+      def keys_matching(pattern, &block)
+        pattern = pattern.source if pattern.is_a?(Regexp)
+
+        object_keywords[:patternProperties] ||= {}
+        object_keywords[:patternProperties][pattern] = collect_schemas_from_block(&block).first
+      end
+
+      # Constrains every property name, as JSON Schema propertyNames
+      def keys(&block)
+        object_keywords[:propertyNames] = collect_schemas_from_block(&block).first
+      end
+
+      def reference(schema_name)
+        if schema_name == :root
+          {"$ref" => "#"}
+        else
+          {"$ref" => "#/$defs/#{schema_name}"}
+        end
+      end
+
+      private
+
+      # Merges everything a schema class collects beyond its properties: annotations, core keywords,
+      # key constraints, conditionals. Annotations are defaults, so an option passed to the enclosing
+      # builder wins over them.
+      def merge_schema_keywords(schema, schema_class)
+        schema.replace(schema_class.annotations.merge(schema))
+        schema.merge!(schema_class.core_keywords)
+        schema.merge!(schema_class.object_keywords)
+        merge_conditions(schema, schema_class)
+      end
+
+      def add_property(name, definition, required:, requires: nil)
+        property_name = name.to_sym
+
+        properties[property_name] = definition
+        if required
+          required_properties << property_name unless required_properties.include?(property_name)
+        else
+          required_properties.delete(property_name)
+        end
+
+        if requires
+          builder = ConditionalBuilder.new
+          builder.requires(*Array(requires))
+          dependencies[name.to_s] = builder
+        end
+
+        nil
+      end
+
+      def primitive_type?(type)
+        type.is_a?(Symbol) && PRIMITIVE_TYPES.include?(type)
+      end
+
+      def schema_class?(type)
+        (type.is_a?(Class) && type < Schema) || type.is_a?(Schema)
+      end
+    end
+  end
+end

data/lib/schematist/dsl.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    include SchemaBuilders
+    include PrimitiveTypes
+    include ComplexTypes
+    include Conditionals
+    include Utilities
+  end
+end

data/lib/schematist/errors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Schematist
+  # Base error class for all schema-related errors
+  class Error < StandardError; end
+
+  # Raised when an invalid schema type is specified
+  class InvalidSchemaTypeError < Error
+    def initialize(type)
+      super("Unknown schema type: #{type}")
+    end
+  end
+
+  # Raised when an invalid array type is specified
+  class InvalidArrayTypeError < Error; end
+
+  # Raised when an invalid object type is specified
+  class InvalidObjectTypeError < Error; end
+
+  # Raised when schema definition is invalid
+  class InvalidSchemaError < Error; end
+
+  # Raised when schema validation fails
+  class ValidationError < Error; end
+
+  # Raised when maximum limits are exceeded
+  class LimitExceededError < Error; end
+end