openapi: 3.1.0
info:
  title: BATbern Shared API Components
  description: |
    Canonical, single-source-of-truth schemas shared by every BATbern OpenAPI spec
    (ADR-013 §6). Specs reference these via the ADR-006 stub pattern
    (`x-java-type` + `x-java-type-import`) so the generated Java side resolves to the
    shared-kernel classes, while readers/SDK consumers see one consistent definition
    instead of a divergent inline copy per spec.

    Java sources of truth:
    - `ErrorResponse`     → `ch.batbern.shared.dto.ErrorResponse`
    - `PaginationMetadata`→ `ch.batbern.shared.api.PaginationMetadata`
    - `PaginatedResponse` → `ch.batbern.shared.dto.PaginatedResponse`

    Do NOT redefine these inline in any other spec. Phase 3 of the api-consolidation
    plan rewires existing inline copies to reference this file.
  version: 1.0.0
  license:
    name: Proprietary

# This file carries no operations — it exists only to host shared component schemas.
paths: {}

components:
  schemas:
    ErrorResponse:
      type: object
      description: |
        Standard error envelope returned on every 4xx/5xx response across all services.
        Flat shape (NOT nested under `error`). Backed by
        `ch.batbern.shared.dto.ErrorResponse`. `@JsonInclude(NON_NULL)` — absent fields
        are omitted from the wire.
      x-java-type: ch.batbern.shared.dto.ErrorResponse
      x-java-type-import: ch.batbern.shared.dto.ErrorResponse
      properties:
        timestamp:
          type: string
          format: date-time
          description: When the error occurred (ISO-8601 / Instant).
        path:
          type: string
          description: Request path that generated the error.
        status:
          type: integer
          description: HTTP status code.
          examples: [400]
        error:
          type: string
          description: Short HTTP reason phrase (e.g. "Bad Request").
        errorCode:
          type: string
          description: |
            Stable machine-readable error code for typed client handling
            (e.g. `ADDITIONAL_EMAIL_DUPLICATE`, `ERR_VALIDATION`).
          examples: ["ERR_VALIDATION"]
        message:
          type: string
          description: Human-readable error message.
        correlationId:
          type: string
          description: Correlation ID for tracing this request across services.
        severity:
          type: string
          description: Operational severity classification.
          enum: [LOW, MEDIUM, HIGH, CRITICAL]
        details:
          type: object
          additionalProperties: true
          description: |
            Additional structured context (e.g. per-field validation errors keyed by
            field name). Free-form object.
        stackTrace:
          type: string
          description: Present only in dev/staging diagnostics — never in production.

    ValidationError:
      type: object
      description: |
        A single field-level validation failure. Typically returned in a list inside
        `ErrorResponse.details` for `400` validation responses.
      properties:
        field:
          type: string
          description: Name of the request field that failed validation.
        message:
          type: string
          description: Why the field is invalid.
      required:
        - field
        - message

    PaginationMetadata:
      type: object
      description: |
        Page-based pagination metadata returned with every paginated list response.
        Backed by `ch.batbern.shared.api.PaginationMetadata`. Page-based — NOT
        offset/cursor.
      x-java-type: ch.batbern.shared.api.PaginationMetadata
      x-java-type-import: ch.batbern.shared.api.PaginationMetadata
      properties:
        page:
          type: integer
          description: Zero-based (or one-based per spec) current page index.
          examples: [0]
        limit:
          type: integer
          description: Page size — items per page.
          examples: [20]
        totalItems:
          type: integer
          format: int64
          description: Total number of items across all pages.
          examples: [150]
        totalPages:
          type: integer
          description: Total number of pages.
          examples: [8]
        hasNext:
          type: boolean
          description: Whether a next page exists.
        hasPrev:
          type: boolean
          description: Whether a previous page exists.
      required:
        - page
        - limit
        - totalItems
        - totalPages
        - hasNext
        - hasPrev

    PaginatedResponse:
      type: object
      description: |
        Base envelope for a paginated list response: `{ data: [...], pagination }`.
        Concrete specs compose this by overriding `data` with their item type
        (e.g. `PaginatedUserResponse` sets `data: array of User`). Backed by
        `ch.batbern.shared.dto.PaginatedResponse<T>`.
      properties:
        data:
          type: array
          items:
            type: object
          description: The page of items (item type set by the concrete spec).
        pagination:
          $ref: '#/components/schemas/PaginationMetadata'
      required:
        - data
        - pagination