openapi_parser 2.3.1 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3129b448382c0b36273808c25a197c9264ec23d4729c93f8c5594375cf16cc5
-  data.tar.gz: 57aa683478c58dd684995e326687ef8e187a08fe4818e707812b1484a3e6e13b
+  metadata.gz: d03c17295ee85e0cf17e06e83f6e28c1bed8028e7de1ae68574e2d69ad6160b2
+  data.tar.gz: 6cae65df5bab290cff5d7c014d181f5eb631e153863f5eac82c7ce460d224dd9
 SHA512:
-  metadata.gz: 1e99aa6ea5ae7234c886c17c6d48bdeb75480db7698057aa77825301c0151caa986b59f6cc0b5a5a421c135fb47fb513e6440b6a3a18db4dae2f25620001f05a
-  data.tar.gz: b5886770b412d8d73fe30a07039fcf76773880874e4762bd704e6ab3c4b545ade6ed722ebd010717af42c9e09e4e3ccd4fc0f53954c9d98bd24e64583ed99e48
+  metadata.gz: 3074ba856acef7b064c0b1d2cf7b79b274e00766d90797ddfe95626f19ea09571fe72e2346e397bc7cac18f986959c659b62de2933b42d0a403074d5e41a73a9
+  data.tar.gz: 7c373bb6e33c6bf221b7d3dbc41f89951109b8adc7bc9aef362eb5c820733e5c1203279c272e92e96b1cd4a6278b09f70aab5ffee809cf635e9253d6e616bb06

data/.github/workflows/ci.yaml

@@ -20,7 +20,7 @@ jobs:
           - ruby-head
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v5
+    - uses: actions/checkout@v7
     - uses: ruby/setup-ruby@v1
       with:
         ruby-version: ${{ matrix.ruby }}

data/.ruby-version

@@ -1 +1 @@
-3.1.0
+3.3.12

data/CHANGELOG.md

@@ -1,5 +1,36 @@
 ## Unreleased
 
+## 2.4.0 (2026-10-14)
+* support `components.pathItems` so `$ref`s into it resolve, unblocking OpenAPI 3.1 documents that use reusable path items
+* support array-form `type` (3.1) in value validation
+* support root-level `jsonSchemaDialect` (OpenAPI 3.1) in the parse layer
+* support `prefixItems` (OpenAPI 3.1) with positional tuple validation
+* support `contentMediaType` (OpenAPI 3.1) in the parse layer
+* support `contentEncoding` (OpenAPI 3.1) in the parse layer
+* add `SpecValidator` with `strict_specification_version` config (`:silent` / `:warn` / `:raise`) to detect version mismatches between declared OpenAPI version and actual field usage
+  * `ContentEncodingIn30`: detect `contentEncoding` usage in 3.0 documents (3.1 addition)
+  * `ContentMediaTypeIn30`: detect `contentMediaType` usage in 3.0 documents (3.1 addition)
+  * `PrefixItemsIn30`: detect `prefixItems` usage in 3.0 documents (3.1 addition)
+  * `JsonSchemaDialectIn30`: detect root-level `jsonSchemaDialect` usage in 3.0 documents (3.1 addition)
+  * `TypeArrayIn30`: detect array-form `type` usage in 3.0 documents (3.1 form)
+  * `NullableDeprecation`: detect `nullable` usage in 3.1 documents (removed in 3.1)
+  * `ExampleSingularDeprecation`: detect singular `example` on schemas in 3.1 documents (deprecated in 3.1)
+  * `PathItemsIn30`: detect `components.pathItems` usage in 3.0 documents (3.1 addition)
+  * `ExclusiveMinimum` / `ExclusiveMaximum`: detect 3.0 Boolean vs 3.1 numeric form mismatch
+  * `TypeNullIn30`: detect `type: "null"` usage in 3.0 documents (3.1 primitive)
+  * `WebhooksIn30`: detect root-level `webhooks` usage in 3.0 documents (3.1 addition)
+  * `ConstIn30`: detect `const` usage in 3.0 documents (3.1 addition)
+  * `DynamicRefIn30`: detect `$dynamicRef` usage in 3.0 documents (3.1 addition)
+  * `DynamicAnchorIn30`: detect `$dynamicAnchor` usage in 3.0 documents (3.1 addition)
+  * `ContentSchemaIn30`: detect `contentSchema` usage in 3.0 documents (3.1 addition)
+* expose the declared version as `OpenAPI#openapi_version` (a `Gem::Version`, or nil when the field is missing or malformed) so `SpecValidator` rules compare version ranges; a 3.2 document is checked by the 3.1-or-later rules
+* support 3.1-style numeric `exclusiveMinimum` / `exclusiveMaximum` in value validation (standalone bound, not a Boolean modifier on `minimum` / `maximum`)
+* support `type: "null"` (3.1 primitive) in value validation
+* support root-level `webhooks` (OpenAPI 3.1) in the parse layer
+* support `const` (OpenAPI 3.1) with exact-equality value validation
+* support `contentSchema` (OpenAPI 3.1) in the parse layer
+* coerce String values into array-form `type` (3.1) when `coerce_value` is on, so params like `type: [integer, "null"]` accept `"5"`
+
 ## 2.3.1 (2025-11-14)
 * add optional date coercion with behavior matching existing datetime coercion
 

