README.rst

openapi-schema-validator

About

Openapi-schema-validator is a Python library that validates schema 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.

Documentation

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

Installation

Recommended way (via pip):

pip install openapi-schema-validator

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

pip install -e git+https://github.com/python-openapi/openapi-schema-validator.git#egg=openapi_schema_validator

Usage

validate call signature is:

validate(instance, schema, cls=OAS32Validator, **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.

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)

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

By default, the latest OpenAPI schema syntax is expected.

Default dialect resolution

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

Binary Data Semantics

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

OpenAPI 3.0

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
• useful when validating Python-native runtime data

OAS30StrictValidator

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

OpenAPI 3.1+

OpenAPI 3.1+ follows JSON Schema semantics for string typing in this library.

• type: string accepts str only (not bytes)
• format: binary and format: byte are not treated as built-in formats
• for base64-in-JSON, model with contentEncoding: base64 (optionally contentMediaType)
• for raw binary payloads, model via media type (for example application/octet-stream) rather than schema string formats

Quick Reference

Context	"text" (str)	b"text" (bytes)	Notes
OAS 3.0 + OAS30Validator	Pass	Pass for format: binary	Compatibility behavior for Python runtime payloads
OAS 3.0 + OAS30StrictValidator	Pass	Fail	Strict 3.0 validation mode
OAS 3.1 + OAS31Validator	Pass	Fail	Use contentEncoding/contentMediaType and media types
OAS 3.2 + OAS32Validator	Pass	Fail	Same semantics as OAS 3.1

Regex Behavior

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.

Related projects

• 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