Registry / http-networking / openapi-schema-validator

openapi-schema-validator

library0.8.1pypypi✓ verified 49d ago

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.

http-networking serialization web-framework

pip install openapi-schema-validator

github ↗package ↗

Install & Compatibility

Where this runs

tested against v0.9.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.925 runs

installs and imports cleanly · install 0.0s · import 0.810s · 32.3MB

glibc

py 3.10–3.925 runs

installs and imports cleanly · install 3.7s · import 0.721s · 32MB

28MB installed

● package 28MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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).

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

Debug

Known issues

breakingRemote `$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.

affects: >=0.8.0

breakingFor `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+.

affects: >=0.7.0

breakingSupport 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).

affects: >=0.7.0

breakingSupport 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+).

affects: >=0.6.0

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.

affects: >=0.6.0

gotchaThe 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`.

affects: All

gotchaThe 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.

affects: All

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'openapi_schema_validator'

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`

ValidationError: 'propertyName' is a required property

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.

Incorrect argument order for validate()

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)`.

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

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.

Upgrade

Version history

0.9.0latest on PyPI

Audit

Dependencies

jsonschemarequiredCore dependency for schema validation logic.

referencingoptionalUsed for explicit external JSON Schema reference resolution.

jsonschema-specificationsrequiredCompatibility dependency; version limits were removed in 0.6.3.

Agent activity

10 hits · last 30 days

ahrefsbot

googlebot

seranking-bot

Amazon

amazonbot

Resources

githubhttps://github.com/python-openapi/openapi-schema-validator ↗

packagehttps://pypi.org/project/openapi-schema-validator/ ↗