OpenAPI Spec Validator

0.8.4 verified Tue May 12 auth: no python install: verified quickstart: verified

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.

pip install openapi-spec-validator

Common errors

error ModuleNotFoundError: No module named 'openapi_spec_validator' ↓

cause The `openapi-spec-validator` Python package has not been installed in the current environment.

fix

Install the package using pip: pip install openapi-spec-validator

error OpenAPIValidationError: 'info' is a required property ↓

cause The OpenAPI specification being validated is missing the mandatory 'info' object, which provides metadata about the API.

fix

Ensure your OpenAPI specification includes an 'info' object with at least 'title' and 'version' fields. Example:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths: {}

error ImportError: cannot import name 'validate_v2_spec' from 'openapi_spec_validator' ↓

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

fix

Update 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):

from openapi_spec_validator import validate_v2
# ... load your spec ...
validate_v2(spec_dict)

error Validation Error 'openapi' is a required property ↓

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

fix

Explicitly 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:

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

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 compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.84s 35.7M

3.10 alpine (musl) - - 0.86s 35.5M

3.10 slim (glibc) wheel 5.6s 0.68s 36M

3.10 slim (glibc) - - 0.62s 36M

3.11 alpine (musl) wheel - 1.28s 39.1M

3.11 alpine (musl) - - 1.37s 39.0M

3.11 slim (glibc) wheel 4.7s 1.12s 39M

3.11 slim (glibc) - - 1.07s 39M

3.12 alpine (musl) wheel - 1.29s 30.7M

3.12 alpine (musl) - - 1.36s 30.5M

3.12 slim (glibc) wheel 3.8s 1.36s 31M

3.12 slim (glibc) - - 1.34s 31M

3.13 alpine (musl) wheel - 1.31s 30.5M

3.13 alpine (musl) - - 1.30s 30.2M

3.13 slim (glibc) wheel 4.0s 1.21s 30M

3.13 slim (glibc) - - 1.26s 30M

3.9 alpine (musl) wheel - 0.97s 27.5M

3.9 alpine (musl) - - 0.93s 27.6M

3.9 slim (glibc) wheel 4.5s 0.91s 28M

3.9 slim (glibc) - - 0.80s 28M

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

wrong

from openapi_spec_validator import validate_spec

correct

from openapi_spec_validator.shortcuts import validate

`validate_spec` is deprecated; use `validate` instead.

validate_spec_url

wrong

from openapi_spec_validator import validate_spec_url

correct

from openapi_spec_validator.shortcuts import validate_url

`validate_spec_url` is deprecated; use `validate_url` instead.

Quickstart verified last tested: 2026-04-24

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