OpenAPI Spec Validator

0.8.4 · active · verified Sun Mar 29

OpenAPI Spec Validator is a Python library that validates OpenAPI 2.0 (aka Swagger), OpenAPI 3.x, and OpenAPI 3.2 specifications. It aims to check for full compliance with the Specification. As of version 0.8.4, it actively supports modern Python versions and features a consistent release cadence, with several minor releases occurring every few months.

Warnings

breaking Python 3.8 and 3.9 support was dropped with version 0.8.0. Users on these Python versions should remain on `openapi-spec-validator<0.8.0` or upgrade their Python environment.
Fix: Upgrade Python to 3.10 or newer, or pin `openapi-spec-validator` to a version `<0.8.0`.
deprecated The CLI options `--error` and `--errors` were deprecated in version 0.8.1. These options are now considered legacy, with warnings emitted by default.
Fix: Use the new CLI error control options `--subschema-errors` and `--validation-errors` introduced in 0.8.1. To silence deprecation warnings, set `OPENAPI_SPEC_VALIDATOR_WARN_DEPRECATED=0`.
deprecated The `validate_spec` and `validate_spec_url` shortcut functions were deprecated in version 0.7.1.
Fix: Use `validate` for in-memory specs and `validate_url` for URL-based specs instead.
gotcha The `validate` function attempts to auto-detect the OpenAPI version. For explicit validation against a specific OpenAPI version (e.g., 3.1.x), it's recommended to pass the corresponding validator class (e.g., `OpenAPIV31SpecValidator`) using the `cls` argument.
Fix: Pass `cls=OpenAPIV31SpecValidator` (or `OpenAPIV2SpecValidator`, `OpenAPIV30SpecValidator`, etc.) to `validate` for explicit version targeting.
gotcha By default, `openapi-spec-validator` (via `openapi-schema-validator`) uses a local-only empty registry, preventing implicit retrieval of remote `$ref` references.
Fix: To resolve external references, an explicit `registry` must be passed, or `allow_remote_references=True` must be set, which relies on `jsonschema`'s default remote retrieval behavior.

Install

pip install openapi-spec-validator Install stable release

Imports

validate

from openapi_spec_validator import validate

validate_url

from openapi_spec_validator import validate_url

OpenAPIV31SpecValidator
```
from openapi_spec_validator.validation import OpenAPIV31SpecValidator
```
For explicit validation against a specific OpenAPI version.
validate_spec
```
from openapi_spec_validator.shortcuts import validate
```
`validate_spec` is deprecated; use `validate` instead.
validate_spec_url
```
from openapi_spec_validator.shortcuts import validate_url
```
`validate_spec_url` is deprecated; use `validate_url` instead.

Quickstart

This quickstart demonstrates how to validate an OpenAPI specification using the `validate` function. It includes examples for both invalid and valid in-memory specifications, and comments on how to validate from a file.

from openapi_spec_validator import validate
from openapi_spec_validator.readers import read_from_filename

# Example OpenAPI 3.1.0 specification (invalid, 'info' is missing)
# For a valid spec, ensure 'info' and 'paths' are present.
invalid_spec_data = {
    'openapi': '3.1.0',
    'paths': {},
}

# A minimal valid OpenAPI 3.1.0 specification
valid_spec_data = {
    'openapi': '3.1.0',
    'info': {
        'title': 'Test API',
        'version': '1.0.0'
    },
    'paths': {}
}

print('Attempting to validate invalid_spec_data:')
try:
    validate(invalid_spec_data)
    print('Invalid spec data is VALID (this should not happen)')
except Exception as e:
    print(f'Validation failed as expected: {e}')

print('\nAttempting to validate valid_spec_data:')
try:
    validate(valid_spec_data)
    print('Valid spec data is VALID')
except Exception as e:
    print(f'Validation failed unexpectedly: {e}')

# Example of validating from a file (if 'openapi.yaml' exists)
# You would typically create this file with your OpenAPI definition.
# with open('openapi.yaml', 'w') as f:
#     import yaml
#     yaml.dump(valid_spec_data, f)
#
# try:
#     spec_dict, base_uri = read_from_filename('openapi.yaml')
#     validate(spec_dict, base_uri=base_uri)
#     print('\nValidating from openapi.yaml: SUCCESS')
# except Exception as e:
#     print(f'\nValidating from openapi.yaml: FAILED - {e}')

view raw JSON →