Check OpenAPI 3.0 schemas against the OAS 3.0 Schema Object schema

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

Vendor the official OAS 3.0 schema (2024-10-18) unmodified and check
OAS 3.0 schemas against its Schema, Reference, Discriminator, XML and
ExternalDocumentation definitions. Schema or Reference is chosen by the
presence of $ref instead of the official oneOf, so errors point at the
offending keyword and keys next to $ref are ignored as the
specification requires.

Apply the check to OAS30Validator and the Strict, Read and Write
variants; the variants previously used jsonschema's default Draft 4
check.

This is a breaking change: schemas using unsupported keywords, and
roots carrying non-Schema Object keys such as components or a whole
OpenAPI document, now raise SchemaError. Referenced schemas can be
provided via registry, or the check skipped with check_schema=False.

Author: p1c2u

docs/validation.rst

@@ -161,6 +161,26 @@ In order to validate OpenAPI 3.0 schema, import and use ``OAS30Validator`` inste
 
    validate({"name": "John", "age": None}, schema, cls=OAS30Validator)
 
+OpenAPI 3.0 schemas are checked against the
+`official OpenAPI 3.0 Schema Object schema
+<https://spec.openapis.org/oas/3.0/schema/2024-10-18>`__, which allows only the
+fields listed by the specification and ``x-`` extensions. JSON Schema keywords
+that OpenAPI 3.0 does not support, such as ``type`` arrays, ``definitions``,
+``id``, ``$schema``, ``patternProperties`` or ``const``, raise
+``SchemaError``:
+
+.. code-block:: python
+
+   validate("John", {"type": ["string", "null"]}, cls=OAS30Validator)
+   # SchemaError: ['string', 'null'] is not of type 'string'
+
+Use ``nullable: true`` instead of a ``null`` type. An object with ``$ref`` is
+a Reference Object: any other keys next to ``$ref`` are ignored.
+
+The schema passed in is checked as a Schema Object, so it cannot carry other
+keys such as ``definitions``, ``components`` or a whole OpenAPI document.
+Provide referenced schemas through ``registry=...`` (see :doc:`references`).
+
 Default dialect resolution
 --------------------------
 

openapi_schema_validator/_dialects.py

@@ -7,13 +7,15 @@
 )
 
 __all__ = [
+    "OAS30_SCHEMA_ID",
     "OAS31_BASE_DIALECT_ID",
     "OAS31_BASE_DIALECT_METASCHEMA",
     "OAS32_BASE_DIALECT_ID",
     "OAS32_BASE_DIALECT_METASCHEMA",
     "register_openapi_dialect",
 ]
 
+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,