openapi_problemdetails.yaml

openapi: 3.0.3
info:
  title: Problem Details for HTTP APIs
  description: |
    This OpenAPI specification template contains the Problem Details schemas for HTTP APIs, including an example path.

    You can either copy the schemas and responses from the components section into your existing specification or
    use this template as the basis for your API design document.
  version: 1.0.0

paths:
  /example:
    post:
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                example:
                  type: boolean
              required:
                - example
      responses:
        201:
          description: Success!
        400:
          $ref: '#/components/responses/InvalidRequestProblemDetailsResponse'
        415:
          $ref: '#/components/responses/InvalidRequestContentTypeResponse'
        default:
          $ref: '#/components/responses/DefaultProblemResponse'
      tags:
        - Example path

components:
  schemas:
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          format: uri
          default: 'about:blank'
          description: |
            A URI reference that identifies the problem type.
            It should point to human-readable documentation.
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        instance:
          type: string
          format: uri
          description: A URI reference that identifies the specific occurrence of the problem.
      required:
        - type
        - title
        - status
      example:
        type: 'about:blank'
        title: 'An error occurred.'
        status: 500
      externalDocs:
        description: 'RFC 7807: Problem Details for HTTP APIs'
        url: 'https://datatracker.ietf.org/doc/html/rfc7807'

    InvalidContentTypeProblemDetails:
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
      example:
        type: 'about:blank'
        title: 'The content type is not supported.'
        status: 415
        detail: "The request content-type must be 'application/json'."

    InvalidRequestBodyProblemDetails:
      allOf:
        - $ref: '#/components/schemas/ProblemDetails'
        - type: object
          properties:
            violations:
              type: array
              items:
                $ref: '#/components/schemas/Violation'
          required:
            - violations
      example:
        type: 'about:blank'
        title: 'The request body contains errors.'
        status: 400
        detail: "The request body should be valid JSON."
        violations:
          - constraint: 'valid_json'
            message: "Parse error on line 1:\n\n^\nExpected one of: 'STRING', 'NUMBER', 'NULL', 'TRUE', 'FALSE', '{', '['"

    Violation:
      type: object
      properties:
        constraint:
          type: string
          description: The type of constraint that was violated.
        message:
          type: string
          description: A human-readable explanation of the violation and/or how to correct it.
        property:
          type: string
          description: The property of the request body that contains the specific occurrence of the violation.
      required:
        - constraint
        - message

  responses:
    InvalidRequestContentTypeResponse:
      description: The request content-type is not supported.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InvalidContentTypeProblemDetails'

    InvalidRequestProblemDetailsResponse:
      description: The received request is invalid.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InvalidRequestBodyProblemDetails'

    DefaultProblemResponse:
      description: An error occurred.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'