openapi-schema-validator is a Python library that validates schemas against:

• OpenAPI Schema Specification v3.0 which is an extended subset of the JSON Schema Specification Wright Draft 00.
• OpenAPI Schema Specification v3.1 which is an extended superset of the JSON Schema Specification Draft 2020-12.
• OpenAPI Schema Specification v3.2 using the published OAS 3.2 JSON Schema dialect resources.

Check documentation to see more details about the features. All documentation is in the "docs" directory and online at openapi-schema-validator.readthedocs.io

Recommended way (via pip):

pip install openapi-schema-validator

Alternatively you can download the code and install from the repository:

pip install "git+https://github.com/python-openapi/openapi-schema-validator.git"

validate call signature is:

validate(
    instance,
    schema,
    cls=OAS32Validator,
    allow_remote_references=False,
    check_schema=True,
    enforce_properties_required=False,
    **kwargs,
)

The first argument is always the value you want to validate. The second argument is always the OpenAPI schema object. The cls keyword argument is optional and defaults to OAS32Validator. Use cls when you need a specific validator version/behavior.

from openapi_schema_validator import OAS30Validator
from openapi_schema_validator import OAS31Validator
from openapi_schema_validator import validate

# OpenAPI 3.0 behavior
validate(instance, schema, cls=OAS30Validator)

# OpenAPI 3.1 behavior
validate(instance, schema, cls=OAS31Validator)

# OpenAPI 3.2 behavior (default)
validate(instance, schema)

Common forwarded keyword arguments include registry (reference context) and format_checker (format validation behavior). By default, validate uses a local-only empty registry to avoid implicit remote $ref retrieval. To resolve external references, pass an explicit registry. Set allow_remote_references=True only if you explicitly accept jsonschema's default remote retrieval behavior.

check_schema defaults to True and validates the schema before validating an instance. For trusted pre-validated schemas in hot paths, set check_schema=False to skip schema checking.

When enforce_properties_required=True is passed, all properties declared in the schema's properties object are strictly required to be present in the instance (except those marked as writeOnly or readOnly where appropriate), regardless of the schema's required array. This is useful for response or contract testing to ensure no documented fields are missing.

The validate helper keeps an internal compiled-validator cache. You can control cache size using the OPENAPI_SCHEMA_VALIDATOR_COMPILED_VALIDATOR_CACHE_MAX_SIZE environment variable (default: 128). The value is loaded once at first use and reused for the lifetime of the process.

To validate an OpenAPI schema:

from openapi_schema_validator import validate

# A sample schema
schema = {
    "type": "object",
    "required": [
       "name"
    ],
    "properties": {
        "name": {
            "type": "string"
        },
        "age": {
            "type": ["integer", "null"],
            "format": "int32",
            "minimum": 0,
        },
        "birth-date": {
            "type": "string",
            "format": "date",
        },
        "address": {
             "type": 'array',
             "prefixItems": [
                 { "type": "number" },
                 { "type": "string" },
                 { "enum": ["Street", "Avenue", "Boulevard"] },
                 { "enum": ["NW", "NE", "SW", "SE"] }
             ],
             "items": False,
         }
    },
    "additionalProperties": False,
}

# If no exception is raised by validate(), the instance is valid.
validate({"name": "John", "age": 23, "address": [1600, "Pennsylvania", "Avenue"]}, schema)

validate({"name": "John", "city": "London"}, schema)

Expected failure output:

Traceback (most recent call last):
    ...
ValidationError: Additional properties are not allowed ('city' was unexpected)

By default, the latest OpenAPI schema syntax is expected.

The OpenAPI 3.1 and 3.2 base dialect URIs are registered for jsonschema.validators.validator_for resolution. Schemas declaring "$schema" as either "https://spec.openapis.org/oas/3.1/dialect/base" or "https://spec.openapis.org/oas/3.2/dialect/2025-09-17" resolve directly to OAS31Validator and OAS32Validator without unresolved-metaschema fallback warnings.

from jsonschema.validators import validator_for

from openapi_schema_validator import OAS31Validator
from openapi_schema_validator import OAS32Validator

schema = {
    "$schema": "https://spec.openapis.org/oas/3.1/dialect/base",
    "type": "object",
}
schema32 = {
    "$schema": "https://spec.openapis.org/oas/3.2/dialect/2025-09-17",
    "type": "object",
}

assert validator_for(schema) is OAS31Validator
assert validator_for(schema32) is OAS32Validator

The handling of binary-like payloads differs between OpenAPI versions.

OpenAPI 3.0 keeps historical format: binary / format: byte usage on type: string.

OAS30Validator (default - compatibility behavior)

• type: string accepts str
• type: string, format: binary accepts Python bytes and strings
• maxLength / minLength constrain raw bytes by octet count
• useful when validating Python-native runtime data

OAS30StrictValidator

• type: string accepts str only
• type: string, format: binary uses strict format validation and rejects bytes
• use when you want strict, spec-oriented behavior for 3.0 schemas

Under JSON Schema 2020-12, OpenAPI 3.1 and 3.2 model raw binary with a typeless schema (the 3.0 format: binary / format: byte pair was dropped). This library accepts Python bytes for such raw-binary schemas.

OAS31Validator / OAS32Validator (default - runtime-friendly behavior)

• canonical raw binary is a typeless schema, optionally annotated with a non-text contentMediaType and no contentEncoding (for example {} or {"contentMediaType": "application/octet-stream"}); a bytes instance validates
• as a pragmatic compatibility extension, type: string together with a non-text contentMediaType (and no contentEncoding) also accepts bytes. This is runtime tolerance for specs migrated from 3.0, not a claim of spec conformance
• plain type: string accepts str only (not bytes)
• encoded text stays on the string path: model base64-in-JSON and similar with contentEncoding. Any real contentEncoding (base64, base64url, base16, base32, quoted-printable ...) keeps the schema textual; only the no-op identity encodings (identity / binary / 7bit / 8bit) leave it raw
• maxLength / minLength constrain raw bytes by octet count

OAS31StrictValidator / OAS32StrictValidator

• explicit opt-ins that preserve JSON Schema string typing
• canonical typeless raw binary still accepts bytes
• a schema asserting type: string rejects bytes even with a non-text contentMediaType (no pragmatic tolerance)

validator_for keeps resolving the 3.1 / 3.2 dialect ids to the default validators; the strict classes are never the dialect default.

By default, pattern handling follows host Python regex behavior. For ECMAScript-oriented regex validation and matching (via regress), install the optional extra:

pip install "openapi-schema-validator[ecma-regex]"

For more details read about Validation.

• openapi-core

  Python library that adds client-side and server-side support for the OpenAPI.

• openapi-spec-validator

  Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger) and OpenAPI 3.0 specification