Add opt-in OpenAPI 3.0 Schema Object metaschema check

OpenAPI 3.0 schemas are checked against the JSON Schema Draft 4
metaschema, which accepts keywords OpenAPI 3.0 does not support
(type arrays, definitions, id, $schema, patternProperties, const, ...).

Vendor the official OAS 3.0 schema (2024-10-18) unmodified and add
metaschema="openapi" to OAS 3.0 check_schema, plus oas30_metaschema
on the validate shortcut. The check uses the Schema, Reference,
Discriminator, XML and ExternalDocumentation definitions, choosing
Schema or Reference by the presence of $ref instead of oneOf so errors
point at the offending keyword. Local reference targets are checked
against the same metaschema, including targets declaring $schema.

The default stays "draft4"; the cache key includes the selected
metaschema.

Author: p1c2u

docs/validation.rst

@@ -168,6 +168,37 @@ dialect either. Schema checks still follow local JSON pointer references
 (``#/...``) and check the schemas they point to, wherever those are stored in
 the document.
 
+OpenAPI 3.0 Schema Object metaschema
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+By default OpenAPI 3.0 schemas are checked against the JSON Schema Draft 4
+metaschema, which accepts keywords that OpenAPI 3.0 does not support, such as
+``type`` arrays, ``definitions``, ``id``, ``$schema``, ``patternProperties``
+or ``const``. Pass ``metaschema="openapi"`` to ``check_schema`` (or
+``oas30_metaschema="openapi"`` to ``validate``) to check against the
+`official OpenAPI 3.0 Schema Object schema
+<https://spec.openapis.org/oas/3.0/schema/2024-10-18>`__ instead. It allows
+only the fields listed by the specification and ``x-`` extensions:
+
+.. code-block:: python
+
+   from openapi_schema_validator import OAS30Validator
+   from openapi_schema_validator import validate
+
+   schema = {"type": ["string", "null"]}
+
+   OAS30Validator.check_schema(schema)  # passes with the Draft 4 metaschema
+
+   OAS30Validator.check_schema(schema, metaschema="openapi")
+   # SchemaError: ['string', 'null'] is not of type 'string'
+
+   validate("John", schema, cls=OAS30Validator, oas30_metaschema="openapi")
+   # SchemaError: ['string', 'null'] is not of type 'string'
+
+The ``openapi`` metaschema is opt-in for now and is planned to become the
+default for OpenAPI 3.0 in a future major release. ``oas30_metaschema`` is
+accepted only with OpenAPI 3.0 validator classes.
+
 Default dialect resolution
 --------------------------
 

openapi_schema_validator/_caches.py

@@ -54,10 +54,14 @@ def build_key(
         args: tuple[Any, ...],
         kwargs: Mapping[str, Any],
         allow_remote_references: bool,
+        schema_check_options: Hashable = (),
     ) -> Hashable:
+        # ``schema_checked`` is only meaningful for the options it was
+        # checked with, so they are part of the key.
         return (
             cls,
             allow_remote_references,
+            schema_check_options,
             self._schema_fingerprint(schema),
             self._freeze_value(args),
             self._freeze_value(dict(kwargs)),

openapi_schema_validator/_dialects.py

@@ -7,13 +7,17 @@
 )
 
 __all__ = [
+    "OAS30_SCHEMA_ID",
     "OAS31_BASE_DIALECT_ID",
     "OAS31_BASE_DIALECT_METASCHEMA",
     "OAS32_BASE_DIALECT_ID",
     "OAS32_BASE_DIALECT_METASCHEMA",
     "register_openapi_dialect",
 ]
 
+#: Official JSON Schema for OpenAPI 3.0 documents. Its ``Schema`` and
+#: ``Reference`` definitions describe the OpenAPI 3.0 Schema Object.
+OAS30_SCHEMA_ID = "https://spec.openapis.org/oas/3.0/schema/2024-10-18"
 OAS31_BASE_DIALECT_ID = "https://spec.openapis.org/oas/3.1/dialect/base"
 OAS31_BASE_DIALECT_METASCHEMA = OPENAPI_SPECIFICATIONS.contents(
     OAS31_BASE_DIALECT_ID,

openapi_schema_validator/_references.py

@@ -106,11 +106,15 @@ def _resolve_pointer(
 
 def iter_unchecked_reference_targets(
     schema: Mapping[str, Any],
+    *,
+    skip_other_dialects: bool = True,
 ) -> Iterator[Mapping[str, Any]]:
     """Yield reachable local reference targets the structural check missed.
 
     Each target is yielded once. Targets inside a yielded target are
-    treated as covered by that target's check.
+    treated as covered by that target's check. With ``skip_other_dialects``
+    (the default), schemas declaring another dialect via ``$schema`` are
+    left to that dialect.
     """
     covered: set[int] = set()
     _mark_covered(schema, covered)
@@ -125,7 +129,11 @@ def iter_unchecked_reference_targets(
         visited.add(key)
 
         if "$ref" not in current:
-            if current is not schema and declares_other_dialect(current):
+            if (
+                skip_other_dialects
+                and current is not schema
+                and declares_other_dialect(current)
+            ):
                 continue
             # Definitions become reachable through references only.
             for child in _children(current, include_definitions=False):
@@ -142,7 +150,9 @@ def iter_unchecked_reference_targets(
         except (LookupError, TypeError, ValueError):
             # Unresolvable references are reported during validation.
             continue
-        if not isinstance(target, Mapping) or declares_other_dialect(target):
+        if not isinstance(target, Mapping):
+            continue
+        if skip_other_dialects and declares_other_dialect(target):
             continue
         if id(target) not in covered:
             _mark_covered(target, covered)