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 the application/problem+json media type, and its schema is an object with the properties type (a string with format: uri), title (a string), status (an integer), detail (a string) and instance (a string with format: uri).
  • json-api, the JSON:API error objects: the response has the application/vnd.api+json media type, and its schema is an object whose errors property 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
Was this helpful?