versponse 0.1.0 → 0.2.0

data/lib/versponse/properties/base.rb

@@ -0,0 +1,325 @@
+# frozen_string_literal: true
+
+module Versponse
+  # Property types of the DSL
+  module Properties
+    # Shared behaviour of every property: output key, value source, condition and schema keywords
+    #
+    # @api private
+    class Base
+      # Schema allowing null next to a referenced schema
+      NULL_SCHEMA = {"type" => "null"}.freeze
+
+      # Null in OpenAPI 3.0, which has no null type: validators read nullable only beside a type or enum
+      NULL_SCHEMA_30 = {"nullable" => true, "enum" => [nil].freeze}.freeze
+
+      # JSON Schema and OpenAPI keywords a property takes as options (camelized), besides x- extensions.
+      # type, required, nullable, discriminator and $ref come from the DSL itself.
+      SCHEMA_KEYWORDS = %w[
+        title description default examples example deprecated readOnly writeOnly externalDocs xml $comment
+        enum const format pattern minLength maxLength contentMediaType contentEncoding contentSchema
+        minimum maximum exclusiveMinimum exclusiveMaximum multipleOf
+        items prefixItems contains minContains maxContains minItems maxItems uniqueItems unevaluatedItems
+        properties patternProperties additionalProperties unevaluatedProperties propertyNames
+        minProperties maxProperties dependentRequired dependentSchemas
+        allOf anyOf oneOf not if then else
+      ].freeze
+
+      # @return [Array<String>] keywords this property type writes itself, so they can't be options
+      def self.written_keywords = [].freeze
+
+      # @return [Boolean] true for properties whose subtree can render with its own context (context: option)
+      def self.context_option? = false
+
+      # @return [Boolean] true for properties whose nil values a default: or the class's on_nil replaces
+      def self.default_option? = false
+
+      # Options the DSL reads itself, suggested for typos
+      DSL_OPTIONS = %w[map nullable if unless context default on_error].freeze
+
+      # @return [Symbol] property name, used to read the value
+      attr_reader :name
+      # @return [String] key in the output and the schema
+      attr_reader :key
+      # @return [String, nil] source path given with map:
+      attr_reader :map
+      # @return [Proc, nil] value block called with (object, context)
+      attr_reader :block
+      # @return [Versponse::Condition, nil] if:/unless: condition
+      attr_reader :condition
+      # @return [Hash{String => Object}] camelized JSON Schema keywords
+      attr_reader :schema_options
+      # @return [Versponse::ContextOverride::Merge, Versponse::ContextOverride::Call, nil] context of the subtree
+      attr_reader :context_override
+      # @return [Symbol, #call, nil] the property's own on_error: policy
+      attr_reader :on_error
+
+      # @param name [Symbol, String] property name and output key
+      # @param block [Proc, nil] value block
+      # @param options [Hash] map:, nullable:, if:, unless: and JSON Schema keywords in snake_case
+      # @raise [Versponse::DefinitionError] when options conflict
+      def initialize(name:, block: nil, **options)
+        @name = name.to_sym
+        @key = name.to_s.freeze
+        @block = block
+        @map = options.delete(:map)&.to_s
+        @nullable = options.delete(:nullable) || false
+        @condition = Condition.build(options.delete(:if), options.delete(:unless))
+        context = options.delete(:context)
+        raise DefinitionError, "#{key}: context: only works on reference, collection, object and one_of" unless context.nil? || self.class.context_option?
+
+        @context_override = ContextOverride.build(context, key: @key)
+        @on_error = options.delete(:on_error)
+        check_on_error! unless @on_error.nil?
+        parse_default!(options)
+        check_options!(options)
+        @schema_options = Naming.camelize_keys(options)
+        check_keywords!(options)
+      end
+
+      # @return [Boolean] true when the key is emitted only under a condition (so it is not required)
+      def conditional?
+        !condition.nil?
+      end
+
+      # @return [Boolean] true when null is allowed
+      def nullable?
+        @nullable
+      end
+
+      # Sets the value block declared with `source { |object, context| ... }` inside a container
+      #
+      # @param block [Proc] value block
+      # @raise [Versponse::DefinitionError] when map: is also given or source is declared twice
+      def source=(block)
+        raise DefinitionError, "#{key}: use either source or map:, not both" if map
+        raise DefinitionError, "#{key}: source is already declared" if @block
+
+        @block = block
+      end
+
+      # A copy under another name, used by `reference property:`. A map: or block replaces the
+      # source; without either the copy keeps its own source (its map:, block, or original name).
+      #
+      # @param name [Symbol, String] new name and output key
+      # @param map [String, nil] replacement map:
+      # @param block [Proc, nil] replacement value block
+      # @param condition [Versponse::Condition, nil] condition of the copy (the original's is dropped)
+      # @param context_override [Versponse::ContextOverride::Merge, Versponse::ContextOverride::Call, nil] replaces the
+      #   copy's context: when given (only for properties that take context:)
+      # @return [Versponse::Properties::Base] the copy
+      def renamed(name:, map:, block:, condition:, context_override: nil)
+        dup.tap { |copy| copy.rename(name:, map:, block:, condition:, context_override:) }
+      end
+
+      # @param context [Versponse::SchemaContext] schema generation context
+      # @return [Hash] JSON Schema of the property
+      def schema(context)
+        raise NotImplementedError
+      end
+
+      # @param version [String] requested version name, used by nested classes
+      # @param formatters [Hash{String => #call}] formatters by JSON Schema format, for the compiling class and version
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [#call] compiled plan step
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        raise NotImplementedError
+      end
+
+      # @param version [String] canonical version name
+      # @param prefix [Array<String>] output keys leading to this property
+      # @param stack [Array<Array(Class, Symbol)>] classes and views being walked, to stop recursion
+      # @return [Array<Array(Array<String>, Array<Class>)>] expandable paths under this property, each with the
+      #   classes it renders
+      def expandable_entries(version:, prefix:, stack:)
+        []
+      end
+
+      # @return [Boolean] true when a request may expand the association under this property
+      def expandable_path?
+        false
+      end
+
+      # @param version [String] canonical version name
+      # @return [Array<Versponse::Properties::Base>] properties one path segment below this one
+      def path_children(version)
+        []
+      end
+
+      # @param version [String] canonical version name
+      # @return [Versponse::Properties::Base] the property a path segment resolves to (self, or a reused copy)
+      def path_target(version)
+        self
+      end
+
+      # @return [Array<Array(Class, Symbol, String)>] Versponse classes this property renders, with their view and
+      #   this property's key, for {Versponse::Internals#check_references!}
+      def reference_targets
+        []
+      end
+
+      protected
+
+      # @param name [Symbol, String] new name and output key
+      # @param map [String, nil] replacement map:
+      # @param block [Proc, nil] replacement value block
+      # @param condition [Versponse::Condition, nil] condition of the copy
+      # @param context_override [Versponse::ContextOverride::Merge, Versponse::ContextOverride::Call, nil] replaces the
+      #   copy's context: when given
+      # @return [void]
+      # @raise [Versponse::DefinitionError] for a context_override on a property that doesn't take context:
+      def rename(name:, map:, block:, condition:, context_override: nil)
+        replace_source(map, block)
+        @name = name.to_sym
+        @key = name.to_s.freeze
+        @condition = condition
+        return if context_override.nil?
+        raise DefinitionError, "#{key}: context: only applies when the reused property is a reference, collection, object or one_of" unless self.class.context_option?
+
+        @context_override = context_override
+      end
+
+      private
+
+      # A map: or block replaces the source; without either, keep the original name as the source
+      def replace_source(map, block)
+        if map || block
+          @map = map
+          @block = block
+        elsif @map.nil? && @block.nil?
+          @map = @key
+        end
+      end
+
+      def check_options!(options)
+        raise DefinitionError, "#{key}: expandable: only works on reference, collection item: and one_of" if options.key?(:expandable)
+        raise DefinitionError, "#{key}: required is computed automatically, use if: or unless: for optional keys" if options.key?(:required)
+        raise DefinitionError, "#{key}: use either a block or map:, not both" if block && map
+      end
+
+      def check_keywords!(options, label: key, written_keywords: self.class.written_keywords)
+        written = options.keys.find { |option| written_keywords.include?(Naming.camelize(option)) }
+        raise DefinitionError, "#{label}: #{written}: is written by #{dsl_name} itself" if written
+
+        unknown = options.keys.reject do |option|
+          keyword = Naming.camelize(option)
+          SCHEMA_KEYWORDS.include?(keyword) || keyword.start_with?("x-")
+        end
+        return if unknown.empty?
+
+        raise DefinitionError, "#{label}: unknown options #{unknown.map { |option| "#{option}:" }.join(", ")}#{suggestions(unknown)}"
+      end
+
+      def dsl_name
+        self.class.name.split("::").last.gsub(/([a-z])([A-Z])/, '\\1_\\2').downcase.delete_prefix("item_")
+      end
+
+      def suggestions(unknown)
+        dictionary = DSL_OPTIONS + SCHEMA_KEYWORDS.map { |keyword| keyword.gsub(/[A-Z]/) { |letter| "_#{letter.downcase}" } }
+        checker = DidYouMean::SpellChecker.new(dictionary:)
+        found = unknown.filter_map { |option| checker.correct(option.to_s).first }
+        found.empty? ? " (use JSON Schema keywords in snake_case, or x- extensions)" : " (did you mean #{found.map { |option| "#{option}:" }.join(", ")}?)"
+      end
+
+      def extractor
+        Extractors.for(name:, map:, block:)
+      end
+
+      def check_on_error!
+        raise DefinitionError, "#{key}: on_error: must be :raise, :nullify, :omit or a callable taking (error, object, key, context)" unless ErrorPolicy.valid?(@on_error)
+        raise DefinitionError, "#{key}: on_error: :nullify needs nullable: true" if @on_error == :nullify && !nullable?
+        raise DefinitionError, "#{key}: on_error: :omit needs if: or unless:" if @on_error == :omit && !conditional?
+      end
+
+      # A static default stays in the options, so the schema writes it; a callable one only renders. default: nil
+      # means no default.
+      def parse_default!(options)
+        return unless options.key?(:default)
+        raise DefinitionError, "#{key}: default: only works on field, enum and array" unless self.class.default_option?
+
+        default = options.delete(:default)
+        return if default.nil?
+
+        @default = default.respond_to?(:call) ? Callable.normalize(default) : DeepFreeze.call(default)
+        options[:default] = @default unless default.respond_to?(:call)
+      end
+
+      # Called by the subclasses once their schema is complete. Scalar schemas never read SchemaContext#version.
+      def check_default!
+        return if @default.nil? || @default.respond_to?(:call)
+
+        require "json_schemer"
+        schema = schema(SchemaContext.new(version: nil, validation: true))
+        return if JSONSchemer.schema(schema, meta_schema: Versponse.configuration.json_schema_uri, regexp_resolver: "ecma").valid?(@default)
+
+        raise DefinitionError, "#{key}: default: #{@default.inspect} doesn't match the property's schema"
+      end
+
+      # @return [#call, nil] (object, context) callable for nil values: default:, else the class's on_nil
+      def nil_fallback(policies)
+        return unless self.class.default_option?
+        return @default if @default.respond_to?(:call)
+
+        unless @default.nil?
+          value = @default
+          # A Hash or Array default is the caller's to change, so each render gets its own copy
+          return ->(_object, _context) { DeepCopy.call(value) } if DeepCopy.container?(value)
+
+          return ->(_object, _context) { value }
+        end
+        on_nil = policies.on_nil
+        key = @key
+        ->(object, context) { on_nil.call(object, key, context) } if on_nil
+      end
+
+      # A plain field (no block, condition, path map:, default: or on_nil) compiles to the specialized Steps::Read
+      def value_step(formatter: nil, policies: ClassPolicies::NONE)
+        fallback = nil_fallback(policies)
+        return (formatter ? Steps::ReadFormatted : Steps::Read).new(key:, name: map || name, formatter:) if fallback.nil? && plain_read?
+
+        reader = fallback ? Extractors::Fallback.new(extractor, fallback) : extractor
+        Steps::Value.new(key:, extractor: reader, condition:, formatter:)
+      end
+
+      def plain_read?
+        block.nil? && condition.nil? && (map.nil? || !(map == "." || map.include?("/") || map.empty?))
+      end
+
+      def nullable_type(schema, context = nil)
+        return schema unless nullable?
+
+        # const allows one value, so null joins it in an enum
+        schema = schema.except("const").merge("enum" => [schema["const"], nil]) if schema.key?("const")
+        return schema.merge("nullable" => true) if nullable_keyword?(context)
+
+        schema.merge("type" => [*schema["type"], "null"])
+      end
+
+      # OpenAPI 3.0 documents write null with the nullable keyword; validation schemas always use the 3.1 forms
+      def nullable_keyword?(context)
+        Versponse.configuration.nullable_keyword? && !context&.validation?
+      end
+
+      # OpenAPI 3.0 documents (where nullable_keyword? holds) have no type arrays, so a union becomes an anyOf
+      def openapi30_union?(type, context)
+        type.is_a?(::Array) && nullable_keyword?(context)
+      end
+
+      def nullable_ref(schema, context)
+        return schema unless nullable?
+
+        {"anyOf" => [schema, null_schema(context)]}
+      end
+
+      def nullable_choice(keyword, schemas, context)
+        return {keyword => schemas} unless nullable?
+
+        {keyword => [*schemas, null_schema(context)]}
+      end
+
+      def null_schema(context)
+        nullable_keyword?(context) ? NULL_SCHEMA_30 : NULL_SCHEMA
+      end
+    end
+  end
+end

data/lib/versponse/properties/collection.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # An array of objects: inline (block of properties) or of another class (item:)
+    #
+    # @api private
+    class Collection < Base
+      # @return [Array<String>] keywords this property type writes itself
+      def self.written_keywords = %w[items properties required].freeze
+
+      # @return [Boolean] true: the subtree can render with its own context
+      def self.context_option? = true
+
+      include Container
+
+      # @param item [Class, nil] class implementing the reference protocol
+      # @param view [Symbol] view of item
+      # @param expandable [Boolean] render items collapsed unless expanded (item: must be a Versponse class)
+      # @param options [Hash] see {Base#initialize}
+      # @raise [Versponse::DefinitionError] when item does not implement the protocol, expandable: without a Versponse item:,
+      #   or context: with a non-Versponse item:
+      def initialize(item: nil, view: :default, expandable: false, **options)
+        super(**options)
+        raise DefinitionError, "#{key}: item: must respond to to_ref and to_validation_schema" if item && !(item.respond_to?(:to_ref) && item.respond_to?(:to_validation_schema))
+        raise DefinitionError, "#{key}: expandable: needs item: with a Versponse class (mark an item one_of with expandable: instead)" if expandable && !References.versponse?(item)
+
+        @item = item
+        @view = view.to_sym
+        @expandable = expandable
+        raise DefinitionError, "#{key}: context: needs a Versponse class to render with it" if context_override && @item && !References.versponse?(@item)
+      end
+
+      # @return [Boolean] true when items render collapsed unless expanded
+      def expandable?
+        @expandable
+      end
+
+      # @param property [Versponse::Properties::Base] item property of an inline collection
+      # @return [Versponse::Properties::Base] the property
+      # @raise [Versponse::DefinitionError] for a collection with item: or with an item one_of
+      def add(property)
+        raise DefinitionError, "#{key}: a collection with item: can not declare properties" if @item
+        raise DefinitionError, "#{key}: one_of must be the only declaration in a collection block" if @items_one_of
+
+        super
+      end
+
+      # @param one_of [Versponse::Properties::ItemOneOf] unnamed one_of typing every item
+      # @return [Versponse::Properties::ItemOneOf] the one_of
+      # @raise [Versponse::DefinitionError] when the collection has item:, properties or another one_of
+      def items_one_of=(one_of)
+        raise DefinitionError, "#{key}: a collection with item: can not declare one_of" if @item
+        raise DefinitionError, "#{key}: one_of must be the only declaration in a collection block" if @items_one_of || !child_properties.empty?
+
+        @items_one_of = one_of
+      end
+
+      # @param context [Versponse::SchemaContext] schema generation context
+      # @return [Hash] array schema
+      def schema(context)
+        nullable_type({"type" => "array", "items" => items_schema(context)}.merge(schema_options), context)
+      end
+
+      # @param version [String] canonical version name
+      # @param formatters [Hash{String => #call}] formatters by JSON Schema format, for the compiling class and version
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::Nested, Versponse::Steps::Value] compiled step; items of non-Versponse classes pass through
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        plan = items_plan(version, formatters, policies)
+        return value_step if plan.nil?
+
+        collapse_if = (References.collapse_if(@item, version) if expandable?)
+        Steps::Nested.new(key:, extractor:, condition:, plan:, collapsed_plan: items_collapsed_plan(version), collapse_if:, collection: true, context_override:)
+      end
+
+      # @param version [String] canonical version name
+      # @param prefix [Array<String>] output keys leading here
+      # @param stack [Array<Array(Class, Symbol)>] classes and views being walked
+      # @return [Array<Array(Array<String>, Array<Class>)>] entries of the items
+      def expandable_entries(version:, prefix:, stack:)
+        return @items_one_of.expandable_entries(version:, prefix:, stack:) if @items_one_of
+        return super unless @item
+
+        path = prefix + [key]
+        (expandable? ? [[path, [@item]]] : []) + References.nested_entries(@item, view: @view, version:, prefix: path, stack:)
+      end
+
+      # @return [Boolean] true when the items (or the item one_of) are expandable
+      def expandable_path?
+        expandable? || (@items_one_of&.expandable? || false)
+      end
+
+      # @param version [String] canonical version name
+      # @return [Array<Versponse::Properties::Base>] properties one segment below the items
+      def path_children(version)
+        return @items_one_of.path_children(version) if @items_one_of
+        return super unless @item
+
+        References.versponse?(@item) ? @item.versponse.resolve(version).properties_for(@view) : []
+      end
+
+      # @return [Array<Array(Class, Symbol, String)>] the item class, the item one_of's variants, or the inline children's targets
+      def reference_targets
+        return @items_one_of.reference_targets if @items_one_of
+        return (References.versponse?(@item) ? [[@item, @view, key]] : []) if @item
+
+        super
+      end
+
+      private
+
+      def items_schema(context)
+        return {"anyOf" => References.expandable_schemas(@item, view: @view, context:, key:)} if expandable?
+        return References.schema(@item, view: @view, property: nil, context:, key:) if @item
+        return @items_one_of.schema(context) if @items_one_of
+
+        inline_schema(context)
+      end
+
+      def items_collapsed_plan(version)
+        return References.collapsed_plan(@item, version) if expandable?
+
+        @items_one_of.collapsed_dispatcher(version) if @items_one_of&.expandable?
+      end
+
+      def items_plan(version, formatters, policies)
+        return @items_one_of.dispatcher(version) if @items_one_of
+        return inline_plan(version, formatters, policies) if @item.nil?
+
+        References.lazy_plan(@item, version:, view: @view, key:) if References.versponse?(@item)
+      end
+    end
+  end
+end

