OpenAPI Schema Validator

0.8.1 · active · verified Sun Mar 29

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.

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

pip install openapi-schema-validator Install latest version

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

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}")

view raw JSON →