common-components.yml

# ============================================================================
# CANONICAL shared OpenAPI components for ALL Sphereon REST modules.
#
# This file is the single source of truth. It is copied into each consuming
# REST module's openapi directory at build time by the Gradle
# `syncOpenApiCommonComponents` task so that specs can keep clean
# same-directory `$ref: './common-components.yml#/...'` references.
#
# EDIT HERE ONLY. The copies that land next to a consumer's openapi.yml are
# build-generated and git-ignored. Do not edit a copy; it will be overwritten.
#
# The `PageMeta` schema below matches EXACTLY the `pagination` object emitted by
# `com.sphereon.core.api.http.response.ResponseBuilder.paginated()`.
# ============================================================================
openapi: 3.0.3
info:
  title: Sphereon Shared API Components
  version: 1.0.0
  description: Canonical reusable components shared across Sphereon IDK, EDK, and VDX REST APIs.
paths: {}
components:
  parameters:
    TenantId:
      name: X-Tenant-ID
      in: header
      required: false
      # Trusted-infrastructure override header, irrelevant to ordinary API consumers (tenant
      # context comes from the bearer JWT). x-internal hides it from the rendered reference so it
      # does not repeat on every endpoint; it is still accepted at runtime and emitted by codegen.
      x-internal: true
      description: |
        Optional tenant context header for trusted infrastructure or internal
        override flows. Public clients should normally rely on bearer-token
        context instead of sending this header directly; tenant resolution is
        driven by the OIDC bearer JWT, not by this header.
      schema:
        type: string
        format: uuid
    UserId:
      name: X-User-ID
      in: header
      required: false
      # See TenantId: trusted-infra override header, hidden from the reference via x-internal.
      x-internal: true
      description: |
        Optional authenticated user context header for trusted infrastructure
        or internal override flows. Public clients should normally rely on
        bearer-token context instead of sending this header directly.
      schema:
        type: string
        format: uuid
    CorrelationId:
      name: X-Correlation-ID
      in: header
      required: false
      description: |
        Client-supplied correlation identifier. If sent, the server echoes it back
        in the response. If absent, the server generates one. Always present in
        responses and in ApiError.correlationId. UUIDs are recommended but not
        required; any opaque string is accepted.
      schema:
        type: string

    # ---- Pagination query parameters -------------------------------------
    Limit:
      name: limit
      in: query
      description: Maximum number of items to return. Clamped to `[1, 100]`. Defaults to `20`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 20
    Offset:
      name: offset
      in: query
      description: Number of items to skip.
      schema:
        type: integer
        minimum: 0
        default: 0
    Page:
      name: page
      in: query
      description: Zero-based page index (OpenAPI-style pagination, alternative to `offset`).
      schema:
        type: integer
        minimum: 0
        default: 0
    Size:
      name: size
      in: query
      description: Page size (OpenAPI-style pagination, alternative to `limit`). Clamped to `[1, 100]`.
      schema:
        type: integer
        minimum: 1
        maximum: 100
    Sort:
      name: sort
      in: query
      description: Field name to sort by. Defaults to `createdAt`.
      schema:
        type: string
        default: createdAt
    SortDirection:
      name: sortDirection
      in: query
      description: Sort direction.
      schema:
        type: string
        enum: [ASC, DESC]
        default: DESC

  headers:
    CorrelationId:
      description: |
        Correlation identifier for this response. Echoes the inbound
        X-Correlation-ID header when present, otherwise a server-generated
        value. UUIDs are recommended but not required.
      schema:
        type: string

  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT token. Tenant context is resolved from this token.

  schemas:
    ApiError:
      type: object
      description: Stable, machine-readable error body content.
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable, machine-readable error category.
          example: VALIDATION_ERROR
        message:
          type: string
          description: Human-readable error message.
        correlationId:
          type: string
          description: Correlation identifier for the failed request. UUIDs are recommended but not required.
        details:
          type: object
          additionalProperties: true
          description: Additional error context or field-level details (key to message).

    ErrorResponse:
      type: object
      description: 'Envelope wrapping an [ApiError], emitted as the object with an `error` member.'
      required: [error]
      properties:
        error:
          $ref: '#/components/schemas/ApiError'

    PageMeta:
      type: object
      description: |
        Canonical pagination metadata. Matches exactly the `pagination` object emitted by
        `ResponseBuilder.paginated()`. The `limit`/`offset`/`total`/`hasMore` fields are the
        stable legacy fields; `page`/`size`/`totalPages` are the additive unified fields.
      required: [limit, offset, page, size, total, totalPages, hasMore]
      properties:
        limit:
          type: integer
          description: The page size (item limit) that was used.
          minimum: 0
        offset:
          type: integer
          description: The offset that was used.
          minimum: 0
        page:
          type: integer
          description: Zero-based page number derived from offset and limit.
          minimum: 0
        size:
          type: integer
          description: The page size (alias of `limit`, OpenAPI-style).
          minimum: 0
        total:
          type: integer
          format: int64
          description: Total count of items across all pages.
          minimum: 0
        totalPages:
          type: integer
          description: Total number of pages.
          minimum: 0
        hasMore:
          type: boolean
          description: True when more items exist beyond `offset + items.size`.

    PagingMeta:
      type: object
      deprecated: true
      description: |
        Deprecated legacy VDX pagination metadata alias. Prefer [PageMeta], which is the
        canonical shape emitted by `ResponseBuilder.paginated()`. Retained only for specs
        that have not yet migrated.
      properties:
        page:
          type: integer
          minimum: 0
        size:
          type: integer
          minimum: 1
        totalElements:
          type: integer
          minimum: 0
        totalPages:
          type: integer
          minimum: 0

  responses:
    NotFound:
      description: The requested entity was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    ValidationError:
      description: The request failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Unauthorized:
      description: Authentication required.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Forbidden:
      description: Insufficient permissions.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Conflict:
      description: Resource conflict (e.g., duplicate entry).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    Error:
      description: An unexpected error occurred.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'