data/lib/openapi_parser/config.rb

@@ -41,6 +41,18 @@ class OpenAPIParser::Config
     @config.fetch(:strict_reference_validation, false)
   end
 
+  KNOWN_STRICT_SPECIFICATION_VERSION_VALUES = %i[silent warn raise].freeze
+
+  # @return [Symbol] :silent / :warn / :raise
+  def strict_specification_version
+    value = @config.fetch(:strict_specification_version, :silent)
+    unless KNOWN_STRICT_SPECIFICATION_VERSION_VALUES.include?(value)
+      warn("[OpenAPIParser] unknown strict_specification_version: #{value.inspect}, falling back to :silent")
+      return :silent
+    end
+    value
+  end
+
   def validate_header
     @config.fetch(:validate_header, true)
   end

data/lib/openapi_parser/schema_validator/array_validator.rb

@@ -11,10 +11,14 @@ class OpenAPIParser::SchemaValidator
       value, err = validate_unique_items(value, schema)
       return [nil, err] if err
 
-      # array type have an schema in items property
+      # 3.1: prefixItems positionally validates the leading N elements.
+      # Elements past the prefix fall back to schema.items, matching how
+      # JSON Schema 2020-12 layers the two keywords.
+      prefix_schemas = schema.prefix_items || []
       items_schema = schema.items
-      coerced_values = value.map do |v|
-        coerced, err = validatable.validate_schema(v, items_schema)
+      coerced_values = value.each_with_index.map do |v, idx|
+        sub_schema = prefix_schemas[idx] || items_schema
+        coerced, err = validatable.validate_schema(v, sub_schema)
         return [nil, err] if err
 
         coerced

data/lib/openapi_parser/schema_validator/minimum_maximum.rb

@@ -4,8 +4,10 @@ class OpenAPIParser::SchemaValidator
     # @param [Object] value
     # @param [OpenAPIParser::Schemas::Schema] schema
     def check_minimum_maximum(value, schema)
-      include_min_max = schema.minimum || schema.maximum
-      return [value, nil] unless include_min_max
+      has_min_or_max = schema.minimum || schema.maximum
+      has_numeric_exclusive_min = schema.exclusiveMinimum.is_a?(Numeric)
+      has_numeric_exclusive_max = schema.exclusiveMaximum.is_a?(Numeric)
+      return [value, nil] unless has_min_or_max || has_numeric_exclusive_min || has_numeric_exclusive_max
 
       validate(value, schema)
       [value, nil]
@@ -18,16 +20,27 @@ class OpenAPIParser::SchemaValidator
       def validate(value, schema)
         reference = schema.object_reference
 
+        # 3.1: exclusiveMinimum is a standalone numeric bound.
+        if schema.exclusiveMinimum.is_a?(Numeric) && value <= schema.exclusiveMinimum
+          raise OpenAPIParser::LessThanExclusiveMinimum.new(value, reference)
+        end
+
         if schema.minimum
-          if schema.exclusiveMinimum && value <= schema.minimum
+          # 3.0: exclusiveMinimum is a Boolean modifier on `minimum`.
+          if schema.exclusiveMinimum == true && value <= schema.minimum
             raise OpenAPIParser::LessThanExclusiveMinimum.new(value, reference)
           elsif value < schema.minimum
             raise OpenAPIParser::LessThanMinimum.new(value, reference)
           end
         end
 
+        # 3.1: standalone numeric upper bound, mirror of exclusiveMinimum.
+        if schema.exclusiveMaximum.is_a?(Numeric) && value >= schema.exclusiveMaximum
+          raise OpenAPIParser::MoreThanExclusiveMaximum.new(value, reference)
+        end
+
         if schema.maximum
-          if schema.exclusiveMaximum && value >= schema.maximum
+          if schema.exclusiveMaximum == true && value >= schema.maximum
             raise OpenAPIParser::MoreThanExclusiveMaximum.new(value, reference)
           elsif value > schema.maximum
             raise OpenAPIParser::MoreThanMaximum.new(value, reference)

data/lib/openapi_parser/schema_validator/nil_validator.rb

@@ -4,6 +4,10 @@ class OpenAPIParser::SchemaValidator
     # @param [OpenAPIParser::Schemas::Schema] schema
     def coerce_and_validate(value, schema, **_keyword_args)
       return [value, nil] if schema.nullable
+      # 3.1: `type: "null"` makes nil the only valid value for the schema.
+      return [value, nil] if schema.type == 'null'
+      # 3.1: `type: [..., "null"]` lets nil coexist with another primitive.
+      return [value, nil] if schema.type.is_a?(Array) && schema.type.include?('null')
 
       [nil, OpenAPIParser::NotNullError.new(schema.object_reference)]
     end

