Specify allowed values for error status and code in the error schema #196
Description
Problem description
Currently we document error responses with a common ErrorInfo schema:
ErrorInfo:
type: object
required:
- message
- status
- code
properties:
message:
type: string
description: A human readable description of what the event represent
status:
type: integer
description: HTTP response status code
code:
type: string
description: Friendly Code to describe the error
And then examples are provided to illustrate the error cases, with the model:
ErrorResponseSchema:
...
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorInfo'
examples:
ExampleKey1:
value:
status: <status>
code: <code1>
message: <message1>
ExampleKey2:
value:
status: <status>
code: <code2>
message: <message2>
Specification by examples is not normative. This strictly allows any code to be sent, and setting any integer for status and string for code would pass any standard tool validation.
Possible evolution
The way to enforce a subset of values for status and code is specifying the allowed values as an enum:
ErrorResponseSchema:
...
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/ErrorInfo'
- type: object
properties:
status:
enum:
- <status>
code:
enum:
- <code1>
- <code2>
examples:
ExampleKey1:
value:
status: <status>
code: <code1>
message: <message1>
ExampleKey2:
value:
status: <status>
code: <code2>
message: <message2>
The allOf in content.application/json.schema allows a combination of both the generic ErrorInfo schema and the specific schema for this error response, which validates that status and code have only the specified values. This allOf is used without discriminator because it does not imply any hierarchy between the models, just 2 schemas that must be independently validated.