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.
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
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 1.134s · 35.7MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 4.5s · import 1.044s · 36MB
33MB installed
● package 33MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
✗ from openapi_spec_validator import validate_spec
`validate_spec` is deprecated; use `validate` instead.
validate_spec_url
✓ from openapi_spec_validator.shortcuts import validate_url
✗ from openapi_spec_validator import validate_spec_url
`validate_spec_url` is deprecated; use `validate_url` instead.
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}')
openapi-spec-validator --version
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'openapi_spec_validator'
The `openapi-spec-validator` Python package has not been installed in the current environment.
fixInstall the package using pip: `pip install openapi-spec-validator`
OpenAPIValidationError: 'info' is a required property
The OpenAPI specification being validated is missing the mandatory 'info' object, which provides metadata about the API.
fixEnsure your OpenAPI specification includes an 'info' object with at least 'title' and 'version' fields.
Example:
```yaml
openapi: 3.0.0
info:
title: My API
version: 1.0.0
paths: {}
``` ImportError: cannot import name 'validate_v2_spec' from 'openapi_spec_validator'
This error typically occurs when the imported function or class (like `validate_v2_spec` or `default_handlers`) has been moved, renamed, or removed in a newer version of the `openapi-spec-validator` library, indicating a breaking change in its API.
fixUpdate your import statements and code to use the current API of `openapi-spec-validator`. For version-specific validation, use `validate_v2`, `validate_v30`, `validate_v31`, etc. from the main `openapi_spec_validator` module.
Example for OpenAPI 2.0 (Swagger):
```python
from openapi_spec_validator import validate_v2
# ... load your spec ...
validate_v2(spec_dict)
```
Validation Error 'openapi' is a required property
This error occurs when attempting to validate an OpenAPI 2.0 (Swagger) specification using a validator that expects an OpenAPI 3.x structure, where the top-level 'openapi' field is mandatory. OpenAPI 2.0 uses a top-level 'swagger: "2.0"' field instead.
fixExplicitly specify the schema version for validation if your spec is OpenAPI 2.0, or update your spec to OpenAPI 3.x if intended.
Example for OpenAPI 2.0:
```python
from openapi_spec_validator import validate_v2_spec
# ... load your spec ...
validate_v2_spec(spec_dict)
```
Or, for CLI:
`openapi-spec-validator --schema 2.0 openapi.yaml`
Audit
Dependencies
pythonrequiredRequires Python 3.10 or newer.