data/lib/openapi_parser/schema_validator/type_mismatch_validator.rb

@@ -0,0 +1,11 @@
+class OpenAPIParser::SchemaValidator
+  # Emits a ValidateError unconditionally. Used when the dispatcher has
+  # already decided that no primitive applies to the value, e.g.:
+  # - schema declares `type: "null"` and the value is non-nil (3.1)
+  # - schema declares `type: [t1, t2, ...]` and the value matches none
+  class TypeMismatchValidator < Base
+    def coerce_and_validate(value, schema, **_keyword_args)
+      OpenAPIParser::ValidateError.build_error_result(value, schema)
+    end
+  end
+end

data/lib/openapi_parser/schema_validator.rb

@@ -13,6 +13,7 @@ require_relative 'schema_validator/any_of_validator'
 require_relative 'schema_validator/all_of_validator'
 require_relative 'schema_validator/one_of_validator'
 require_relative 'schema_validator/nil_validator'
+require_relative 'schema_validator/type_mismatch_validator'
 require_relative 'schema_validator/unspecified_type_validator'
 
 class OpenAPIParser::SchemaValidator
@@ -74,6 +75,15 @@ class OpenAPIParser::SchemaValidator
   def validate_schema(value, schema, **keyword_args)
     return [value, nil] unless schema
 
+    # 3.1: `const` pins the value to exactly that constant. Checked before
+    # type dispatch so it applies uniformly across primitives. Detection
+    # uses raw_schema so an intentional `const: null` is honored.
+    if schema.respond_to?(:raw_schema) && schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('const')
+      return [nil, OpenAPIParser::ValidateError.new(value, "const #{schema.const.inspect}", schema.object_reference)] if value != schema.const
+    end
+
+    return coerce_into_type_array(value, schema, **keyword_args) if coerce_into_type_array?(value, schema)
+
     if (v = validator(value, schema))
       if keyword_args.empty?
         return v.coerce_and_validate(value, schema)
@@ -103,7 +113,25 @@ class OpenAPIParser::SchemaValidator
       return one_of_validator if schema.one_of
       return nil_validator if value.nil?
 
-      case schema.type
+      # 3.1: pick the type from an Array whose primitive class matches the
+      # value, then dispatch as if it were a single-type schema. If nothing
+      # matches we still pick a candidate so the relevant validator emits
+      # a sensible error rather than silently accepting via the unspecified
+      # fallback.
+      effective_type = schema.type
+      if effective_type.is_a?(Array)
+        matched = pick_array_type(value, effective_type)
+        return type_mismatch_validator if matched.nil?
+
+        effective_type = matched
+      end
+
+      validator_for_type(effective_type)
+    end
+
+    # @return [OpenAPIParser::SchemaValidator::Base]
+    def validator_for_type(type)
+      case type
       when 'string'
         string_validator
       when 'integer'
@@ -116,11 +144,64 @@ class OpenAPIParser::SchemaValidator
         object_validator
       when 'array'
         array_validator
+      when 'null'
+        # 3.1: only nil values are valid here. nil is handled earlier in
+        # this method, so a non-nil value reaching this branch is a type
+        # mismatch that should fail validation.
+        type_mismatch_validator
       else
         unspecified_type_validator
       end
     end
 
+    # 3.1: request params arrive as Strings, so `type: [integer, "null"]`
+    # never matches by class. When coercing, try each listed type instead.
+    # @return [Boolean]
+    def coerce_into_type_array?(value, schema)
+      return false unless @coerce_value && value.is_a?(String)
+      return false if schema.any_of || schema.all_of || schema.one_of
+
+      schema.type.is_a?(Array) && pick_array_type(value, schema.type).nil?
+    end
+
+    # 3.1: returns the first listed type that coerces, or the first type's error.
+    # @return [Array] coerced value and error
+    def coerce_into_type_array(value, schema, **keyword_args)
+      first_error = nil
+      (schema.type - ['null']).each do |type|
+        v = validator_for_type(type)
+        coerced, err = if keyword_args.empty?
+                         v.coerce_and_validate(value, schema)
+                       else
+                         v.coerce_and_validate(value, schema, **keyword_args)
+                       end
+        return [coerced, nil] if err.nil?
+
+        first_error ||= err
+      end
+      return [nil, first_error] if first_error
+
+      type_mismatch_validator.coerce_and_validate(value, schema)
+    end
+
+    def type_mismatch_validator
+      @type_mismatch_validator ||= OpenAPIParser::SchemaValidator::TypeMismatchValidator.new(self, @coerce_value)
+    end
+
+    def pick_array_type(value, types)
+      types.find do |t|
+        case t
+        when 'string'  then value.is_a?(String)
+        when 'integer' then value.is_a?(Integer)
+        when 'number'  then value.is_a?(Numeric)
+        when 'boolean' then value == true || value == false
+        when 'array'   then value.is_a?(Array)
+        when 'object'  then value.is_a?(Hash)
+        when 'null'    then value.nil?
+        end
+      end
+    end
+
     def string_validator
       @string_validator ||= OpenAPIParser::SchemaValidator::StringValidator.new(self, @allow_empty_date_and_datetime, @coerce_value, @datetime_coerce_class, @date_coerce_class)
     end