data/lib/versponse/properties/const.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # A constant value, always the same
+    #
+    # @api private
+    class Const < Base
+      # @return [Array<String>] keywords this property type writes itself
+      def self.written_keywords = %w[const enum].freeze
+
+      # @param value [Object] constant value
+      # @param options [Hash] see {Base#initialize}
+      # @raise [Versponse::DefinitionError] with a block, map: or nullable: (a response constant never reads the object),
+      #   or a value with no JSON type
+      def initialize(value:, **options)
+        super(**options)
+        raise DefinitionError, "#{key}: const never reads the object, so it takes no map: or block (use enum or field for computed values)" if block || map
+        raise DefinitionError, "#{key}: const always renders its value, so it can't be nullable (use enum with nil)" if nullable?
+        raise DefinitionError, "#{key}: const value #{value.inspect} has no JSON type#{" (Symbols render as Symbols, use Strings)" if value.is_a?(::Symbol)}" unless JSONValue.json?(value)
+
+        @constant = DeepFreeze.call(value)
+      end
+
+      # @return [Object] the frozen constant value
+      def value
+        @constant
+      end
+
+      # @param _context [Versponse::SchemaContext] unused
+      # @return [Hash] const schema, or a one-value enum for OpenAPI 3.0
+      def schema(_context)
+        keyword = Versponse.configuration.const_keyword? ? {"const" => @constant} : {"enum" => [@constant]}
+        keyword.merge(schema_options)
+      end
+
+      # @param version [String] unused by constants
+      # @param formatters [Hash{String => #call}] unused by constants
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::Const] compiled step
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        Steps::Const.new(key:, value: @constant, condition:)
+      end
+    end
+  end
+end

