Install & Compatibility
Where this runs
tested against v0.23.1 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.545s · 40.1MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 8.3s · import 1.417s · 40MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
OpenAPI
✓ from openapi_core import OpenAPI
Main class to load and parse an OpenAPI specification.
RequestValidator
✓ from openapi_core.validation.request.validators import RequestValidator
Used for server-side request validation.
ResponseValidator
✓ from openapi_core.validation.response.validators import ResponseValidator
Used for server-side response validation.
OpenAPIRequest
✓ from openapi_core.wrappers.mock import MockRequest as OpenAPIRequest
Example of a wrapper for request objects. Specific framework wrappers are available in `openapi_core.contrib.*`
OpenAPIResponse
✓ from openapi_core.wrappers.mock import MockResponse as OpenAPIResponse
Example of a wrapper for response objects. Specific framework wrappers are available in `openapi_core.contrib.*`
This quickstart demonstrates loading an OpenAPI specification, creating mock requests and responses, and then using `RequestValidator` and `ResponseValidator` to validate them against the loaded spec. It covers both request parameters and response body validation. In real-world scenarios, you would use framework-specific request/response wrappers (e.g., `FlaskRequest`, `StarletteRequest`).
import io
from openapi_core import OpenAPI
from openapi_core.validation.request.validators import RequestValidator
from openapi_core.validation.response.validators import ResponseValidator
from openapi_core.wrappers.mock import MockRequest, MockResponse
# Define a simple OpenAPI spec
oas_spec = {
"openapi": "3.0.0",
"info": {"title": "Test API", "version": "1.0.0"},
"paths": {
"/hello": {
"get": {
"parameters": [
{
"name": "name",
"in": "query",
"required": True,
"schema": {"type": "string"}
}
],
"responses": {
"200": {
"description": "A greeting",
"content": {
"application/json": {
"schema": {"type": "object", "properties": {"message": {"type": "string"}}}
}
}
}
}
}
}
}
}
# Load the OpenAPI specification
openapi = OpenAPI.from_dict(oas_spec)
# --- Request Validation ---
# Create a mock request for validation
request = MockRequest(
host_url="http://localhost",
path="/hello",
method="get",
query_string="name=World"
)
validator = RequestValidator(openapi)
result = validator.validate(request)
if result.errors:
print(f"Request validation errors: {result.errors}")
else:
print("Request validated successfully.")
# Access validated parameters
print(f"Validated query parameters: {result.parameters.query}")
# --- Response Validation ---
# Create a mock response for validation
response = MockResponse(
data=io.BytesIO(b'{"message": "Hello, World!"}'),
status_code=200,
mimetype="application/json"
)
validator = ResponseValidator(openapi)
result = validator.validate(request, response)
if result.errors:
print(f"Response validation errors: {result.errors}")
else:
print("Response validated successfully.")
Debug
Known issues
breakingSupport for Python 3.9 was dropped in version 0.23.0b1. Support for Python 3.8 was dropped in version 0.20.0.fixUpgrade your Python environment to 3.10 or newer.
affects: 0.20.0, 0.23.0b1 and later
breakingWith the introduction of OpenAPI 3.2 support, older 'V3 aliases' for specification components have been moved to 'V32' paths. For example, if you were directly importing from `openapi_core.spec.v3_0` it might need adjustment if those aliases were changed or removed.fixReview your imports related to `openapi_core.spec` and adjust them to the new V32 structure or use the main `OpenAPI` class for abstraction where possible.
affects: 0.23.0 and later
deprecatedThe `spec_base_uri` configuration parameter for `OpenAPI` initialization is deprecated.fixUse the `base_uri` parameter directly in `OpenAPI.from_dict()` or `OpenAPI.from_file()` instead.
affects: 0.19.3 and later
breakingThe defaults for `style_deserializers_factory` and `media_tyles_deserialization_factory` in configuration and protocols were changed to `None`.fixIf you relied on implicit defaults, you might need to explicitly configure these factories or update your code to handle `None` where a default factory was previously expected.
affects: 0.22.0 and later
gotchaVersion 0.23.0 introduced an opt-in strict mode for omitted `additionalProperties`. By default, `additionalProperties` are allowed if not explicitly forbidden in the schema, but this mode can make validation stricter.fixIf you encounter unexpected validation errors for properties not explicitly defined in your OpenAPI schema, consider whether you have enabled the strict mode or if your schema implicitly disallows additional properties. Adjust your schema or disable strict mode if necessary.
affects: 0.23.0 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'openapi_core.schema.exceptions' OR ImportError: cannot import name 'OpenAPI' from 'openapi_core'
The internal structure and top-level imports of `openapi-core` have changed across different versions, leading to incorrect import paths for classes like `OpenAPI` or specific exception types.
fixFor `ModuleNotFoundError` related to `openapi_core.schema.exceptions`, update your import from `from openapi_core.schema.exceptions import OpenAPIError` to `from openapi_core.exceptions import OpenAPIError`. For `ImportError: cannot import name 'OpenAPI' from 'openapi_core'`, ensure you are using the correct import path as per the version you have installed; for recent versions (>=0.17.0), `OpenAPI` is typically imported directly from the top-level package: `from openapi_core import OpenAPI`.
Validation error: 'X' is a required property
A request or response being validated against the OpenAPI specification is missing a mandatory property ('X') that is marked as `required` in the schema.
fixEnsure that the JSON body, query parameters, or headers of your request/response include all properties defined as `required` in the corresponding OpenAPI specification schema. Consult your OpenAPI document for the exact required fields.
openapi_core.templating.paths.finders.PathNotFound
`openapi-core` could not find a matching path template in your OpenAPI specification for the URL of the incoming request. This can happen due to mismatches in the URL structure or issues with templated path parameters (e.g., special characters in path parameters not being correctly parsed).
fixVerify that the URL being validated exactly matches a path defined in your OpenAPI specification, including any templated parameters like `{id}`. Ensure that path parameters in your spec do not contain unsupported special characters (like hyphens, which caused issues in older versions) that might prevent `openapi-core` from correctly matching the path. openapi_core.casting.schemas.exceptions.CastError: Failed to cast value to object type
The data provided in the request or response does not conform to the expected data type defined in your OpenAPI schema, and `openapi-core` failed to cast it to the correct Python type (e.g., a string was received where an integer was expected, or a non-dict value was given for an object schema).
fixInspect the value that caused the `CastError` and compare its type and structure against the OpenAPI schema definition for that field. Adjust the incoming data to match the expected type (e.g., send an integer instead of a string if `type: integer` is specified).
Upgrade
Version history
0.23.1latest on PyPI · released Apr 2, 2026
Audit
Dependencies
jsonschemarequiredUsed for schema validation, core dependency.
openapi-spec-validatorrequiredUsed for validating the OpenAPI specification itself.
flaskoptionalOptional integration for Flask applications.
starletteoptionalOptional integration for Starlette/FastAPI applications.
falconoptionalOptional integration for Falcon applications.
djangooptionalOptional integration for Django applications.
aiohttpoptionalOptional integration for aiohttp applications.