data/lib/openapi_parser/schemas/components.rb

@@ -24,5 +24,9 @@ module OpenAPIParser::Schemas
     # @!attribute [r] headers
     #   @return [Hash{String => Header}, nil] header objects
     openapi_attr_hash_object :headers, Header, reference: true
+
+    # @!attribute [r] path_items
+    #   @return [Hash{String => PathItem}, nil] path item objects (OpenAPI 3.1+)
+    openapi_attr_hash_object :path_items, PathItem, reference: true, schema_key: :pathItems
   end
 end

data/lib/openapi_parser/schemas/openapi.rb

@@ -21,6 +21,18 @@ module OpenAPIParser::Schemas
     #   @return [String, nil]
     openapi_attr_values :openapi
 
+    # Declared OpenAPI version as a comparable value.
+    # A prerelease tag is dropped ("3.1.0-rc1" => 3.1.0) because it does not
+    # change which version's rules the document is written against.
+    # @return [Gem::Version, nil] nil when the field is missing or not a
+    #   major.minor[.patch] version string
+    def openapi_version
+      return nil unless openapi.is_a?(String)
+      return nil unless openapi.match?(/\A\d+\.\d+/) && Gem::Version.correct?(openapi)
+
+      Gem::Version.new(openapi).release
+    end
+
     # @!attribute [r] paths
     #   @return [Paths, nil]
     openapi_attr_object :paths, Paths, reference: false
@@ -33,6 +45,14 @@ module OpenAPIParser::Schemas
     #   @return [Info, nil]
     openapi_attr_object :info, Info, reference: false
 
+    # @!attribute [r] webhooks
+    #   @return [Hash{String => PathItem}, nil] webhook path items (OpenAPI 3.1+)
+    openapi_attr_hash_object :webhooks, PathItem, reference: true
+
+    # @!attribute [r] json_schema_dialect
+    #   @return [String, nil] dialect URI for embedded JSON Schemas (OpenAPI 3.1+)
+    openapi_attr_value :json_schema_dialect, schema_key: :jsonSchemaDialect
+
     # @return [OpenAPIParser::RequestOperation, nil]
     def request_operation(http_method, request_path)
       OpenAPIParser::RequestOperation.create(http_method, request_path, @path_item_finder, @config)

data/lib/openapi_parser/schemas/schema.rb

@@ -71,7 +71,10 @@ module OpenAPIParser::Schemas
                         :type,
                         :nullable,
                         :example,
-                        :deprecated
+                        :deprecated,
+                        :const,
+                        :contentMediaType,
+                        :contentEncoding
 
     # @!attribute [r] read_only
     #   @return [Boolean, nil]
@@ -97,6 +100,14 @@ module OpenAPIParser::Schemas
     #   @return [Schema, nil]
     openapi_attr_object :items, Schema, reference: true
 
+    # @!attribute [r] prefix_items
+    #   @return [Array<Schema>, nil] tuple-style positional schemas (OpenAPI 3.1+)
+    openapi_attr_list_object :prefix_items, Schema, reference: true, schema_key: :prefixItems
+
+    # @!attribute [r] content_schema
+    #   @return [Schema, nil] schema describing the content payload (OpenAPI 3.1+)
+    openapi_attr_object :content_schema, Schema, reference: true, schema_key: :contentSchema
+
     # @!attribute [r] properties
     #   @return [Hash{String => Schema}, nil]
     openapi_attr_hash_object :properties, Schema, reference: true

data/lib/openapi_parser/spec_validator/rule.rb

