Skip to content

openapi.md

Latest commit

 

History

History
224 lines (200 loc) · 9.25 KB

openapi.md

File metadata and controls

224 lines (200 loc) · 9.25 KB

OpenAPI / JSON Schema

ProblemDetails object as defined by RFC 9457 (formerly RFC 7807). Returned with Content-Type: application/problem+json.

The library always emits type, title, and status. detail, instance and any extension members (RFC 9457 §3.2) are conditional. The schema below documents two optional extension members:

  • code — API-specific error code (vendor extension).
  • errors — Array of granular error details with { detail, pointer, parameter, header, code }. Accepted but not emitted by the library.

None of these are emitted by the library out of the box.

JSON Schema (Draft 2019-09)

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "title": "ProblemDetails",
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "description": "A URI reference that identifies the problem type. Per RFC 9457, this is a URI-reference (may be relative). Defaults to 'about:blank' when not provided.",
      "format": "uri-reference",
      "maxLength": 1024,
      "default": "about:blank"
    },
    "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
    },
    "status": {
      "type": "integer",
      "description": "The HTTP status code generated by the origin server for this occurrence of the problem. If present, this member is only advisory; the generator MUST use the same status code in the actual HTTP response (RFC 9457 §3.1).",
      "format": "int32",
      "minimum": 100,
      "maximum": 599
    },
    "detail": {
      "type": "string",
      "description": "A human-readable explanation specific to this occurrence of the problem. SHOULD focus on helping the client correct the problem, rather than giving debugging information (RFC 9457 §3.1).",
      "maxLength": 4096
    },
    "instance": {
      "type": "string",
      "description": "A URI reference that identifies the specific occurrence of the problem. SHOULD identify both the specific occurrence and its problem type. It may or may not yield further information if dereferenced (RFC 9457 §3.1).",
      "format": "uri-reference",
      "maxLength": 1024
    },
    "code": {
      "type": "string",
      "description": "Optional API-specific error code (extension member, not part of RFC 9457).",
      "maxLength": 50
    },
    "errors": {
      "type": "array",
      "description": "Array of granular error details. Accepted as an extension member but not emitted by this library.",
      "maxItems": 1000,
      "items": { "$ref": "#/$defs/ErrorDetail" }
    }
  },
  "required": ["type", "title", "status"],
  "additionalProperties": true,
  "$defs": {
    "ErrorDetail": {
      "type": "object",
      "description": "Granular detail for a single problem cause.",
      "properties": {
        "detail":    { "type": "string", "maxLength": 4096 },
        "pointer":   { "type": "string", "maxLength": 1024, "description": "JSON Pointer to a request body property." },
        "parameter": { "type": "string", "maxLength": 1024, "description": "Query or path parameter name." },
        "header":    { "type": "string", "maxLength": 1024, "description": "Request header name." },
        "code":      { "type": "string", "maxLength": 50 }
      },
      "required": ["detail"],
      "additionalProperties": true
    }
  }
}

OpenAPI 3.0 (YAML)

components:
  schemas:
    ProblemDetails:
      type: object
      description: >
        Problem Details object as defined by RFC 9457 (formerly RFC 7807).
        Returned with media type `application/problem+json`.
      required:
        - type
        - title
        - status
      properties:
        type:
          type: string
          format: uri-reference
          maxLength: 1024
          default: 'about:blank'
          description: >
            A URI reference that identifies the problem type. Per RFC 9457
            this is a URI-reference (may be relative). Defaults to
            "about:blank" when not provided.
          example: 'about:blank'
        title:
          type: string
          maxLength: 1024
          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.
          example: 'Not Found'
        status:
          type: integer
          format: int32
          minimum: 100
          maximum: 599
          description: >
            The HTTP status code generated by the origin server for this
            occurrence of the problem. If present, this member is only
            advisory; the generator MUST use the same status code in the
            actual HTTP response (RFC 9457 §3.1).
          example: 404
        detail:
          type: string
          maxLength: 4096
          description: >
            A human-readable explanation specific to this occurrence of the
            problem. SHOULD focus on helping the client correct the problem,
            rather than giving debugging information (RFC 9457 §3.1).
          example: 'Could not find any dragon with ID: 99'
        instance:
          type: string
          format: uri-reference
          maxLength: 1024
          description: >
            A URI reference that identifies the specific occurrence of the
            problem. SHOULD identify both the specific occurrence and its
            problem type. It may or may not yield further information if
            dereferenced (RFC 9457 §3.1).
          example: '/dragons/99'
        code:
          type: string
          maxLength: 50
          description: >
            Optional API-specific error code (extension member, not part of
            RFC 9457).
        errors:
          type: array
          maxItems: 1000
          description: >
            Array of granular error details. Accepted as an
            extension member but not emitted by this library.
          items:
            $ref: '#/components/schemas/ErrorDetail'
      additionalProperties: true

    ErrorDetail:
      type: object
      description: Granular detail for a single problem cause.
      required:
        - detail
      properties:
        detail:
          type: string
          maxLength: 4096
        pointer:
          type: string
          maxLength: 1024
          description: JSON Pointer to a request body property.
        parameter:
          type: string
          maxLength: 1024
          description: Query or path parameter name.
        header:
          type: string
          maxLength: 1024
          description: Request header name.
        code:
          type: string
          maxLength: 50

Programmatic usage — @ApiProblemResponse()

The library ships a NestJS / Swagger decorator that injects the schema above automatically:

import { ApiProblemResponse } from 'nest-problem-details-filter/swagger';

@ApiProblemResponse({ status: 404, type: 'not-found', title: 'Dragon not found' })

It emits content: { 'application/problem+json': { schema: ProblemDetails, example } } and supports retryAfter (auto-documents the Retry-After header), baseUri (resolves relative types into absolute URIs to match the runtime filter), and explicit schema / examples overrides.

If you want a named model in Swagger UI, register it after document generation:

import { addProblemDetailsSchema } from 'nest-problem-details-filter/swagger';

const document = SwaggerModule.createDocument(app, builder);
addProblemDetailsSchema(document);

See docs/usage.md for the full decorator API and BASE_PROBLEMS_URI alignment notes.

Preview: tests/fixtures/swagger-document.json is a committed OpenAPI 3.0 JSON generated by the decorator's integration test — copy it into editor.swagger.io to see how the schema renders.

Notes

  • All members are technically optional in RFC 9457. This schema marks type, title, and status as required because the library always emits them.
  • type uses format: uri-reference (not uri) because RFC 9457 explicitly allows relative references; the library emits values like not-found when no base URI is configured, plus about:blank and absolute URIs.
  • Validation errors: the schema accepts the errors extension member, but the library does not emit it by default (invalid-params appeared only in an RFC 7807 example and was not standardised in RFC 9457).
  • The Content-Type response header is application/problem+json. RFC 9457 §6.2 also registers application/problem+xml; this library emits only JSON.
  • title MAY be localized via the HTTP Content-Language response header (RFC 9457 §3.1). This library does not localize.
  • maxLength / maxItems constraints in this schema are pragmatic hardening limits and are not mandated by RFC 9457.

References