{"id":789,"library":"openapi-spec-validator","title":"OpenAPI Spec Validator","description":"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.","status":"active","version":"0.8.4","language":"python","source_language":"en","source_url":"https://github.com/python-openapi/openapi-spec-validator","tags":["openapi","swagger","validation","schema","cli"],"install":[{"cmd":"pip install openapi-spec-validator","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Requires Python 3.10 or newer.","package":"python","optional":false}],"imports":[{"symbol":"validate","correct":"from openapi_spec_validator import validate"},{"symbol":"validate_url","correct":"from openapi_spec_validator import validate_url"},{"note":"For explicit validation against a specific OpenAPI version.","symbol":"OpenAPIV31SpecValidator","correct":"from openapi_spec_validator.validation import OpenAPIV31SpecValidator"},{"note":"`validate_spec` is deprecated; use `validate` instead.","wrong":"from openapi_spec_validator import validate_spec","symbol":"validate_spec","correct":"from openapi_spec_validator.shortcuts import validate"},{"note":"`validate_spec_url` is deprecated; use `validate_url` instead.","wrong":"from openapi_spec_validator import validate_spec_url","symbol":"validate_spec_url","correct":"from openapi_spec_validator.shortcuts import validate_url"}],"quickstart":{"code":"from openapi_spec_validator import validate\nfrom openapi_spec_validator.readers import read_from_filename\n\n# Example OpenAPI 3.1.0 specification (invalid, 'info' is missing)\n# For a valid spec, ensure 'info' and 'paths' are present.\ninvalid_spec_data = {\n    'openapi': '3.1.0',\n    'paths': {},\n}\n\n# A minimal valid OpenAPI 3.1.0 specification\nvalid_spec_data = {\n    'openapi': '3.1.0',\n    'info': {\n        'title': 'Test API',\n        'version': '1.0.0'\n    },\n    'paths': {}\n}\n\nprint('Attempting to validate invalid_spec_data:')\ntry:\n    validate(invalid_spec_data)\n    print('Invalid spec data is VALID (this should not happen)')\nexcept Exception as e:\n    print(f'Validation failed as expected: {e}')\n\nprint('\\nAttempting to validate valid_spec_data:')\ntry:\n    validate(valid_spec_data)\n    print('Valid spec data is VALID')\nexcept Exception as e:\n    print(f'Validation failed unexpectedly: {e}')\n\n# Example of validating from a file (if 'openapi.yaml' exists)\n# You would typically create this file with your OpenAPI definition.\n# with open('openapi.yaml', 'w') as f:\n#     import yaml\n#     yaml.dump(valid_spec_data, f)\n#\n# try:\n#     spec_dict, base_uri = read_from_filename('openapi.yaml')\n#     validate(spec_dict, base_uri=base_uri)\n#     print('\\nValidating from openapi.yaml: SUCCESS')\n# except Exception as e:\n#     print(f'\\nValidating from openapi.yaml: FAILED - {e}')","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade Python to 3.10 or newer, or pin `openapi-spec-validator` to a version `<0.8.0`.","message":"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.","severity":"breaking","affected_versions":">=0.8.0"},{"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`.","message":"The CLI options `--error` and `--errors` were deprecated in version 0.8.1. These options are now considered legacy, with warnings emitted by default.","severity":"deprecated","affected_versions":">=0.8.1"},{"fix":"Use `validate` for in-memory specs and `validate_url` for URL-based specs instead.","message":"The `validate_spec` and `validate_spec_url` shortcut functions were deprecated in version 0.7.1.","severity":"deprecated","affected_versions":">=0.7.1"},{"fix":"Pass `cls=OpenAPIV31SpecValidator` (or `OpenAPIV2SpecValidator`, `OpenAPIV30SpecValidator`, etc.) to `validate` for explicit version targeting.","message":"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.","severity":"gotcha","affected_versions":"all"},{"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.","message":"By default, `openapi-spec-validator` (via `openapi-schema-validator`) uses a local-only empty registry, preventing implicit retrieval of remote `$ref` references.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"search_vec":"'0.8.4':37 '2.0':14 '3':18 '3.2':22 'activ':39 'aim':25 'aka':15 'cadenc':49 'check':27 'cli':62 'complianc':30 'consist':47 'everi':55 'featur':45 'full':29 'librari':10 'minor':52 'modern':41 'month':57 'occur':54 'openapi':1,4,13,17,21,58 'python':9,42 'releas':48,53 'schema':61 'sever':51 'spec':2,5 'specif':23,33 'support':40 'swagger':16,59 'valid':3,6,12,60 'version':36,43 'x':19","created_at":"2026-03-29T04:21:46.145978+00:00","updated_at":"2026-04-16T17:34:18.915812+00:00","problems":[{"fix":"Install the package using pip: `pip install openapi-spec-validator`","cause":"The `openapi-spec-validator` Python package has not been installed in the current environment.","error":"ModuleNotFoundError: No module named 'openapi_spec_validator'"},{"fix":"Ensure your OpenAPI specification includes an 'info' object with at least 'title' and 'version' fields. \nExample: \n```yaml\nopenapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths: {}\n```","cause":"The OpenAPI specification being validated is missing the mandatory 'info' object, which provides metadata about the API.","error":"OpenAPIValidationError: 'info' is a required property"},{"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. \nExample for OpenAPI 2.0 (Swagger): \n```python\nfrom openapi_spec_validator import validate_v2\n# ... load your spec ...\nvalidate_v2(spec_dict)\n```","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.","error":"ImportError: cannot import name 'validate_v2_spec' from 'openapi_spec_validator'"},{"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. \nExample for OpenAPI 2.0: \n```python\nfrom openapi_spec_validator import validate_v2_spec\n# ... load your spec ...\nvalidate_v2_spec(spec_dict)\n```\nOr, for CLI: \n`openapi-spec-validator --schema 2.0 openapi.yaml`","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.","error":"Validation Error 'openapi' is a required property"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"0.9.0","cli_name":"openapi-spec-validator","cli_version":"openapi-spec-validator 0.8.5","type":"library","homepage":null,"github":"https://github.com/python-openapi/openapi-spec-validator","docs":"https://openapi-spec-validator.readthedocs.io/en/latest/","changelog":null,"pypi":"https://pypi.org/project/openapi-spec-validator/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":"verified"}}