openapi-schema-validator

openapi-schema-validator

.. image:: https://img.shields.io/pypi/v/openapi-schema-validator.svg :target: https://pypi.python.org/pypi/openapi-schema-validator .. image:: https://github.com/python-openapi/openapi-schema-validator/actions/workflows/python-tests.yml/badge.svg :target: https://github.com/python-openapi/openapi-schema-validator/actions .. image:: https://img.shields.io/codecov/c/github/python-openapi/openapi-schema-validator/master.svg?style=flat :target: https://codecov.io/github/python-openapi/openapi-schema-validator?branch=master .. image:: https://img.shields.io/pypi/pyversions/openapi-schema-validator.svg :target: https://pypi.python.org/pypi/openapi-schema-validator .. image:: https://img.shields.io/pypi/format/openapi-schema-validator.svg :target: https://pypi.python.org/pypi/openapi-schema-validator .. image:: https://img.shields.io/pypi/status/openapi-schema-validator.svg :target: https://pypi.python.org/pypi/openapi-schema-validator

About

Openapi-schema-validator is a Python library that validates schema against:

• OpenAPI Schema Specification v3.0 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject>__ which is an extended subset of the JSON Schema Specification Wright Draft 00 <http://json-schema.org/>__.
• OpenAPI Schema Specification v3.1 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#schemaObject>__ which is an extended superset of the JSON Schema Specification Draft 2020-12 <http://json-schema.org/>__.
• OpenAPI Schema Specification v3.2 <https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.2.0.md#schemaObject>__ which uses the same JSON Schema dialect as v3.1.

Documentation #############

Check documentation to see more details about the features. All documentation is in the "docs" directory and online at openapi-schema-validator.readthedocs.io <https://openapi-schema-validator.readthedocs.io>__

Installation ############

Recommended way (via pip):

.. code-block:: console

pip install openapi-schema-validator

Alternatively you can download the code and install from the repository:

.. code-block:: console

pip install -e git+https://github.com/python-openapi/openapi-schema-validator.git#egg=openapi_schema_validator

Usage

To validate an OpenAPI v3.1 schema:

.. code-block:: python

from openapi_schema_validator import validate

A sample schema

schema = { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "age": { "type": ["integer", "null"], "format": "int32", "minimum": 0, }, "birth-date": { "type": "string", "format": "date", }, "address": { "type": 'array', "prefixItems": [ { "type": "number" }, { "type": "string" }, { "enum": ["Street", "Avenue", "Boulevard"] }, { "enum": ["NW", "NE", "SW", "SE"] } ], "items": False, } }, "additionalProperties": False, }

If no exception is raised by validate(), the instance is valid.

validate({"name": "John", "age": 23, "address": [1600, "Pennsylvania", "Avenue"]}, schema)

validate({"name": "John", "city": "London"}, schema)

Traceback (most recent call last): ... ValidationError: Additional properties are not allowed ('city' was unexpected)

By default, the latest OpenAPI schema syntax is expected.

Strict vs Pragmatic Validators

OpenAPI 3.0 has two validator variants with different behaviors for binary format:

OAS30Validator (default - pragmatic)

• Accepts Python bytes for type: string with format: binary
• More lenient for Python use cases where binary data is common
• Use when validating Python objects directly

OAS30StrictValidator

• Follows OAS spec strictly: only accepts str for type: string
• For format: binary, only accepts base64-encoded strings
• Use when strict spec compliance is required

Comparison Matrix

.. list-table:: :header-rows: 1 :widths: 35 20 22 23

• • Schema
  • Value
  • OAS30Validator (default)
  • OAS30StrictValidator
• • type: string
  • "test" (str)
  • Pass
  • Pass
• • type: string
  • b"test" (bytes)
  • Fail
  • Fail
• • type: string, format: binary
  • b"test" (bytes)
  • Pass
  • Fail
• • type: string, format: binary
  • "dGVzdA==" (base64)
  • Pass
  • Pass
• • type: string, format: binary
  • "test" (plain str)
  • Pass
  • Fail

For more details read about Validation <https://openapi-schema-validator.readthedocs.io/en/latest/validation.html>__.

Related projects ################

• openapi-core <https://github.com/python-openapi/openapi-core>__ Python library that adds client-side and server-side support for the OpenAPI.
• openapi-spec-validator <https://github.com/python-openapi/openapi-spec-validator>__ Python library that validates OpenAPI Specs against the OpenAPI 2.0 (aka Swagger) and OpenAPI 3.0 specification