Response schemas tell API consumers exactly what data structure, data types, headers, and status codes to expect. Incomplete response schemas lead to runtime crashes and unhandled exceptions in client code.
1. Response Schema Declaration Rules
- Explicit Status Codes: Model specific HTTP status codes ('200', '201', '400', '401', '404', '500') rather than relying solely on default.
- Strict Required Arrays: Specify the required array on all component schemas so client SDK generators do not mark all properties as optional.
- Model Response Headers: Declare rate-limiting (X-RateLimit-Remaining) and location headers (Location) inside the response definition.
response-schema-example.yaml
responses:
'201':
description: Resource successfully created
headers:
Location:
description: URI of the newly created resource
schema:
type: string
format: uri
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerAccount'
'400':
description: Invalid payload syntax or validation error
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetails'Analyze Response Schema Completeness
Run APIForge to check if your API endpoints define explicit response schemas for all expected HTTP success and error status codes.