@@ -0,0 +1,68 @@
+module OpenAPIParser
+  class SpecValidator
+    class Rule
+      def self.rule_name
+        name
+          .split('::')
+          .last
+          .gsub(/([A-Z])/) { "_#{Regexp.last_match(1).downcase}" }
+          .sub(/^_/, '')
+          .to_sym
+      end
+
+      def initialize(version)
+        @version = version
+      end
+
+      # @return [Gem::Version, nil] declared OpenAPI version, nil when unknown
+      attr_reader :version
+
+      def check(_root)
+        raise NotImplementedError
+      end
+
+      # @param [String] boundary like '3.1'
+      # @return [Boolean] false when the version is unknown
+      def version_before?(boundary)
+        !version.nil? && version < Gem::Version.new(boundary)
+      end
+
+      # @param [String] boundary like '3.1'
+      # @return [Boolean] false when the version is unknown
+      def version_at_least?(boundary)
+        !version.nil? && version >= Gem::Version.new(boundary)
+      end
+
+      private
+
+        def violation(path:, message:)
+          OpenAPIParser::SpecViolation.new(
+            message: message,
+            path: path,
+            rule_name: self.class.rule_name,
+          )
+        end
+
+        def each_schema(root, &block)
+          return enum_for(:each_schema, root) unless block
+
+          visited = {}
+          walk(root, visited) do |node|
+            yield node if node.is_a?(OpenAPIParser::Schemas::Schema)
+          end
+        end
+
+        def walk(node, visited, &block)
+          return unless node.respond_to?(:_openapi_all_child_objects)
+          return if visited[node.object_id]
+
+          visited[node.object_id] = true
+          block.call(node)
+
+          node._openapi_all_child_objects.each_value do |child|
+            walk(child, visited, &block)
+          end
+        end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/const_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `const` is a JSON Schema 2020-12 keyword adopted by OpenAPI 3.1.
+      # 3.0 does not recognize it. Detection inspects raw_schema so a
+      # literal `const: null` (deliberate) still flags.
+      class ConstIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('const')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`const` is a 3.1 addition (from JSON Schema 2020-12); 3.0 has no equivalent',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/content_encoding_in_30.rb

@@ -0,0 +1,24 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `contentEncoding` is a JSON Schema 2020-12 annotation adopted by
+      # 3.1. Metadata only, no runtime side-effects.
+      class ContentEncodingIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('contentEncoding')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`contentEncoding` is a 3.1 addition (from JSON Schema 2020-12); 3.0 has no equivalent',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/content_media_type_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `contentMediaType` is a JSON Schema 2020-12 annotation adopted by
+      # 3.1. It is metadata, so it has no runtime side-effects; we only
+      # report version mismatches.
+      class ContentMediaTypeIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('contentMediaType')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`contentMediaType` is a 3.1 addition (from JSON Schema 2020-12); 3.0 has no equivalent',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/content_schema_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `contentSchema` is a JSON Schema 2020-12 annotation adopted by 3.1.
+      # The parse layer accepts it permissively; this rule reports the
+      # version mismatch on 3.0 documents.
+      class ContentSchemaIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('contentSchema')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`contentSchema` is a 3.1 addition (from JSON Schema 2020-12); 3.0 has no equivalent',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/dynamic_anchor_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `$dynamicAnchor` is the companion of `$dynamicRef` from JSON Schema
+      # 2020-12, declaring the dynamic resolution point. 3.0 has nothing
+      # equivalent; the rule flags it on 3.0 documents.
+      class DynamicAnchorIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('$dynamicAnchor')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`$dynamicAnchor` is a 3.1 addition (from JSON Schema 2020-12); 3.0 has no equivalent',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/dynamic_ref_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `$dynamicRef` is a JSON Schema 2020-12 referencing mechanism that
+      # 3.1 adopted. 3.0 does not recognize it. The parse layer keeps the
+      # value as raw schema data; this rule reports the version mismatch.
+      class DynamicRefIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('$dynamicRef')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`$dynamicRef` is a 3.1 addition (from JSON Schema 2020-12); 3.0 only knows `$ref`',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/example_singular_deprecation.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # In 3.1 the singular `example` keyword on a Schema is deprecated in
+      # favor of the JSON Schema `examples` array. The field is still
+      # allowed but discouraged, so we report it as a violation.
+      class ExampleSingularDeprecation < Rule
+        def check(root)
+          return [] unless version_at_least?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('example')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: 'singular `example` on a Schema is deprecated in 3.1; use the `examples` array',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/exclusive_maximum.rb

@@ -0,0 +1,32 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      class ExclusiveMaximum < Rule
+        def check(root)
+          return [] if version.nil?
+
+          violations = []
+          each_schema(root) do |schema|
+            value = schema.exclusiveMaximum
+            next if value.nil?
+
+            if version_before?('3.1')
+              if value.is_a?(Numeric)
+                violations << violation(
+                  path: schema.object_reference,
+                  message: 'numeric exclusiveMaximum is a 3.1-only form; in 3.0 use a Boolean modifier paired with `maximum`',
+                )
+              end
+            elsif value == true || value == false
+              violations << violation(
+                path: schema.object_reference,
+                message: 'Boolean exclusiveMaximum is a 3.0-only form; in 3.1 use a standalone numeric bound',
+              )
+            end
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/exclusive_minimum.rb

@@ -0,0 +1,32 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      class ExclusiveMinimum < Rule
+        def check(root)
+          return [] if version.nil?
+
+          violations = []
+          each_schema(root) do |schema|
+            value = schema.exclusiveMinimum
+            next if value.nil?
+
+            if version_before?('3.1')
+              if value.is_a?(Numeric)
+                violations << violation(
+                  path: schema.object_reference,
+                  message: 'numeric exclusiveMinimum is a 3.1-only form; in 3.0 use a Boolean modifier paired with `minimum`',
+                )
+              end
+            elsif value == true || value == false
+              violations << violation(
+                path: schema.object_reference,
+                message: 'Boolean exclusiveMinimum is a 3.0-only form; in 3.1 use a standalone numeric bound',
+              )
+            end
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/json_schema_dialect_in_30.rb