data/lib/versponse/properties/container.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # Child properties of an inline object or collection
+    #
+    # @api private
+    module Container
+      # @param property [Versponse::Properties::Base] child property
+      # @return [Versponse::Properties::Base] the property
+      def add(property)
+        (@properties ||= {})[property.key] = property
+      end
+
+      # @param version [String] canonical version name
+      # @param prefix [Array<String>] output keys leading to this container
+      # @param stack [Array<Array(Class, Symbol)>] classes and views being walked
+      # @return [Array<Array(Array<String>, Array<Class>)>] entries of the child properties
+      def expandable_entries(version:, prefix:, stack:)
+        child_properties.flat_map { |property| property.expandable_entries(version:, prefix: prefix + [key], stack:) }
+      end
+
+      # @param version [String] canonical version name
+      # @return [Array<Versponse::Properties::Base>] the child properties
+      def path_children(version)
+        child_properties
+      end
+
+      # @return [Array<Array(Class, Symbol, String)>] the reference targets of the child properties
+      def reference_targets
+        child_properties.flat_map(&:reference_targets)
+      end
+
+      private
+
+      def child_properties
+        @properties&.values || []
+      end
+
+      def inline_plan(version, formatters, policies)
+        properties = FieldOrder.call(child_properties)
+        Plan.new(label: key, steps: properties.map { |property| property.step(version:, formatters:, policies:) },
+          recoveries: ErrorPolicy.recoveries(properties, policies, version))
+      end
+
+      def inline_schema(context)
+        ObjectSchema.build(FieldOrder.call(child_properties), context)
+      end
+    end
+  end
+end

