{"id":906,"library":"openapi-schema-validator","title":"OpenAPI Schema Validator","description":"openapi-schema-validator is a Python library designed for validating data instances against OpenAPI Schema Specification versions 3.0, 3.1, and 3.2. It leverages `jsonschema` under the hood and provides specific validators for different OpenAPI versions, along with features for handling read/write contexts and managing external references. The library is actively maintained, with version 0.8.1 being the latest, and releases occur as new OpenAPI specifications emerge or features/fixes are required.","status":"active","version":"0.8.1","language":"python","source_language":"en","source_url":"https://github.com/python-openapi/openapi-schema-validator","tags":["OpenAPI","validation","JSON Schema","schema","API","OAS"],"install":[{"cmd":"pip install openapi-schema-validator","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for schema validation logic.","package":"jsonschema","optional":false},{"reason":"Used for explicit external JSON Schema reference resolution.","package":"referencing","optional":true},{"reason":"Compatibility dependency; version limits were removed in 0.6.3.","package":"jsonschema-specifications","optional":false}],"imports":[{"note":"High-level function for validating an instance against a schema. Defaults to OAS32Validator.","symbol":"validate","correct":"from openapi_schema_validator import validate"},{"note":"Use for OpenAPI 3.2 schema validation (default for `validate` in recent versions).","symbol":"OAS32Validator","correct":"from openapi_schema_validator import OAS32Validator"},{"note":"Use for OpenAPI 3.1 schema validation.","symbol":"OAS31Validator","correct":"from openapi_schema_validator import OAS31Validator"},{"note":"Use for OpenAPI 3.0 schema validation.","symbol":"OAS30Validator","correct":"from openapi_schema_validator import OAS30Validator"},{"note":"Use for strict OpenAPI 3.0 schema validation, enforcing stricter typing (e.g., 'string' only accepts `str`).","symbol":"OAS30StrictValidator","correct":"from openapi_schema_validator import OAS30StrictValidator"},{"note":"Use for OpenAPI 3.0 schema validation specifically in a read context (honoring 'readOnly' keywords).","symbol":"OAS30ReadValidator","correct":"from openapi_schema_validator import OAS30ReadValidator"},{"note":"Use for OpenAPI 3.0 schema validation specifically in a write context (honoring 'writeOnly' keywords).","symbol":"OAS30WriteValidator","correct":"from openapi_schema_validator import OAS30WriteValidator"}],"quickstart":{"code":"from openapi_schema_validator import validate\n\n# A sample OpenAPI 3.2 schema\nschema = {\n    \"type\": \"object\",\n    \"required\": [\"name\"],\n    \"properties\": {\n        \"name\": {\"type\": \"string\"},\n        \"age\": {\n            \"type\": [\"integer\", \"null\"],\n            \"format\": \"int32\",\n            \"minimum\": 0,\n        },\n        \"birth-date\": {\"type\": \"string\", \"format\": \"date\"},\n        \"address\": {\n            \"type\": \"array\",\n            \"prefixItems\": [\n                {\"type\": \"number\"},\n                {\"type\": \"string\"},\n                {\"enum\": [\"Street\", \"Avenue\", \"Boulevard\"]},\n                {\"enum\": [\"NW\", \"NE\", \"SW\", \"SE\"]}\n            ],\n            \"items\": False,\n        }\n    },\n    \"additionalProperties\": False,\n}\n\n# A valid instance\ntry:\n    validate({\"name\": \"John\", \"age\": 23, \"address\": [1600, \"Pennsylvania\", \"Avenue\"]}, schema)\n    print(\"Instance is valid!\")\nexcept Exception as e:\n    print(f\"Validation failed: {e}\")\n\n# An invalid instance (missing required 'name')\ntry:\n    validate({\"age\": 23}, schema)\nexcept Exception as e:\n    print(f\"Validation failed as expected: {e}\")\n\n# An invalid instance (additional property 'city')\ntry:\n    validate({\"name\": \"John\", \"city\": \"London\"}, schema)\nexcept Exception as e:\n    print(f\"Validation failed as expected: {e}\")","lang":"python","description":"The simplest way to validate an instance against an OpenAPI schema is to use the `validate` function. Provide the instance to be validated and the OpenAPI schema object. By default, it expects the latest OpenAPI schema syntax (3.2)."},"warnings":[{"fix":"To resolve external references, pass an explicit `registry` (e.g., from `referencing`). Set `allow_remote_references=True` only if you explicitly accept `jsonschema`'s default remote retrieval behavior, especially if dealing with untrusted sources.","message":"Remote `$ref` resolution is now disabled by default. The `validate` function and validator classes use a local-only empty registry to avoid implicit remote `$ref` retrieval.","severity":"breaking","affected_versions":">=0.8.0"},{"fix":"Ensure that string-typed properties intended to carry binary data in OpenAPI 3.0 are handled as Python `str` (e.g., base64-encoded) before validation, or use appropriate media type modeling for raw binary payloads for OpenAPI 3.1+.","message":"For `OAS30Validator` and `OAS30StrictValidator`, a schema type 'string' now *only* accepts Python `str` instances. It no longer accepts `bytes`.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Upgrade your Python environment to 3.10 or newer (requires_python: >=3.10.0, <4.0.0). ","message":"Support for Python 3.8 and 3.9 has been dropped.","severity":"breaking","affected_versions":">=0.7.0"},{"fix":"Upgrade your Python environment to 3.8 or newer. (Note: 3.8/3.9 were later dropped in 0.7.0, so aim for 3.10+).","message":"Support for Python 3.7 has been dropped.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"For OpenAPI 3.0 validation in specific read/write contexts, use `OAS30ReadValidator` or `OAS30WriteValidator` instead.","message":"`OAS30Validator` no longer accepts `read` and `write` properties directly. These were removed to align with a clearer read/write context model.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"Always pass the data instance as the first argument and the OpenAPI schema as the second argument to `validate`.","message":"The argument order for the `validate` function is crucial: `validate(instance, schema)`, not `validate(schema, instance)`. Incorrect order will lead to validation errors or unexpected behavior.","severity":"gotcha","affected_versions":"All"},{"fix":"Load your OpenAPI document into a Python dictionary using a library like `yaml` or `json` before passing it to `validate` or a specific validator.","message":"The library validates against a provided schema object; it does not automatically load OpenAPI documents from file paths. You must load your OpenAPI document (e.g., from YAML or JSON) into a Python dictionary or object first.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"search_vec":"'0.8.1':58 '3.0':22 '3.1':23 '3.2':25 'activ':54 'along':40 'api':79 'context':46 'data':15 'design':12 'differ':37 'emerg':69 'extern':49 'featur':42 'features/fixes':71 'handl':44 'hood':31 'instanc':16 'json':76 'jsonschema':28 'latest':61 'leverag':27 'librari':11,52 'maintain':55 'manag':48 'new':66 'oa':80 'occur':64 'openapi':1,5,18,38,67,74 'openapi-schema-valid':4 'provid':33 'python':10 'read/write':45 'refer':50 'releas':63 'requir':73 'schema':2,6,19,77,78 'specif':20,34,68 'valid':3,7,14,35,75 'version':21,39,57","created_at":"2026-03-29T06:07:07.999046+00:00","updated_at":"2026-04-16T17:34:13.472581+00:00","problems":[{"fix":"Install the library using pip: `pip install openapi-schema-validator`","cause":"The 'openapi-schema-validator' Python package is not installed in the active Python environment.","error":"ModuleNotFoundError: No module named 'openapi_schema_validator'"},{"fix":"Ensure the data instance includes all properties listed in the 'required' array of the corresponding schema.","cause":"The data instance being validated is missing a property that is marked as 'required' in the OpenAPI schema.","error":"ValidationError: 'propertyName' is a required property"},{"fix":"Reverse the order of arguments to `validate(instance, schema)`.","cause":"The `validate` function was called with the schema as the first argument and the instance as the second argument, instead of `validate(instance, schema)` as required.","error":"Incorrect argument order for validate()"},{"fix":"Ensure the data instance conforms to the expected type (e.g., an object/dictionary) as defined by the OpenAPI schema before passing it to the validator.","cause":"The validator received a data instance of an unexpected type (e.g., a list) where a dictionary-like object was anticipated, leading to an attempt to call a dictionary method like `.get()` on an incompatible type.","error":"AttributeError: 'list' object has no attribute 'get'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.9.0","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/python-openapi/openapi-schema-validator","docs":null,"changelog":null,"pypi":"https://pypi.org/project/openapi-schema-validator/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["http-networking","serialization","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"}}