@@ -0,0 +1,19 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `jsonSchemaDialect` is a 3.1 root-level addition; 3.0 has no
+      # equivalent.
+      class JsonSchemaDialectIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+          return [] unless root.raw_schema.is_a?(Hash) && root.raw_schema.key?('jsonSchemaDialect')
+
+          [violation(
+            path: '#/jsonSchemaDialect',
+            message: '`jsonSchemaDialect` is a 3.1 root-level addition; 3.0 documents have no such field',
+          )]
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/nullable_deprecation.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `nullable` is a 3.0 keyword that 3.1 removed in favor of
+      # `type: [..., "null"]`. The field's mere presence on a 3.1 document
+      # is a spec violation, regardless of true/false.
+      class NullableDeprecation < Rule
+        def check(root)
+          return [] unless version_at_least?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('nullable')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`nullable` was removed in 3.1; use `type: [..., "null"]` instead',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/path_items_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `components.pathItems` is a 3.1 addition. The parse layer accepts it
+      # in 3.0 documents permissively; this rule reports the version
+      # mismatch.
+      class PathItemsIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          components = root.components
+          return [] unless components
+
+          raw = components.raw_schema
+          return [] unless raw.is_a?(Hash) && raw.key?('pathItems')
+
+          [violation(
+            path: "#{components.object_reference}/pathItems",
+            message: '`components.pathItems` is a 3.1 addition; 3.0 documents should not declare it',
+          )]
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/prefix_items_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `prefixItems` is JSON Schema 2020-12's positional tuple keyword.
+      # 3.1 adopts it; 3.0 has no equivalent and parsing it is a spec
+      # mismatch the validator should report.
+      class PrefixItemsIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('prefixItems')
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`prefixItems` is a 3.1 addition (from JSON Schema 2020-12); 3.0 has no equivalent',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/type_array_in_30.rb

@@ -0,0 +1,25 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # 3.1 lets `type` be an Array of primitive type names (e.g.
+      # `["string", "null"]`). 3.0 only allowed a single String, so the
+      # array form on a 3.0 document is a spec violation.
+      class TypeArrayIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.type.is_a?(Array)
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`type` as an Array of primitive names is a 3.1 addition; 3.0 expects a single type String',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/type_null_in_30.rb

@@ -0,0 +1,26 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `type: "null"` was added by 3.1; 3.0 only allowed the original six
+      # primitive type names. The parse layer accepts the literal anyway,
+      # so we report the mismatch here. Array-form types like
+      # `["string", "null"]` are covered by a separate rule.
+      class TypeNullIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.type == 'null'
+
+            violations << violation(
+              path: schema.object_reference,
+              message: '`type: "null"` is a 3.1 addition; 3.0 documents have no such primitive',
+            )
+          end
+          violations
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/rules/webhooks_in_30.rb

@@ -0,0 +1,18 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # `webhooks` is a 3.1 root-level addition; 3.0 has no equivalent.
+      class WebhooksIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+          return [] unless root.raw_schema.is_a?(Hash) && root.raw_schema.key?('webhooks')
+
+          [violation(
+            path: '#/webhooks',
+            message: '`webhooks` is a 3.1 root-level addition; 3.0 documents have no such field',
+          )]
+        end
+      end
+    end
+  end
+end

data/lib/openapi_parser/spec_validator/spec_violation.rb

@@ -0,0 +1,11 @@
+module OpenAPIParser
+  class SpecValidator
+    SpecViolation = Struct.new(:message, :path, :rule_name, keyword_init: true) do
+      def to_s
+        "[#{rule_name}] #{path}: #{message}"
+      end
+    end
+  end
+
+  SpecViolation = SpecValidator::SpecViolation
+end

data/lib/openapi_parser/spec_validator.rb

