standard-response-errors

Since 0.0.1

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

Good with the json-api convention. The response must use the application/vnd.api+json media type, and its schema must be an object whose errors property is an array of objects.

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

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.