README.rst

April 24, 2026 · View on GitHub

OpenAPI Spec validator

About

OpenAPI Spec Validator is a CLI, pre-commit hook and python package that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger) <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md>, OpenAPI 3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md> OpenAPI 3.1 <https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md>__ and OpenAPI 3.2 <https://spec.openapis.org/oas/v3.2.0.html>__ specification. The validator aims to check for full compliance with the Specification.

Documentation #############

Check documentation to see more details about the features. All documentation is in the "docs" directory and online at openapi-spec-validator.readthedocs.io <https://openapi-spec-validator.readthedocs.io>__

Installation ############

.. code-block:: console

pip install openapi-spec-validator

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

.. code-block:: bash

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

Usage

CLI (Command Line Interface)

Straight forward way:

.. code-block:: bash

openapi-spec-validator openapi.yaml

pipes way:

.. code-block:: bash

cat openapi.yaml | openapi-spec-validator -

docker way:

.. code-block:: bash

docker run -v path/to/openapi.yaml:/openapi.yaml --rm pythonopenapi/openapi-spec-validator /openapi.yaml

or more pythonic way:

.. code-block:: bash

python -m openapi_spec_validator openapi.yaml

For more details, read about CLI (Command Line Interface) <https://openapi-spec-validator.readthedocs.io/en/latest/cli.html>__.

pre-commit hook

.. code-block:: yaml

repos:

repo: https://github.com/python-openapi/openapi-spec-validator rev: 0.8.5 # The version to use or 'master' for latest hooks:
- id: openapi-spec-validator

For more details, read about pre-commit hook <https://openapi-spec-validator.readthedocs.io/en/latest/hook.html>__.

Python package

.. code:: python

from openapi_spec_validator import validate
from openapi_spec_validator.readers import read_from_filename

spec_dict, base_uri = read_from_filename('openapi.yaml')

# If no exception is raised by validate(), the spec is valid.
validate(spec_dict)

# Example of an intentionally invalid spec.
invalid_spec = {'openapi': '3.1.0'}

validate(invalid_spec)

Traceback (most recent call last):
    ...
OpenAPIValidationError: 'info' is a required property

For more details, read about Python package <https://openapi-spec-validator.readthedocs.io/en/latest/python.html>__.

Performance tuning

You can tune resolved-path caching with an environment variable:

.. code-block:: bash

OPENAPI_SPEC_VALIDATOR_RESOLVED_CACHE_MAXSIZE=2048

Rules:

Default is 128.
Set 0 to disable the resolved cache.
Invalid values (non-integer or negative) fall back to 128.

You can also choose schema validator backend:

.. code-block:: bash

OPENAPI_SPEC_VALIDATOR_SCHEMA_VALIDATOR_BACKEND=jsonschema-rs

Allowed values are auto (default), jsonschema, and jsonschema-rs. Invalid values raise a warning and fall back to auto.

If you select the jsonschema-rs backend, make sure the optional jsonschema-rs package is installed:

.. code-block:: bash

pip install jsonschema-rs

Related projects ################

openapi-core <https://github.com/python-openapi/openapi-core>__ Python library that adds client-side and server-side support for the OpenAPI v3.0, OpenAPI v3.1 and OpenAPI v3.2 specification.
openapi-schema-validator <https://github.com/python-openapi/openapi-schema-validator>__ Python library that validates schema against the OpenAPI Schema Specification v3.0, OpenAPI Schema Specification v3.1 and OpenAPI Schema Specification v3.2.

License #######