@@ -0,0 +1,85 @@
+require_relative 'spec_validator/spec_violation'
+require_relative 'spec_validator/rule'
+require_relative 'spec_validator/rules/exclusive_minimum'
+require_relative 'spec_validator/rules/exclusive_maximum'
+require_relative 'spec_validator/rules/content_encoding_in_30'
+require_relative 'spec_validator/rules/content_media_type_in_30'
+require_relative 'spec_validator/rules/prefix_items_in_30'
+require_relative 'spec_validator/rules/json_schema_dialect_in_30'
+require_relative 'spec_validator/rules/type_array_in_30'
+require_relative 'spec_validator/rules/path_items_in_30'
+require_relative 'spec_validator/rules/nullable_deprecation'
+require_relative 'spec_validator/rules/example_singular_deprecation'
+require_relative 'spec_validator/rules/type_null_in_30'
+require_relative 'spec_validator/rules/webhooks_in_30'
+require_relative 'spec_validator/rules/const_in_30'
+require_relative 'spec_validator/rules/dynamic_ref_in_30'
+require_relative 'spec_validator/rules/dynamic_anchor_in_30'
+require_relative 'spec_validator/rules/content_schema_in_30'
+
+module OpenAPIParser
+  class SpecViolationError < OpenAPIError
+    attr_reader :violations
+
+    def initialize(violations)
+      @violations = violations
+      super(nil)
+    end
+
+    def message
+      @violations.map(&:to_s).join("\n")
+    end
+  end
+
+  class SpecValidator
+    def self.run(root)
+      new(root).run
+    end
+
+    def self.run!(root, policy:)
+      return if policy == :silent
+
+      violations = run(root)
+      return if violations.empty?
+
+      case policy
+      when :warn
+        violations.each { |v| warn(v.to_s) }
+      when :raise
+        raise OpenAPIParser::SpecViolationError.new(violations)
+      end
+    end
+
+    def initialize(root)
+      @root = root
+      @version = root.openapi_version
+    end
+
+    def run
+      rules.flat_map { |klass| klass.new(@version).check(@root) }
+    end
+
+    private
+
+      def rules
+        [
+          Rules::ExclusiveMinimum,
+          Rules::ExclusiveMaximum,
+          Rules::ContentEncodingIn30,
+          Rules::ContentMediaTypeIn30,
+          Rules::PrefixItemsIn30,
+          Rules::JsonSchemaDialectIn30,
+          Rules::TypeArrayIn30,
+          Rules::PathItemsIn30,
+          Rules::NullableDeprecation,
+          Rules::ExampleSingularDeprecation,
+          Rules::TypeNullIn30,
+          Rules::WebhooksIn30,
+          Rules::ConstIn30,
+          Rules::DynamicRefIn30,
+          Rules::DynamicAnchorIn30,
+          Rules::ContentSchemaIn30,
+        ]
+      end
+  end
+end

data/lib/openapi_parser/version.rb

@@ -1,3 +1,3 @@
 module OpenAPIParser
-  VERSION = '2.3.1'.freeze
+  VERSION = '2.4.0'.freeze
 end

data/lib/openapi_parser.rb

@@ -15,6 +15,7 @@ require 'openapi_parser/request_operation'
 require 'openapi_parser/schema_validator'
 require 'openapi_parser/parameter_validator'
 require 'openapi_parser/reference_expander'
+require 'openapi_parser/spec_validator'
 
 module OpenAPIParser
   class << self
@@ -99,6 +100,8 @@ module OpenAPIParser
           path_item.set_path_item_to_operation
         end
 
+        OpenAPIParser::SpecValidator.run!(root, policy: config.strict_specification_version)
+
         root
       end
   end

data/sig/openapi_parser/config.rbs

@@ -15,6 +15,8 @@ module OpenAPIParser
     def expand_reference: -> bool
     def strict_response_validation: -> bool
     def strict_reference_validation: -> bool
+    KNOWN_STRICT_SPECIFICATION_VERSION_VALUES: Array[Symbol]
+    def strict_specification_version: -> (:silent | :warn | :raise)
     def validate_header: -> bool
     def request_validator_options: -> OpenAPIParser::SchemaValidator::Options
     def response_validate_options: -> OpenAPIParser::SchemaValidator::ResponseValidateOptions

data/sig/openapi_parser/schema_validator.rbs

@@ -27,6 +27,9 @@ module OpenAPIParser
 
     private
     def validator: (Object value, OpenAPIParser::Schemas::Schema schema) -> [OpenAPIParser::SchemaValidator::Base, OpenAPIParser::validate_error]
+    def validator_for_type: (String? type) -> OpenAPIParser::SchemaValidator::Base
+    def coerce_into_type_array?: (Object value, OpenAPIParser::Schemas::Schema schema) -> bool
+    def coerce_into_type_array: (Object value, OpenAPIParser::Schemas::Schema schema, **untyped) -> [Object, OpenAPIParser::validate_error]
     def string_validator: -> OpenAPIParser::SchemaValidator::StringValidator
     def integer_validator: -> OpenAPIParser::SchemaValidator::IntegerValidator
     def float_validator: -> OpenAPIParser::SchemaValidator::FloatValidator

data/sig/openapi_parser/spec_validator.rbs