data/lib/versponse/properties/enum.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Versponse
+  module Properties
+    # A value from a fixed list
+    #
+    # @api private
+    class Enum < Base
+      # @return [Array<String>] keywords this property type writes itself
+      def self.written_keywords = %w[enum].freeze
+
+      # @return [Boolean] true: nil values can be replaced
+      def self.default_option? = true
+
+      # Ruby classes a value of each built-in type must be
+      VALUE_CLASSES = {
+        "string" => [::String],
+        "number" => [::Numeric],
+        "integer" => [::Integer],
+        "boolean" => [::TrueClass, ::FalseClass],
+        "object" => [::Hash]
+      }.freeze
+
+      # @param values [Array] allowed values, each of the type
+      # @param type [Symbol, String, Array<Symbol, String>, nil] a built-in type, a custom one (only its base type is used, its
+      #   schema options would duplicate or contradict the values) or a union of built-in types; nil infers it from the values
+      # @param options [Hash] see {Base#initialize}
+      # @raise [Versponse::DefinitionError] when values is empty, type is unknown or can't be inferred, or a value isn't of the type
+      def initialize(values:, type: nil, **options)
+        super(**options)
+        raise DefinitionError, "#{key}: values must be a non-empty Array" unless values.is_a?(::Array) && !values.empty?
+
+        @values = values.dup.freeze
+        @type = type.nil? ? inferred_type : FieldType.resolve(type, key).first
+        check_values!
+        check_default!
+      end
+
+      # @param context [Versponse::SchemaContext, nil] schema generation context
+      # @return [Hash] JSON Schema of the enum; nullable adds nil to the values, and "null" to type (or nullable: true
+      #   in OpenAPI 3.0 documents, where a type union is an anyOf of single types)
+      def schema(context)
+        options = {"enum" => nullable? ? @values | [nil] : @values}.merge(schema_options)
+        return FieldType.openapi30_union(@type, options, nullable: nullable?) if openapi30_union?(@type, context)
+
+        nullable_type({"type" => @type}.merge(options), context)
+      end
+
+      # @param version [String] unused by scalars
+      # @param formatters [Hash{String => #call}] unused by enums
+      # @param policies [Versponse::ClassPolicies] class-level on_nil and on_error of the compiling class
+      # @return [Versponse::Steps::Value] compiled step
+      def step(version:, formatters:, policies: ClassPolicies::NONE)
+        value_step(policies:)
+      end
+
+      private
+
+      # Like verquest's query coercion: one type per value class, number when integers and floats mix
+      def inferred_type
+        types = @values.compact.map do |value|
+          json_type(value) || raise(DefinitionError, "#{key}: can't infer the enum type from #{value.inspect}, pass type:#{" (Symbols render as Symbols, use Strings)" if value.is_a?(::Symbol)}")
+        end.uniq
+        raise DefinitionError, "#{key}: can't infer the enum type from nil alone, pass type:" if types.empty?
+
+        types.delete("integer") if types.include?("number")
+        (types.size == 1) ? types.first : FieldType.union(types, key)
+      end
+
+      def json_type(value)
+        case value
+        when ::String then "string"
+        when ::Integer then "integer"
+        when ::Numeric then "number"
+        when true, false then "boolean"
+        when ::Hash then "object"
+        end
+      end
+
+      def check_values!
+        types = Array(@type)
+        invalid = @values.find { |value| !(value.nil? && nullable?) && !matches?(value, types) }
+        return if invalid.nil? && (nullable? || !@values.include?(nil))
+
+        raise DefinitionError, "#{key}: enum value #{invalid.inspect} is not of type #{types.join(" or ")}"
+      end
+
+      def matches?(value, types)
+        types.any? { |type| VALUE_CLASSES.fetch(type).any? { |klass| value.is_a?(klass) } }
+      end
+    end
+  end
+end