standard-response-errors

This rule ensures that bodies for “error” responses are adhere to the same convention.

Rule Details

Having errors formatted in the same way significantly simplifies their handling.

The standard-response-errors rule is designed to ensure that the bodies of all responses for 4xx and 5xx codes in a schema adhere to the same convention.

Currently supported conventions are:

Problem JSON. This convention provides a standardized format for sending details about errors in HTTP APIs, enhancing the consistency and interoperability of the API’s structure.
JSON API. By this convention, a response body is an array of Error objects, as defined in JSON:API specification.

Configuration

The configuration is a single string representing the desired convention.

Currently supported values are:

problem-json - Problem JSON. This is the default value
json-api - convention, where a response body is a list of JSON:API Error objects

Configuration Example

lint:
  standard-response-errors:
    - error
    - problem-json

Examples

Good.

paths:
  /users:
    get:
      responses:
        "400":
          description: Bad Request
          content:
            application/problem+json:
              schema:
                type: object
                properties:
                  type:
                    type: string
                  title:
                    type: string
                  status:
                    type: integer
                  detail:
                    type: string

Bad.

paths:
  /users:
    get:
      responses:
        "400":
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string

When Not to Use It

When your team or organisation has different conventions for formatting errors.

Compatibility

This rule is compatible with all OpenAPI 3.x versions.