AEP-0193 Linter Rules

Rules for AEP-193- Errors

# Rules for AEP-193: Errors

aep-193-error-response-schema

Rule: Error response schema should contain all required fields of the correct type.

This rule enforces that all 4xx and 5xx responses have valid schema according to AEP-193 rule.

Details

This rule looks at the 4xx and 5xx responses and reports if either one of required parameters is missing or if it has incorrect type.

Examples

Incorrect code for this rule:

paths:
  '/test1':
    get:
      description: '404 response schema is missing required fields: type, detail, instance and title'
      responses:
        200:
          content:
            'application/json':
              schema:
                type: 'object'
                properties:
                  results:
                    type: string
        404:
          content:
            'application/json':
              schema:
                type: 'object'
                properties:
                  status:
                    type: 'integer'
  '/test2':
    get:
      description: '404 response schema detail property is of incorrect type'
      404:
        content:
          'application/json':
            schema:
              type: 'object'
              properties:
                status:
                  type: 'integer'
                type:
                  type: 'string',
                detail:
                  type: 'integer',
                instance:
                  type: 'string',
                title:
                  type: 'string',

Correct code for this rule:

paths:
  '/books':
    get:
      responses:
        404:
          content:
            'application/json':
              schema:
                title: An RFC 7807 problem object
                type: object
                properties:
                  type:
                    type: string
                    format: uri-reference
                    description:
                      A URI reference that identifies the problem type.
                  title:
                    type: string
                    description:
                      A short, human-readable summary of the problem type.
                  status:
                    type: integer
                    description:
                      The HTTP status code generated by the origin server for
                      this occurrence of the problem.
                    minimum: 100
                    maximum: 599
                  detail:
                    type: string
                    description:
                      A human-readable explanation specific to this occurrence
                      of the problem.
                  instance:
                    type: string
                    format: uri-reference
                    description:
                      A URI reference that identifies the specific occurrence
                      of the problem. It may or may not yield further
                      information if dereferenced.

Or:

paths:
  '/books':
    get:
      responses:
        404:
          content:
            'application/json':
              schema:
                '$ref': 'https://aep.dev/json-schema/type/problems.json'

Disabling

If you need to violate this rule for a specific operation, add an “override” to the Spectral rule file for the specific file and fragment.

overrides:
  - files:
      - 'openapi.json#/books/get'
    rules:
      aep-193-error-response-schema: 'off'

If you need to violate this rule for an entire file, add an “override” to the Spectral rule file for the specific file without a fragment.