OpenAPI Schema Validator

0.8.1 verified Tue May 12 auth: no python install: verified

openapi-schema-validator is a Python library designed for validating data instances against OpenAPI Schema Specification versions 3.0, 3.1, and 3.2. It leverages `jsonschema` under the hood and provides specific validators for different OpenAPI versions, along with features for handling read/write contexts and managing external references. The library is actively maintained, with version 0.8.1 being the latest, and releases occur as new OpenAPI specifications emerge or features/fixes are required.

pip install openapi-schema-validator

Common errors

error ModuleNotFoundError: No module named 'openapi_schema_validator' ↓

cause The 'openapi-schema-validator' Python package is not installed in the active Python environment.

fix

Install the library using pip: pip install openapi-schema-validator

error ValidationError: 'propertyName' is a required property ↓

cause The data instance being validated is missing a property that is marked as 'required' in the OpenAPI schema.

fix

Ensure the data instance includes all properties listed in the 'required' array of the corresponding schema.

error Incorrect argument order for validate() ↓

cause The `validate` function was called with the schema as the first argument and the instance as the second argument, instead of `validate(instance, schema)` as required.

fix

Reverse the order of arguments to validate(instance, schema).

error AttributeError: 'list' object has no attribute 'get' ↓

cause The validator received a data instance of an unexpected type (e.g., a list) where a dictionary-like object was anticipated, leading to an attempt to call a dictionary method like `.get()` on an incompatible type.

fix

Ensure the data instance conforms to the expected type (e.g., an object/dictionary) as defined by the OpenAPI schema before passing it to the validator.

Warnings

breaking Remote `$ref` resolution is now disabled by default. The `validate` function and validator classes use a local-only empty registry to avoid implicit remote `$ref` retrieval. ↓

fix To resolve external references, pass an explicit `registry` (e.g., from `referencing`). Set `allow_remote_references=True` only if you explicitly accept `jsonschema`'s default remote retrieval behavior, especially if dealing with untrusted sources.

breaking For `OAS30Validator` and `OAS30StrictValidator`, a schema type 'string' now *only* accepts Python `str` instances. It no longer accepts `bytes`. ↓

fix Ensure that string-typed properties intended to carry binary data in OpenAPI 3.0 are handled as Python `str` (e.g., base64-encoded) before validation, or use appropriate media type modeling for raw binary payloads for OpenAPI 3.1+.

breaking Support for Python 3.8 and 3.9 has been dropped. ↓

fix Upgrade your Python environment to 3.10 or newer (requires_python: >=3.10.0, <4.0.0).

breaking Support for Python 3.7 has been dropped. ↓

fix Upgrade your Python environment to 3.8 or newer. (Note: 3.8/3.9 were later dropped in 0.7.0, so aim for 3.10+).

breaking `OAS30Validator` no longer accepts `read` and `write` properties directly. These were removed to align with a clearer read/write context model. ↓

fix For OpenAPI 3.0 validation in specific read/write contexts, use `OAS30ReadValidator` or `OAS30WriteValidator` instead.

gotcha The argument order for the `validate` function is crucial: `validate(instance, schema)`, not `validate(schema, instance)`. Incorrect order will lead to validation errors or unexpected behavior. ↓

fix Always pass the data instance as the first argument and the OpenAPI schema as the second argument to `validate`.

gotcha The library validates against a provided schema object; it does not automatically load OpenAPI documents from file paths. You must load your OpenAPI document (e.g., from YAML or JSON) into a Python dictionary or object first. ↓

fix Load your OpenAPI document into a Python dictionary using a library like `yaml` or `json` before passing it to `validate` or a specific validator.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.65s 32.3M

3.10 alpine (musl) - - 0.68s 32.2M

3.10 slim (glibc) wheel 5.0s 0.49s 32M

3.10 slim (glibc) - - 0.46s 31M

3.11 alpine (musl) wheel - 0.97s 35.4M

3.11 alpine (musl) - - 1.05s 35.3M

3.11 slim (glibc) wheel 4.0s 0.81s 35M

3.11 slim (glibc) - - 0.76s 35M

3.12 alpine (musl) wheel - 1.09s 27.0M

3.12 alpine (musl) - - 1.22s 26.8M

3.12 slim (glibc) wheel 3.3s 1.17s 26M

3.12 slim (glibc) - - 1.13s 26M

3.13 alpine (musl) wheel - 0.98s 26.7M

3.13 alpine (musl) - - 1.06s 26.5M

3.13 slim (glibc) wheel 3.5s 0.95s 26M

3.13 slim (glibc) - - 1.01s 26M

3.9 alpine (musl) wheel - 0.30s 21.2M

3.9 alpine (musl) - - 0.30s 21.2M

3.9 slim (glibc) wheel 3.0s 0.25s 21M

3.9 slim (glibc) - - 0.25s 21M

Imports

validate
```
from openapi_schema_validator import validate
```
High-level function for validating an instance against a schema. Defaults to OAS32Validator.
OAS32Validator
```
from openapi_schema_validator import OAS32Validator
```
Use for OpenAPI 3.2 schema validation (default for `validate` in recent versions).

OAS31Validator

from openapi_schema_validator import OAS31Validator

Use for OpenAPI 3.1 schema validation.

OAS30Validator

from openapi_schema_validator import OAS30Validator

Use for OpenAPI 3.0 schema validation.

OAS30StrictValidator
```
from openapi_schema_validator import OAS30StrictValidator
```
Use for strict OpenAPI 3.0 schema validation, enforcing stricter typing (e.g., 'string' only accepts `str`).
OAS30ReadValidator
```
from openapi_schema_validator import OAS30ReadValidator
```
Use for OpenAPI 3.0 schema validation specifically in a read context (honoring 'readOnly' keywords).
OAS30WriteValidator
```
from openapi_schema_validator import OAS30WriteValidator
```
Use for OpenAPI 3.0 schema validation specifically in a write context (honoring 'writeOnly' keywords).

Quickstart last tested: 2026-04-24

The simplest way to validate an instance against an OpenAPI schema is to use the `validate` function. Provide the instance to be validated and the OpenAPI schema object. By default, it expects the latest OpenAPI schema syntax (3.2).

from openapi_schema_validator import validate

# A sample OpenAPI 3.2 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,
}

# A valid instance
try:
    validate({"name": "John", "age": 23, "address": [1600, "Pennsylvania", "Avenue"]}, schema)
    print("Instance is valid!")
except Exception as e:
    print(f"Validation failed: {e}")

# An invalid instance (missing required 'name')
try:
    validate({"age": 23}, schema)
except Exception as e:
    print(f"Validation failed as expected: {e}")

# An invalid instance (additional property 'city')
try:
    validate({"name": "John", "city": "London"}, schema)
except Exception as e:
    print(f"Validation failed as expected: {e}")