standard-response-errors
Since 0.0.1 · In the rulesets: Strict at warning, All at warning
This rule checks that every 4xx and 5xx response has the error format of one convention, Problem Details (RFC 9457) unless configured otherwise.
Rule details
A client handles errors in one place when every error has the same shape; with one shape per operation, it handles them in each call, or not at all. The conventions the rule knows:
problem-json, Problem Details for HTTP APIs: the response has theapplication/problem+jsonmedia type, and its schema is an object with the propertiestype(a string withformat: uri),title(a string),status(an integer),detail(a string) andinstance(a string withformat: uri).json-api, the JSON:API error objects: the response has theapplication/vnd.api+jsonmedia type, and its schema is an object whoseerrorsproperty is an array of objects.
The rule reports Response must use Problem JSON format or Response must use JSON:API error format when the media type is missing, and Response must use correct Problem JSON schema or
Response must use correct JSON:API error schema when the schema is not the one above. It is in
the strict and all rulesets; turn it off when the API has an error format of its own.
Configuration
A convention name, problem-json or json-api. problem-json by default.
Configuration example. JSON:API errors.
commands:
lint:
rules:
standard-response-errors:
- error
- json-api
Examples
Good. A Problem Details response.
paths:
/users:
get:
responses:
"400":
description: Bad Request
content:
application/problem+json:
schema:
type: object
properties:
type:
type: string
format: uri
title:
type: string
status:
type: integer
detail:
type: string
instance:
type: string
format: uri
Bad. An error shape of its own.
paths:
/users:
get:
responses:
"400":
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
Good. With the json-api convention.
paths:
/users:
get:
responses:
"400":
description: Bad Request
content:
application/vnd.api+json:
schema:
type: object
properties:
errors:
type: array
items:
type: object
properties:
status:
type: string
title:
type: string
detail:
type: string
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.rules has the details.
commands:
lint:
rules:
standard-response-errors: off