openapi-spec-validator

The project uses pre-commit for static checks. All changes are checked on CI, and passing checks are required for PR acceptance. You can run these checks locally:

• Install git hooks: To automatically run checks during git commit operations:

  pre-commit install

• Run on staged files: To run checks only on files currently staged in git:

  pre-commit run

• Run on all files: To run all checks against every file in the repository:

  pre-commit run --all-files

You can validate OpenAPI specifications using the openapi-spec-validator executable directly, via a Python module invocation, or through Docker.

Direct Executable

Validate a specific file:

openapi-spec-validator openapi.yaml

Or pipe the content into the validator using -:

cat openapi.yaml | openapi-spec-validator -

Python Module

If the executable is not in your path, use the Python interpreter:

python -m openapi_spec_validator openapi.yaml

Docker

Run the validator in a container by mounting your local file:

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

You can install the package via pip from PyPI or directly from the GitHub repository.

To install from PyPI:

pip install openapi-spec-validator

To install from the git repository in editable mode:

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

The project uses Poetry for dependency management. To set up a local development environment:

1. Configure Poetry (Recommended): Set Poetry to create a virtual environment in a .venv folder within the project root:

   poetry config virtualenvs.in-project true

2. Install Dependencies: Install the runtime and development dependencies:

   poetry install

3. Activate Environment: Enter the virtual environment:

   poetry shell

When reporting a bug in the openapi-spec-validator issue tracker, follow these guidelines:

1. Verify first: Check the Issue tracker to ensure the issue hasn't already been reported. Ensure your report is not a support request or question; use the Discussion board for those.
2. Provide details:
   • Use a clear, descriptive title.
   • Include your exact runtime environment and versions.
   • Provide exact reproduction steps, including minimal code snippets.
   • Include the observed behavior (paste console outputs).
   • Describe the expected behavior and provide links to relevant documentation explaining why that behavior is expected.

You can validate a specification hosted at a remote URL directly using validate_url(). If no exception is raised, the specification is valid.

from openapi_spec_validator import validate_url

# If no exception is raised, the spec is valid
validate_url('http://example.com/openapi.json')

To validate a local OpenAPI specification, use read_from_filename to load the specification dictionary and its base URI, then pass the dictionary to validate(). If no exception is raised, the specification is valid. If the specification contains relative file references, you must provide the base_uri to validate().

from openapi_spec_validator import validate
from openapi_spec_validator.readers import read_from_filename

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

# Validate the spec
validate(spec_dict)

# If the spec uses relative files, provide the base_uri
validate(spec_dict, base_uri='file:///path/to/spec/openapi.yaml')

To run the validator automatically during your git workflow, add it to your .pre-commit-config.yaml file:

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

You can integrate openapi-spec-validator into your Git workflow using the pre-commit framework. This ensures that your OpenAPI specifications are validated automatically before they are committed, preventing broken specifications from entering your repository.

To set this up, add the following configuration to your .pre-commit-config.yaml file. Ensure the rev matches the version you wish to use (e.g., 0.9.0).

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

You can choose which backend engine is used for schema validation via the OPENAPI_SPEC_VALIDATOR_SCHEMA_VALIDATOR_BACKEND environment variable.

Allowed values:

• auto (default)
• jsonschema
• jsonschema-rs (requires the jsonschema-rs package: pip install jsonschema-rs)

Note: Invalid values will raise a warning and fall back to auto.

OPENAPI_SPEC_VALIDATOR_SCHEMA_VALIDATOR_BACKEND=jsonschema-rs

You can tune the performance and behavior of the validator using the following environment variables:

Performance Tuning

• OPENAPI_SPEC_VALIDATOR_RESOLVED_CACHE_MAXSIZE: Controls the resolved-path caching size. Default is 128. Set to 0 to disable caching.
• OPENAPI_SPEC_VALIDATOR_SCHEMA_VALIDATOR_BACKEND: Selects the schema validator backend. Options: auto, jsonschema, or jsonschema-rs.

Silencing Deprecation Warnings

• OPENAPI_SPEC_VALIDATOR_WARN_DEPRECATED: Set to 0 to silence warnings regarding the use of deprecated flags like --errors or --error.

You can control the size of the jsonschema-path resolved path cache using the OPENAPI_SPEC_VALIDATOR_RESOLVED_CACHE_MAXSIZE environment variable.

• Default: 128
• Disable cache: Set to 0
• Custom size: Set to any positive integer (e.g., 2048)
• Invalid values: Non-integers or negative values fall back to the default of 128.

OPENAPI_SPEC_VALIDATOR_RESOLVED_CACHE_MAXSIZE=2048