@@ -0,0 +1,109 @@
+module OpenAPIParser
+  class SpecViolationError < OpenAPIError
+    @violations: Array[OpenAPIParser::SpecValidator::SpecViolation]
+    attr_reader violations: Array[OpenAPIParser::SpecValidator::SpecViolation]
+
+    def initialize: (Array[OpenAPIParser::SpecValidator::SpecViolation] violations) -> void
+    def message: () -> String
+  end
+
+  class SpecValidator
+    @root: OpenAPIParser::Schemas::OpenAPI
+    @version: Gem::Version?
+
+    def self.run: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecViolation]
+    def self.run!: (OpenAPIParser::Schemas::OpenAPI root, policy: (:silent | :warn | :raise)) -> void
+    def initialize: (OpenAPIParser::Schemas::OpenAPI root) -> void
+    def run: () -> Array[SpecViolation]
+    private def rules: () -> Array[singleton(Rule)]
+
+    class SpecViolation < ::Struct[untyped]
+      attr_accessor message: String
+      attr_accessor path: String
+      attr_accessor rule_name: Symbol
+      def to_s: () -> String
+    end
+
+    class Rule
+      @version: Gem::Version?
+      attr_reader version: Gem::Version?
+
+      def self.rule_name: () -> Symbol
+      def initialize: (Gem::Version? version) -> void
+      def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecViolation]
+      def version_before?: (String boundary) -> bool
+      def version_at_least?: (String boundary) -> bool
+      private def violation: (path: String, message: String) -> SpecViolation
+      private def each_schema: (untyped root) ?{ (untyped) -> void } -> untyped
+      private def walk: (untyped node, Hash[Integer, bool] visited) { (untyped) -> void } -> void
+    end
+
+    module Rules
+      class ExclusiveMinimum < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class ExclusiveMaximum < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class ContentEncodingIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class ContentMediaTypeIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class PrefixItemsIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class JsonSchemaDialectIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class TypeArrayIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class PathItemsIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class NullableDeprecation < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class ExampleSingularDeprecation < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class TypeNullIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class WebhooksIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class ConstIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class DynamicRefIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class DynamicAnchorIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+
+      class ContentSchemaIn30 < Rule
+        def check: (OpenAPIParser::Schemas::OpenAPI root) -> Array[SpecValidator::SpecViolation]
+      end
+    end
+  end
+
+  SpecViolation: singleton(SpecValidator::SpecViolation)
+end

data/sig/openapi_parser.rbs

@@ -14,6 +14,8 @@ module OpenAPIParser
   module Schemas
     class OpenAPI
       def initialize: (Hash[bot, bot] hash, untyped config, uri: OpenAPIParser::readable_uri?, schema_registry: Hash[bot, bot]) -> OpenAPIParser::Schemas::OpenAPI
+      def openapi: () -> String?
+      def openapi_version: () -> Gem::Version?
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openapi_parser
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.4.0
 platform: ruby
 authors:
 - ota42y
@@ -188,6 +188,7 @@ files:
 - lib/openapi_parser/schema_validator/options.rb
 - lib/openapi_parser/schema_validator/properties_number.rb
 - lib/openapi_parser/schema_validator/string_validator.rb
+- lib/openapi_parser/schema_validator/type_mismatch_validator.rb
 - lib/openapi_parser/schema_validator/unspecified_type_validator.rb
 - lib/openapi_parser/schemas.rb
 - lib/openapi_parser/schemas/base.rb
@@ -207,6 +208,25 @@ files:
 - lib/openapi_parser/schemas/response.rb
 - lib/openapi_parser/schemas/responses.rb
 - lib/openapi_parser/schemas/schema.rb
+- lib/openapi_parser/spec_validator.rb
+- lib/openapi_parser/spec_validator/rule.rb
+- lib/openapi_parser/spec_validator/rules/const_in_30.rb
+- lib/openapi_parser/spec_validator/rules/content_encoding_in_30.rb
+- lib/openapi_parser/spec_validator/rules/content_media_type_in_30.rb
+- lib/openapi_parser/spec_validator/rules/content_schema_in_30.rb
+- lib/openapi_parser/spec_validator/rules/dynamic_anchor_in_30.rb
+- lib/openapi_parser/spec_validator/rules/dynamic_ref_in_30.rb
+- lib/openapi_parser/spec_validator/rules/example_singular_deprecation.rb
+- lib/openapi_parser/spec_validator/rules/exclusive_maximum.rb
+- lib/openapi_parser/spec_validator/rules/exclusive_minimum.rb
+- lib/openapi_parser/spec_validator/rules/json_schema_dialect_in_30.rb
+- lib/openapi_parser/spec_validator/rules/nullable_deprecation.rb
+- lib/openapi_parser/spec_validator/rules/path_items_in_30.rb
+- lib/openapi_parser/spec_validator/rules/prefix_items_in_30.rb
+- lib/openapi_parser/spec_validator/rules/type_array_in_30.rb
+- lib/openapi_parser/spec_validator/rules/type_null_in_30.rb
+- lib/openapi_parser/spec_validator/rules/webhooks_in_30.rb
+- lib/openapi_parser/spec_validator/spec_violation.rb
 - lib/openapi_parser/version.rb
 - openapi_parser.gemspec
 - sig/openapi_parser.rbs
@@ -217,6 +237,7 @@ files:
 - sig/openapi_parser/schema_validators/base.rbs
 - sig/openapi_parser/schema_validators/options.rbs
 - sig/openapi_parser/schemas/base.rbs
+- sig/openapi_parser/spec_validator.rbs
 - sig/openapi_parser/version.rbs
 - sig/types.rbs
 - sig/wip_types.rbs
@@ -238,7 +259,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: OpenAPI3 parser
 test_files: []