AshOaskit.
View Source
Generates JSON:API compliant error response schemas for OpenAPI specs.
This module provides standard error response schemas following the JSON:API specification format. These schemas can be used in OpenAPI response definitions for error status codes.
JSON:API Error Format
The JSON:API specification defines a standard error object structure:
{
"errors": [
{
"id": "unique-error-id",
"status": "422",
"code": "validation_error",
"title": "Invalid Attribute",
"detail": "First name must be at least 2 characters",
"source": {
"pointer": "/data/attributes/first_name",
"parameter": "filter[name]"
},
"meta": {
"field": "first_name"
}
}
]
}Error Response Codes
This module generates schemas for common HTTP error status codes:
400- Bad Request (malformed request syntax)401- Unauthorized (authentication required)403- Forbidden (authorization failed)404- Not Found (resource doesn't exist)409- Conflict (resource conflict, e.g., duplicate)422- Unprocessable Entity (validation errors)500- Internal Server Error (server-side failures)
Usage
# Get the standard JSON:API error schema
schema = ErrorSchemas.error_response_schema()
# Get error responses for a specific set of status codes
responses = ErrorSchemas.error_responses(["400", "404", "422"])
# Get all standard error responses
responses = ErrorSchemas.all_error_responses()
# Add error schemas to components
components = ErrorSchemas.add_error_components(existing_components)Summary
Functions
Adds error schema components to an existing components map.
Returns all standard error responses.
Returns common error responses for create operations.
Returns common error responses for delete operations.
Returns the standard JSON:API error object schema.
Returns an error response object for a specific status code.
Returns the JSON:API error response envelope schema.
Returns error responses for the specified status codes.
Returns a simple error response without $ref (inline schema).
Returns common error responses for read operations.
Returns responses for a specific operation type.
Returns common error responses for update operations.
Functions
Adds error schema components to an existing components map.
This adds the JsonApiError and JsonApiErrorObject schemas to
the components schemas section.
Parameters
components- Existing OpenAPI components map
Returns
Updated components map with error schemas added.
Examples
iex> ErrorSchemas.add_error_components(%{schemas: %{}})
%{
schemas: %{
"JsonApiError" => %{...},
"JsonApiErrorObject" => %{...}
}
}@spec all_error_responses() :: map()
Returns all standard error responses.
Includes responses for: 400, 401, 403, 404, 409, 422, 500.
Returns
A map of status codes to response objects.
@spec create_error_responses() :: map()
Returns common error responses for create operations.
Includes: 400, 401, 403, 409, 422.
Returns
A map of status codes to response objects.
@spec delete_error_responses() :: map()
Returns common error responses for delete operations.
Includes: 401, 403, 404.
Returns
A map of status codes to response objects.
@spec error_object_schema() :: map()
Returns the standard JSON:API error object schema.
This schema represents a single error object as defined by the JSON:API specification.
Returns
A map representing the OpenAPI schema for a single error object.
Examples
iex> schema = ErrorSchemas.error_object_schema()
...> schema[:type]
:object
iex> Map.has_key?(schema[:properties], :id)
true
iex> Map.has_key?(schema[:properties], :status)
trueReturns an error response object for a specific status code.
Generates an OpenAPI response object with appropriate description and schema for the given HTTP status code.
Parameters
status_code- The HTTP status code as a string
Returns
A map representing the OpenAPI response object.
Examples
iex> ErrorSchemas.error_response("404")
%{
description: "Resource not found",
content: %{
"application/vnd.api+json" => %{
schema: %{"$ref" => "#/components/schemas/JsonApiError"}
}
}
}@spec error_response_schema() :: map()
Returns the JSON:API error response envelope schema.
This wraps error objects in the standard errors array format.
Returns
A map representing the OpenAPI schema for an error response.
Examples
iex> ErrorSchemas.error_response_schema()
%{
type: :object,
properties: %{
errors: %{
type: :array,
items: %{...}
}
}
}Returns error responses for the specified status codes.
Parameters
status_codes- List of HTTP status codes as strings
Returns
A map of status codes to response objects.
Examples
iex> ErrorSchemas.error_responses(["400", "404"])
%{
"400" => %{...},
"404" => %{...}
}Returns a simple error response without $ref (inline schema).
Useful when you don't want to use component references.
Parameters
status_code- The HTTP status code as a string
Returns
A map with inline error schema.
@spec read_error_responses() :: map()
Returns common error responses for read operations.
Includes: 400, 401, 403, 404.
Returns
A map of status codes to response objects.
Returns responses for a specific operation type.
Parameters
operation_type- One of:read,:create,:update,:delete
Returns
A map of status codes to response objects.
@spec update_error_responses() :: map()
Returns common error responses for update operations.
Includes: 400, 401, 403, 404, 409, 422.
Returns
A map of status codes to response objects.