openapi_parser 2.3.1 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3129b448382c0b36273808c25a197c9264ec23d4729c93f8c5594375cf16cc5
-  data.tar.gz: 57aa683478c58dd684995e326687ef8e187a08fe4818e707812b1484a3e6e13b
+  metadata.gz: e570c33d05a24e9b11a3f5b86f5321f895088a672d404df68f3d14b4d3f9fb8f
+  data.tar.gz: fadcedd0e7b7c5ce057f2b0fa36f313218f151ae524dd2290c1242fbdfca02da
 SHA512:
-  metadata.gz: 1e99aa6ea5ae7234c886c17c6d48bdeb75480db7698057aa77825301c0151caa986b59f6cc0b5a5a421c135fb47fb513e6440b6a3a18db4dae2f25620001f05a
-  data.tar.gz: b5886770b412d8d73fe30a07039fcf76773880874e4762bd704e6ab3c4b545ade6ed722ebd010717af42c9e09e4e3ccd4fc0f53954c9d98bd24e64583ed99e48
+  metadata.gz: 680325ae11c7dce38425d23c89918d3ce5cb768261dbd48f6d21c166ca0d89b2dbf9304297b2f754830f47cdf8d45dd2501371b396fe972957474e171f4b3b49
+  data.tar.gz: 27b757f70c102671ff1f2891918f5e7abb044796e280027b097214f4f0bbb2ff538b7f7c84d7d1bb7f1fc8b46b63591ad62e37985dab50ebb35c0603b854e92e

data/.github/workflows/ci.yaml

@@ -17,10 +17,11 @@ jobs:
           - "3.2"
           - "3.3"
           - "3.4"
+          - "4.0"
           - 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,45 @@
 ## Unreleased
 
+## 2.5.0 (2026-10-21)
+* add OpenAPI 3.2 `SpecValidator` rules
+  * `SelfBefore32`: detect `$self` usage in pre-3.2 documents (3.2 addition)
+* support root-level `$self` (OpenAPI 3.2) in the parse layer (`self_uri`); it is not yet used as the base URI for `$ref` resolution
+* support boolean schemas (OpenAPI 3.1): `true` accepts any value and `false` rejects any value with `FalseSchemaError`, instead of crashing the loader with `NoMethodError`
+* add `SpecValidator` rule `BooleanSchemaIn30`: detect boolean schemas in 3.0 documents (3.1 addition; `additionalProperties` is not affected)
+* coerce non-String values into array-form `type` (3.1) the same way as a single `type` when `coerce_value` is on, so `type: [integer, "null"]` handles a Float the same way as `type: integer`
+* stop truncating a Float with a fractional part in integer coercion (`coerce_value`): `1.5` for `type: integer` now fails instead of becoming `1`, while a Float with no fractional part, like `1.0`, is still converted
+
+## 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/errors.rb

@@ -38,6 +38,13 @@ module OpenAPIParser
     end
   end
 
+  # 3.1: raised for any value checked against the boolean schema `false`
+  class FalseSchemaError < OpenAPIError
+    def message
+      "#{@reference} does not allow any value"
+    end
+  end
+
   class NotExistRequiredKey < OpenAPIError
     def initialize(keys, reference)
       super(reference)

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/integer_validator.rb

@@ -21,6 +21,8 @@ class OpenAPIParser::SchemaValidator
 
       def coerce(value)
         return value if value.kind_of?(Integer)
+        # Integer() truncates a Float, so convert only one with no fractional part.
+        return value.finite? && value == value.floor ? value.to_i : value if value.kind_of?(Float)
 
         begin
           Integer(value)

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,22 @@ class OpenAPIParser::SchemaValidator
   def validate_schema(value, schema, **keyword_args)
     return [value, nil] unless schema
 
+    # 3.1: a boolean schema accepts (`true`) or rejects (`false`) any value,
+    # including null.
+    if schema.respond_to?(:raw_schema)
+      return [value, nil] if schema.raw_schema == true
+      return [nil, OpenAPIParser::FalseSchemaError.new(schema.object_reference)] if schema.raw_schema == false
+    end
+
+    # 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 +120,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 +151,67 @@ 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: when coercing, a value whose class matches no listed type is tried
+    # against each listed type, the same way a single `type` coerces it.
+    # Request params arrive as Strings ("5" for `type: [integer, "null"]`),
+    # and a single `type: integer` also coerces a Float such as 1.0.
+    # nil is left to the nil validator, as it is for a single `type`.
+    # @return [Boolean]
+    def coerce_into_type_array?(value, schema)
+      return false unless @coerce_value && !value.nil?
+      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,18 @@ 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
+
+    # @!attribute [r] self_uri
+    #   @return [String, nil] the document's own URI, `$self` (OpenAPI 3.2+)
+    openapi_attr_value :self_uri, schema_key: :'$self'
+
     # @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
@@ -114,5 +125,13 @@ module OpenAPIParser::Schemas
     def additional_properties
       @additional_properties.nil? ? true : @additional_properties
     end
+
+    # 3.1: a boolean schema (`true` / `false`) has no keywords to load.
+    def load_data
+      return super if raw_schema.is_a?(::Hash)
+
+      @_openapi_all_child_objects = {}
+      nil
+    end
   end
 end

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/boolean_schema_in_30.rb

@@ -0,0 +1,26 @@
+module OpenAPIParser
+  class SpecValidator
+    module Rules
+      # A boolean schema (`true` / `false` in place of a schema object) comes
+      # from JSON Schema 2020-12, which 3.1 adopts. 3.0 allows a boolean only
+      # for `additionalProperties`, which is not loaded as a Schema, so any
+      # Schema whose raw value is a boolean is a spec mismatch in 3.0.
+      class BooleanSchemaIn30 < Rule
+        def check(root)
+          return [] unless version_before?('3.1')
+
+          violations = []
+          each_schema(root) do |schema|
+            next unless schema.raw_schema == true || schema.raw_schema == false
+
+            violations << violation(
+              path: schema.object_reference,
+              message: 'a boolean schema is a 3.1 addition (from JSON Schema 2020-12); 3.0 allows a boolean only for `additionalProperties`',
+            )
+          end
+          violations
+        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