#   Copyright 2023-2025 SmartBear
#
#   Licensed under the Apache License, Version 2.0 (the "License");
#   you may not use this file except in compliance with the License.
#   You may obtain a copy of the License at
#
#       http://www.apache.org/licenses/LICENSE-2.0
#
#   Unless required by applicable law or agreed to in writing, software
#   distributed under the License is distributed on an "AS IS" BASIS,
#   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
#   See the License for the specific language governing permissions and
#   limitations under the License.

$schema: 'https://json-schema.org/draft//schema'
$id: 'https://problems-registry.smartbear.com/ProblemDetails/1.0.0'
$ref: '#/$defs/ProblemDetails'

$defs:

  ErrorDetail:
    type: object
    description: >-
      An object to provide explicit details on a problem towards an API consumer.
    required:
      - detail
    properties:
      detail:
        type: string
        description: >-
          A granular description on the specific error related to a body
          property, query parameter, path parameters, and/or header.
        maxLength: 4096
      pointer:
        type: string
        description: >-
          A JSON Pointer to a specific request body property that is the
          source of error.
        maxLength: 1024
      parameter:
        type: string
        description: The name of the query or path parameter that is the source of error.
        maxLength: 1024
      header:
        type: string
        description: The name of the header that is the source of error.
        maxLength: 1024
      code:
        type: string
        description: >-
          A string containing additional provider specific codes to identify
          the error context.
        maxLength: 50

  ProblemDetails:
    type: object
    description: >-
      The `ProblemDetails` object provides detailed information about an errors that occurred during an API call execution.
      This problem object conforms to the [RFC9457](https://www.rfc-editor.org/info/rfc9457) (formerly [RFC7807](https://tools.ietf.org/html/rfc7807)).

      The object is extended with the following properties:
      - `code` - a string identifier to aid the provider team better understand the error
      - `errors` - and array of errors providing contextual information on the root cause of the problem

      The `ProblemDetails` referenced by this domain utilize the [SmartBear Problems Registry](https://problems-registry.smartbear.com/).
    required:
      - detail
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        maxLength: 1024
        enum:
        - 'about:blank'
        - 'https://problems-registry.smartbear.com/already-exists'
        - 'https://problems-registry.smartbear.com/bad-request'
        - 'https://problems-registry.smartbear.com/business-rule-violation'
        - 'https://problems-registry.smartbear.com/forbidden'
        - 'https://problems-registry.smartbear.com/invalid-body-property-format'
        - 'https://problems-registry.smartbear.com/invalid-body-property-value'
        - 'https://problems-registry.smartbear.com/invalid-parameters'
        - 'https://problems-registry.smartbear.com/invalid-request-header-format'
        - 'https://problems-registry.smartbear.com/invalid-request-parameter-format'
        - 'https://problems-registry.smartbear.com/invalid-request-parameter-value'
        - 'https://problems-registry.smartbear.com/license-cancelled'
        - 'https://problems-registry.smartbear.com/license-expired'
        - 'https://problems-registry.smartbear.com/missing-body-property'
        - 'https://problems-registry.smartbear.com/missing-request-header'
        - 'https://problems-registry.smartbear.com/not-found'
        - 'https://problems-registry.smartbear.com/server-error'
        - 'https://problems-registry.smartbear.com/service-unavailable'
        - 'https://problems-registry.smartbear.com/unauthorized'
        - 'https://problems-registry.smartbear.com/validation-error'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        minimum: 100
        maximum: 599
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        maxLength: 1024
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        maxLength: 4096
      instance:
        type: string
        description: >-
          A URI reference that identifies the specific occurrence of the problem. It
          may or may not yield further information if dereferenced.
        maxLength: 1024
      code:
        type: string
        description: >-
          An API specific error code aiding the provider team understand the error
          based on their own potential taxonomy or registry.
        maxLength: 50
      errors:
        type: array
        description: An array of error details to accompany a problem details response.
        maxItems: 1000
        items:
          $ref: '#/$defs/ErrorDetail'

# Utility objects

  AlreadyExists:
    type: object
    description: >-
      This problem occurs when the resource being created is found to already exist on the server.

      Your client application tried to create a resource that already exists. Perhaps review your client logic to determine if a user should be able to send such a request.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/already-exists'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 409
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Already exists'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The resource being created already exists.'

  BadRequest:
    type: object
    description: >-
      The server cannot or will not process the request due to something that is perceived to be a client error (for example, malformed request syntax, invalid request message framing, or deceptive request routing).

      Your client application initiated a request that is malformed. Please review your client request against the defined semantics for the API.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/bad-request'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Bad Request'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request is invalid or malformed.'

  BusinessRuleViolation:
    type: object
    description: >-
      This problem occurs when the request is deemed invalid as it fails to meet business rule expectations.

      Your client issued a request that failed business rule validation. Please review your request to determine if you can remain within appropriate business rules.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/business-rule-violation'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 422
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Business Rule Violation'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request body is invalid and not meeting business rules.'

  Forbidden:
    type: object
    description: >-
      This problem occurs when the requested resource (and/or operation combination) is not authorized for the requesting client (and or authorization context).

      Your client application tried to perform an operation on a resource that it's not authorized to perform in the given context.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/forbidden'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 403
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Forbidden'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The resource could not be returned as the requestor is not authorized.'

  InvalidBodyPropertyFormat:
    type: object
    description: >-
      This problem occurs when the request body contain a malformed property.

      Your client issued a request that contained a malformed body property. Please review your request and compare against the shared API definition.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/invalid-body-property-format'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Invalid Body Property Format'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request body contains a malformed property.'

  InvalidBodyPropertyValue:
    type: object
    description: >-
      This problem occurs when the request body contains a invalid property value.

      Your client issued a request that contained an invalid body property value. Please review your request and compare against the shared API definition where applicable.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/invalid-body-property-value'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Invalid Body Property Value'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request body contains an invalid body property value.'

  InvalidParameters:
    type: object
    description: >-
      This problem occurs when a client request contains invalid or malformed parameters causing the server to reject the request.

      Your client application issued a request to an API that contains invalid or malformed parameters.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/invalid-parameters'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Invalid parameters'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request contained invalid, or malformed parameters (path or header or query).'

  InvalidRequestHeaderFormat:
    type: object
    description: >-
      This problem occurs when the request contains a malformed request header.

      Your client issued a request that contained a malformed request header. Please review your request parameters and compare against the shared API definition when applicable.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/invalid-request-header-format'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Invalid Request Header Format'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request contains a malformed request header parameter.'

  InvalidRequestParameterFormat:
    type: object
    description: >-
      This problem occurs when the request contains a malformed query or path parameter.

      Your client issued a request that contained a malformed query or path parameter.
      Please review your request parameters and compare against the shared API definition.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/invalid-request-parameter-format'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Invalid Request Parameter Format'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request contains a malformed request query parameter.'

  InvalidRequestParameterValue:
    type: object
    description: >-
      This problem occurs when the request contains a invalid query or path parameter value.

      Your client issued a request that contained an invalid query or path parameter value.
      Please review your request and compare against the shared API definition where applicable.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/invalid-request-parameter-value'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Invalid Request Parameter Value'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request body contains an invalid request parameter value.'

  LicenseCancelled:
    type: object
    description: >-
      This problem occurs when the license associated with the client has been cancelled thus rendering the service unavailable.

      The license associated with your client/organization has been cancelled.
      Please contact your account manager or representative.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/license-cancelled'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 503
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'License Cancelled'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The service is unavailable as the license associated with your client or organization has been cancelled. Please contact your account manager or representative.'

  LicenseExpired:
    type: object
    description: >-
      This problem occurs when the license associated with the client has expired thus rendering the service unavailable.

      The license associated with your client/organization has expired.
      Please contact your account manager or representative.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/license-expired'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 503
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'License Expired'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The service is unavailable as the license associated with your client or organization has expired. Please contact your account manager or representative.'

  MissingBodyProperty:
    type: object
    description: >-
      This problem occurs when the request sent to the API is missing an expected body property.

      Your client issued a request that omitted an expected body property.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/missing-body-property'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Missing body property'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request is missing an expected body property.'

  MissingRequestHeader:
    type: object
    description: >-
      This problem occurs when the request sent to the API is missing an expected request header.

      Your client issued a request that omitted an expected request header.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/missing-request-header'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Missing request header'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request is missing an expected HTTP request header.'

  MissingRequestParameter:
    type: object
    description: >-
      This problem occurs when the request sent to the API is missing an query or path parameter.

      Your client issued a request that omitted an expected query or path par.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/missing-request-parameter'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 400
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Missing request parameter'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request is missing an expected query or path parameter.'

  NotFound:
    type: object
    description: >-
      This problem occurs when the requested resource could not be found.

      Your client application tried to access a resource that does not exist (or could not be found).
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/not-found'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 404
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Not Found'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The requested resource was not found.'

  ServerError:
    type: object
    description: >-
      This problem occurs when the server encounters an unexpected condition that prevents it from fulfilling the request.

      Your client application did everything correct. Unfortunately our API encountered a condition that resulted in this problem.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/server-error'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 500
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Server Error'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The server encountered an unexpected error.'

  ServiceUnavailable:
    type: object
    description: >-
      This problem occurs when the service requested is currently unavailable and the server is not ready to handle the request.

      Your client application did everything correct. Unfortunately our API is currently unavailable.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/service-unavailable'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 503
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Service Unavailable'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The service is currently unavailable.'

  Unauthorized:
    type: object
    description: >-
      This problem occurs when the requested resource could not be returned as the client request lacked valid authentication credentials.

      Your client application issued a requested to a protected resource without supplying the required auth details.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/unauthorized'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 401
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Unauthorized'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'Access token not set or invalid, and the requested resource could not be returned.'

  ValidationError:
    type: object
    description: >-
      This problem occurs when the request is deemed unprocessable.

      Your client issued a request that failed validation. Certain validation libraries return multi-errors and cannot be easily parsed into discreet types. This problem type, afforded the provider with the ability to surface all validation errors and negate the need for a trial and error workflow on your side. 

      Please review your request to determine if you can remain within appropriate business rules. Consider validating your request against available metadata (e.g. schemas) prior to sending to the server.
    allOf:
    - $ref: "#/$defs/ProblemDetails"
    properties:
      type:
        type: string
        description: A URI reference that identifies the problem type.
        format: uri
        const: 'https://problems-registry.smartbear.com/validation-error'
      status:
        type: integer
        description: >-
          The HTTP status code generated by the origin server for this occurrence of
          the problem.
        format: int32
        const: 422
      title:
        type: string
        description: >-
          A short, human-readable summary of the problem type. It should not change
          from occurrence to occurrence of the problem, except for purposes of
          localization.
        const: 'Validation Error'
      detail:
        type: string
        description: A human-readable explanation specific to this occurrence of the problem.
        const: 'The request is not valid.'