OpenAPI data types for problem messages, compliant to RFC 9457 - Problem Details for HTTP APIs (which obsoletes RFC 7807)

problem.yaml

openapi: 3.0.0 #Ref: https://github.com/belgif/openapi-problem/blob/6d8c8839130a3e7dd459ad08989b8bec1bae982a/src/main/openapi/problem/v1/problem-v1.yaml
info:
  title: problem types
  version: "${project.version}"
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers: []
paths: {}
components:
  responses:
    ProblemResponse:
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
      description: a problem
    InputValidationProblemResponse:
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/InputValidationProblem"
      description: A problem caused by invalid input
  schemas:
    Problem:
      description: |
        A Problem Details object (RFC 9457).
        
        Additional properties specific to the problem type may be present.    
      type: object
      properties:
        type:
          type: string
          format: uri
          description: An absolute URI that identifies the problem type
          default: about:blank  # kept for backwards-compatibility, type will be mandatory in problem-v2
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML).
        title:
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 400
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
        instance:
          type: string
          format: uri
          description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
      example:
        type: urn:problem-type:exampleOrganization:exampleProblem # "exampleOrganization" should be a short identifier for the organization that defines the problem type. "belgif" is used for problem types standardized in the Belgif REST guide
        href: "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types" # optional, should refer to documentation of the problem type, either of a belgif standardized or a custom problem type
        title: Description of the type of problem that occurred
        status: 400 # HTTP response status, appropriate for the problem type
        detail: Description of specific occurrence of the problem
        instance: urn:uuid:123e4567-e89b-12d3-a456-426614174000
    InvalidParamProblem:
      deprecated: true # deprecated by InputValidationProblem
      description: Problem details for invalid input parameter(s)
      type: object
      allOf:
        - $ref: "#/components/schemas/Problem"
      properties:
        invalidParams:
          type: array
          description: An array of parameter OpenAPI violations
          items:
            $ref: "#/components/schemas/InvalidParam"
    InvalidParam:
      deprecated: true # deprecated by InputValidationIssue (within an InputValidationProblem)
      type: object
      properties:
        in:
          description: The location of the invalid parameter (cfr Swagger parameters)
          type: string
          enum:
            - body
            - path
            - query
            - header
        name:
          description: The name of the invalid parameter
          type: string
        value:
          description: The value of the erroneous parameter
          # no type specified, allowing any type. This is valid OpenAPI 3.0 even though some editors may indicate an error (issue #25)
    InputValidationProblem:
      type: object
      allOf:
      - $ref: "#/components/schemas/Problem"
      properties:
        issues:
          type: array
          items:
            $ref: "#/components/schemas/InputValidationIssue"
      example:
        type: urn:problem-type:belgif:badRequest
        href: https://www.belgif.be/specification/rest/api-guide/problems/badRequest.html
        title: Bad Request
        status: 400
        detail:  "The input message is incorrect"
        instance: urn:uuid:123456-1234-1235-4567489798
        issues:
          - type: urn:problem-type:belgif:input-validation:schemaViolation # type is mandatory, can be a standard belgif issue type or a custom one
            # href: (TODO: provide dereferenceable link with documentation for standard belgif input validation problems)
            detail: exampleNumericProperty with value xyz should be numeric # detail is optional
            in: path
            name: exampleNumericProperty
            value: abc
          - type: urn:problem-type:belgif:input-validation:schemaViolation
            title: "Input isn't valid with respect to schema"
            detail: "examplePropertyWithPattern a2345678901 doesn't match pattern '^\\d{11}$'"
            in: body
            name: items[0].examplePropertyWithPattern # location within the body
            value: "a2345678901"
    InputValidationIssue:
      type: object
      description: |
        An issue detected during input validation.

        `status` is usually not present.
        `href`, if present, refers to documentation of the issue type.
        Additional properties specific to the issue type may be present.
      allOf:
        - $ref: "#/components/schemas/Problem"
      properties:
        in:
          type: string
          description: The location of the invalid input
          enum:
            - body
            - header
            - path
            - query
        name:
          type: string
          description: The name of the invalid input
        value:
          description: The value of the erroneous input
          # no type specified, allowing any type. This is valid in OpenAPI even though some editors may indicate an error