schematist 0.1.0 → 1.1.0

data/lib/schematist/dsl/complex_types.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    module ComplexTypes
+      def object(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, object_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def array(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, array_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def tuple(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, tuple_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def any_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, any_of_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def one_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, one_of_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def all_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, all_of_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def none_of(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(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 = nil, required: true, requires: nil)
+        return self_schema(name) && nil if schema.nil? && name.is_a?(Hash)
+
+        add_property_or_self(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,108 @@
+# frozen_string_literal: true
+
+module Schematist
+  module DSL
+    # A branch of a conditional. Backed by a schema class, so anything you can write in a schema
+    # you can write in a branch: nested objects, arrays, composition, references, raw fragments.
+    # `requires` and `validates` stay as shorthands for the two common cases.
+    class ConditionalBuilder
+      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 initialize
+        @schema_class = Class.new(Schema)
+      end
+
+      # Requires properties without saying anything else about them
+      def requires(*fields)
+        required.concat(fields.map(&:to_s))
+      end
+
+      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
+        return @schema_class.self_schema.dup if @schema_class.self_schema
+
+        schema = {}
+        schema[:properties] = branch_properties if branch_properties.any?
+        schema[:required] = branch_required if branch_required.any?
+        schema[:additionalProperties] = @schema_class.additional_properties if additional_properties_set?
+
+        @schema_class.send(:merge_schema_keywords, schema, @schema_class)
+      end
+
+      def empty?
+        to_schema.empty?
+      end
+
+      def required_fields
+        branch_required
+      end
+
+      # A branch that only lists required properties becomes dependentRequired rather than
+      # dependentSchemas, which is the smaller thing to say when it is all you mean.
+      def validations_empty?
+        to_schema.keys == [:required]
+      end
+
+      # Everything else is the ordinary schema DSL, evaluated against the branch's schema class
+      def method_missing(name, ...)
+        return super unless @schema_class.respond_to?(name)
+
+        @schema_class.public_send(name, ...)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @schema_class.respond_to?(name) || super
+      end
+
+      private
+
+      def branch_properties
+        declared = @schema_class.properties.transform_keys(&:to_s)
+        validations.merge(declared)
+      end
+
+      def branch_required
+        (@schema_class.required_properties.map(&:to_s) + required).uniq
+      end
+
+      def additional_properties_set?
+        @schema_class.instance_variable_defined?(:@additional_properties)
+      end
+
+      def required
+        @required ||= []
+      end
+
+      def validations
+        @validations ||= {}
+      end
+    end
+  end
+end

data/lib/schematist/dsl/conditional_context.rb

@@ -0,0 +1,27 @@
+# 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 otherwise(&block)
+        @else_builder.instance_eval(&block)
+      end
+
+      # Everything else describes the then branch
+      def method_missing(name, ...)
+        return super unless @then_builder.respond_to?(name)
+
+        @then_builder.public_send(name, ...)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @then_builder.respond_to?(name) || super
+      end
+    end
+  end
+end

data/lib/schematist/dsl/conditionals.rb

@@ -0,0 +1,84 @@
+# 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
+
+      # Matches on property values, or on any schema when one is passed explicitly:
+      #   given(status: "shipped") { ... }
+      #   given({required: %w[tax_id]}) { ... }
+      def given(condition = nil, **properties, &block)
+        raise ArgumentError, "given requires a condition" if condition.nil? && properties.empty?
+
+        if_schema = condition || {
+          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 = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, string_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def number(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, number_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def integer(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, integer_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def boolean(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(name, boolean_schema(description: description, **options, &block), required: required, requires: requires)
+      end
+
+      def null(name = nil, description: nil, required: true, requires: nil, **options, &block)
+        add_property_or_self(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,315 @@
+# 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, format: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({
+          type: "number",
+          description: description,
+          format: format,
+          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, format: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({
+          type: "integer",
+          description: description,
+          format: format,
+          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, enum: nil, const: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({type: "boolean", description: description, enum: enum, const: const}.compact, annotations, schema_block)
+      end
+
+      def null_schema(description: nil, enum: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block) if block
+
+        annotate({type: "null", description: description, enum: enum}.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, of: nil, min_items: nil, max_items: nil, unevaluated_items: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+        schemas = schema_block.schemas
+        tail = determine_array_items(of) if of
+
+        # A tuple is exactly its prefix unless you give it somewhere for the rest to go
+        closed = tail.nil? && unevaluated_items.nil? && max_items.nil?
+
+        annotate({
+          type: "array",
+          description: description,
+          prefixItems: schemas,
+          items: tail,
+          minItems: min_items || schemas.length,
+          maxItems: closed ? schemas.length : max_items,
+          unevaluatedItems: unevaluated_items
+        }.compact, annotations, schema_block)
+      end
+
+      def any_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+
+        annotate({
+          description: description,
+          anyOf: schema_block.schemas,
+          unevaluatedProperties: unevaluated_properties,
+          unevaluatedItems: unevaluated_items
+        }.compact, annotations, schema_block)
+      end
+
+      def one_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+
+        annotate({
+          description: description,
+          oneOf: schema_block.schemas,
+          unevaluatedProperties: unevaluated_properties,
+          unevaluatedItems: unevaluated_items
+        }.compact, annotations, schema_block)
+      end
+
+      def all_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: nil, **annotations, &block)
+        schema_block = collect_schema_block(&block)
+
+        annotate({
+          description: description,
+          allOf: schema_block.schemas,
+          unevaluatedProperties: unevaluated_properties,
+          unevaluatedItems: unevaluated_items
+        }.compact, annotations, schema_block)
+      end
+
+      def none_of_schema(description: nil, unevaluated_properties: nil, unevaluated_items: 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,
+          unevaluatedItems: unevaluated_items
+        }.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)
+        raise InvalidObjectTypeError, "An object needs a block or an `of:` schema to describe it." unless 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 = schema_for(sub_schema)
+          # The keyword wins over an annotation set inside the block
+          schema[:description] = description if description
+          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