unmarshalling.md

hide	navigation

Unmarshalling

Unmarshalling is the process of converting a primitive schema type value into a higher-level object based on a format keyword. All request/response data that can be described by a schema in the OpenAPI specification can be unmarshalled.

Unmarshallers first validate data against the provided schema (See Validation).

Openapi-core comes with a set of built-in format unmarshallers:

• date - converts a string into a date object,
• date-time - converts a string into a datetime object,
• binary - converts a string into a byte object,
• uuid - converts a string into a UUID object,
• byte - decodes a Base64-encoded string.

You can also define your own format unmarshallers (See Extra Format Unmarshallers).

Request unmarshalling

Use the unmarshal_request method to validate and unmarshal request data against a given spec. By default, the OpenAPI spec version is detected:

# raises an error if the request is invalid
result = openapi.unmarshal_request(request)

The request object should implement the OpenAPI Request protocol (See Integrations).

!!! note

The Webhooks feature is part of OpenAPI v3.1+.

Use the same method to validate and unmarshal webhook request data against a given spec.

# raises an error if the request is invalid
result = openapi.unmarshal_request(webhook_request)

The webhook request object should implement the OpenAPI WebhookRequest protocol (See Integrations).

Retrieve validated and unmarshalled request data:

# get parameters
path_params = result.parameters.path
query_params = result.parameters.query
cookies_params = result.parameters.cookies
headers_params = result.parameters.headers
# get body
body = result.body
# get security data
security = result.security

You can also define your own request unmarshaller (See Request Unmarshaller).

Response unmarshalling

Use the unmarshal_response method to validate and unmarshal response data against a given spec. By default, the OpenAPI spec version is detected:

# raises an error if the response is invalid
result = openapi.unmarshal_response(request, response)

The response object should implement the OpenAPI Response protocol (See Integrations).

!!! note

The Webhooks feature is part of OpenAPI v3.1+.

Use the same method to validate and unmarshal response data from a webhook request against a given spec.

# raises an error if the request is invalid
result = openapi.unmarshal_response(webhook_request, response)

Retrieve validated and unmarshalled response data:

# get headers
headers = result.headers
# get data
data = result.data

You can also define your own response unmarshaller (See Response Unmarshaller).