openapi_parser 2.3.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7f08706ff7f3eeb957f73f1352879e4234c0c2cb5a2906a12ace5e75c0517d3
-  data.tar.gz: 9267f25fcfa1cb600b0373980a011086b2b70ceefba042658b4a20d80c57b851
+  metadata.gz: d03c17295ee85e0cf17e06e83f6e28c1bed8028e7de1ae68574e2d69ad6160b2
+  data.tar.gz: 6cae65df5bab290cff5d7c014d181f5eb631e153863f5eac82c7ce460d224dd9
 SHA512:
-  metadata.gz: 1a9213679b51be326c333e040f3de339d6aec2e1c74de0efa685f685da8846ca1b09926829177c62c4ebdc5a877b528919ad2a9a293179fe20d45cfd5f01e3c4
-  data.tar.gz: f9e3d895124ccfeb70fabc1a0ee22395fc38ff2c1447b6529d996adb5cedaa87b924028db4b07ee1e1aeabaab799906dfc488126e3cb8ac4439152ac34f4ff8d
+  metadata.gz: 3074ba856acef7b064c0b1d2cf7b79b274e00766d90797ddfe95626f19ea09571fe72e2346e397bc7cac18f986959c659b62de2933b42d0a403074d5e41a73a9
+  data.tar.gz: 7c373bb6e33c6bf221b7d3dbc41f89951109b8adc7bc9aef362eb5c820733e5c1203279c272e92e96b1cd4a6278b09f70aab5ffee809cf635e9253d6e616bb06

data/.github/workflows/ci.yaml

@@ -1,5 +1,7 @@
 name: ci
-on: [push]
+on:
+  - pull_request
+  - push
 jobs:
   test:
     strategy:
@@ -18,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,39 @@
 ## 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
+
 ## 2.3.0 (2025-10-01)
 * bump base64 dep
 * bump actions checkout dep

data/README.md

@@ -27,7 +27,7 @@ request_operation.path_params
 # => {"template_name"=>"1"}
 
 # coerce parameter
-root = OpenAPIParser.parse(YAML.load_file('open_api_3/schema.yml'), {coerce_value: true, datetime_coerce_class: DateTime})
+root = OpenAPIParser.parse(YAML.load_file('open_api_3/schema.yml'), {coerce_value: true, datetime_coerce_class: DateTime, date_coerce_class: Date})
 request_operation = root.request_operation(:get, '/string_params_coercer')
 request_operation.validate_request_parameter({'integer_1' => '1', 'datetime_string' => '2016-04-01T16:00:00+09:00'})
 # => {"integer_1"=>1, "datetime_string"=>#<DateTime: 2016-04-01T16:00:00+09:00 ((2457480j,25200s,0n),+32400s,2299161j)>

data/lib/openapi_parser/config.rb

@@ -19,6 +19,10 @@ class OpenAPIParser::Config
     @config[:datetime_coerce_class]
   end
 
+  def date_coerce_class
+    @config[:date_coerce_class]
+  end
+
   def coerce_value
     @config[:coerce_value]
   end
@@ -37,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
@@ -46,6 +62,7 @@ class OpenAPIParser::Config
     @request_validator_options ||= OpenAPIParser::SchemaValidator::Options.new(allow_empty_date_and_datetime: allow_empty_date_and_datetime,
                                                                                coerce_value: coerce_value,
                                                                                datetime_coerce_class: datetime_coerce_class,
+                                                                               date_coerce_class: date_coerce_class,
                                                                                validate_header: validate_header)
   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/options.rb

@@ -6,14 +6,17 @@ class OpenAPIParser::SchemaValidator
     #   @return [Boolean] coerce value option on/off
     # @!attribute [r] datetime_coerce_class
     #   @return [Object, nil] coerce datetime string by this Object class
+    # @!attribute [r] date_coerce_class
+    #   @return [Object, nil] coerce date string by this Object class
     # @!attribute [r] validate_header
     #   @return [Boolean] validate header or not
-    attr_reader :allow_empty_date_and_datetime, :coerce_value, :datetime_coerce_class, :validate_header
+    attr_reader :allow_empty_date_and_datetime, :coerce_value, :datetime_coerce_class, :validate_header, :date_coerce_class
 
-    def initialize(allow_empty_date_and_datetime: false, coerce_value: nil, datetime_coerce_class: nil, validate_header: true)
+    def initialize(allow_empty_date_and_datetime: false, coerce_value: nil, datetime_coerce_class: nil, validate_header: true, date_coerce_class: nil)
       @allow_empty_date_and_datetime = allow_empty_date_and_datetime
       @coerce_value = coerce_value
       @datetime_coerce_class = datetime_coerce_class
+      @date_coerce_class = date_coerce_class
       @validate_header = validate_header
     end
   end

data/lib/openapi_parser/schema_validator/string_validator.rb

@@ -2,10 +2,11 @@ class OpenAPIParser::SchemaValidator
   class StringValidator < Base
     include ::OpenAPIParser::SchemaValidator::Enumable
 
-    def initialize(validator, allow_empty_date_and_datetime, coerce_value, datetime_coerce_class)
+    def initialize(validator, allow_empty_date_and_datetime, coerce_value, datetime_coerce_class, date_coerce_class)
       super(validator, coerce_value)
       @allow_empty_date_and_datetime = allow_empty_date_and_datetime
       @datetime_coerce_class = datetime_coerce_class
+      @date_coerce_class = date_coerce_class
     end
 
     def coerce_and_validate(value, schema, **_keyword_args)
@@ -90,16 +91,18 @@ class OpenAPIParser::SchemaValidator
         return [nil, OpenAPIParser::InvalidDateFormat.new(value, schema.object_reference)] unless value =~ /^\d{4}-\d{2}-\d{2}$/
 
         begin
-          parsed_date = Date.iso8601(value)
+          if @date_coerce_class.nil?
+            # validate only
+            Date.iso8601(value)
+            [value, nil]
+          else
+            # validate and coerce
+            [@date_coerce_class.iso8601(value), nil]
+          end
         rescue ArgumentError
-          return [nil, OpenAPIParser::InvalidDateFormat.new(value, schema.object_reference)]
-        end
-
-        unless parsed_date.strftime('%Y-%m-%d') == value
-          return [nil, OpenAPIParser::InvalidDateFormat.new(value, schema.object_reference)]
+          # when rfc3339(value) failed
+          [nil, OpenAPIParser::InvalidDateFormat.new(value, schema.object_reference)]
         end
-
-        return [value, nil]
       end
 
       def validate_datetime_format(value, schema)

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
@@ -56,6 +57,7 @@ class OpenAPIParser::SchemaValidator
     @allow_empty_date_and_datetime = options.allow_empty_date_and_datetime
     @coerce_value = options.coerce_value
     @datetime_coerce_class = options.datetime_coerce_class
+    @date_coerce_class = options.date_coerce_class
   end
 
   # execute validate data
@@ -73,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)
@@ -102,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'
@@ -115,13 +144,66 @@ 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)
+      @string_validator ||= OpenAPIParser::SchemaValidator::StringValidator.new(self, @allow_empty_date_and_datetime, @coerce_value, @datetime_coerce_class, @date_coerce_class)
     end
 
     def integer_validator

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