Specify allowed values for error status and code in the error schema

[jlurien]

Problem description

Currently we document error responses with a common ErrorInfo schema:

  ErrorInfo:
    type: object
    required:
      - message
      - status
      - code
    properties:
      message:
        type: string
        description: A human readable description of what the event represent
      status:
        type: integer
        description: HTTP response status code
      code:
        type: string
        description: Friendly Code to describe the error

And then examples are provided to illustrate the error cases, with the model:

    ErrorResponseSchema:
      ...
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorInfo'
          examples:
            ExampleKey1:
              value:
                status: <status>
                code: <code1>
                message: <message1>
            ExampleKey2:
              value:
                status: <status>
                code: <code2>
                message: <message2>

Specification by examples is not normative. This strictly allows any code to be sent, and setting any integer for status and string for code would pass any standard tool validation.

Possible evolution

The way to enforce a subset of values for status and code is specifying the allowed values as an enum:

    ErrorResponseSchema:
      ...
      content:
        application/json:
          schema:
            allOf:
              - $ref: '#/components/schemas/ErrorInfo'
              - type: object
                properties:
                  status:
                    enum:
                      - <status>
                  code:
                    enum:
                      - <code1>
                      - <code2>
          examples:
            ExampleKey1:
              value:
                status: <status>
                code: <code1>
                message: <message1>
            ExampleKey2:
              value:
                status: <status>
                code: <code2>
                message: <message2>

The allOf in content.application/json.schema allows a combination of both the generic ErrorInfo schema and the specific schema for this error response, which validates that status and code have only the specified values. This allOf is used without discriminator because it does not imply any hierarchy between the models, just 2 schemas that must be independently validated.

[PedroDiez]

Related to cover actions under the scope of Issues #162, #180