openapi: 3.1.0
info:
  title: Time Quality Messaging API
  description: AMQP message contracts between Core and Time Quality Monitor
  contact:
    name: ILM
    url: https://www.otilm.com
    email: ilm@omnitrust.com
  license:
    name: "Apache License, Version 2.0"
    url: https://github.com/OmniTrustILM/interface-documentation/blob/main/LICENSE.md
  version: 2.20.0
  x-logo:
    url: images/ilm-logo.svg
externalDocs:
  description: ILM Documentation
  url: https://docs.otilm.com
servers:
- url: https://demo.otilm.com/api
  description: ILM Demo server
tags:
- name: Time Quality Messaging
  description: RabbitMQ message contracts between Core and Time Quality Monitor. These
    are not HTTP endpoints — the paths exist only to anchor each message schema in
    the generated OpenAPI document.
paths:
  /v1/internal/messaging/timeQuality/result:
    post:
      tags:
      - Time Quality Messaging
      summary: "Time Quality Result [RabbitMQ: Monitor → Core]"
      description: "Message published by Time Quality Monitor and consumed by Core.\
        \ Carries the NTP check outcome — overall status, measured drift, per-server\
        \ details — for a specific time quality configuration profile."
      operationId: receiveTimeQualityResult
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TimeQualityResultMessage"
        required: true
      responses:
        "204":
          description: Message accepted
        "400":
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "404":
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "500":
          description: Internal Server Error
      security: []
      x-transport: rabbitmq
  /v1/internal/messaging/timeQuality/configSnapshot:
    post:
      tags:
      - Time Quality Messaging
      summary: "Time Quality Config Snapshot [RabbitMQ: Core → Monitor]"
      description: "Message published by Core and consumed by Time Quality Monitor.\
        \ Carries a full snapshot of all active NTP-based time quality configurations;\
        \ always a complete replacement, never a delta."
      operationId: receiveTimeQualityConfigSnapshot
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TimeQualityConfigSnapshot"
        required: true
      responses:
        "204":
          description: Message accepted
        "400":
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "404":
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "500":
          description: Internal Server Error
      security: []
      x-transport: rabbitmq
  /v1/internal/messaging/timeQuality/configRequest:
    post:
      tags:
      - Time Quality Messaging
      summary: "Time Quality Config Request [RabbitMQ: Monitor → Core]"
      description: Message sent by Time Quality Monitor to Core requesting a fresh
        snapshot of all active time quality configurations. Core responds by publishing
        a TimeQualityConfigSnapshot.
      operationId: receiveTimeQualityConfigRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TimeQualityConfigRequest"
        required: true
      responses:
        "204":
          description: Message accepted
        "400":
          description: Bad Request
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "404":
          description: Not Found
          content:
            '*/*':
              schema:
                $ref: "#/components/schemas/ErrorMessageDto"
        "500":
          description: Internal Server Error
      security: []
      x-transport: rabbitmq
components:
  schemas:
    LeapSecondWarning:
      type: string
      enum:
      - none
      - positive
      - negative
    NtpServerMeasurementResult:
      type: object
      description: Per-server NTP measurement result carried in a time quality result
        message
      properties:
        host:
          type: string
          description: NTP server hostname or IP address
          minLength: 1
        reachable:
          type: boolean
          description: Whether the server was reachable during this check
        offsetMs:
          type: number
          format: double
          description: Measured clock offset from this server in milliseconds; null
            when server was unreachable
        rttMs:
          type: number
          format: double
          description: Round-trip time to this server in milliseconds; null when server
            was unreachable
        stratum:
          type: integer
          format: int32
          description: NTP stratum of this server; null when server was unreachable
        precisionMs:
          type: number
          format: double
          description: Clock precision of this server in milliseconds; null when server
            was unreachable
      required:
      - host
      - reachable
    TimeQualityResultMessage:
      type: object
      description: "NTP time quality check result, published by Time Quality Monitor\
        \ and consumed by Core"
      properties:
        configurationId:
          type: string
          format: uuid
          description: UUID of the time quality configuration that produced this result
        name:
          type: string
          description: Display name of the time quality configuration
          minLength: 1
        timestamp:
          type: string
          format: date-time
          description: "Timestamp when the check was performed, in ISO 8601 UTC format"
        status:
          $ref: "#/components/schemas/TimeQualityStatus"
          description: "Overall time quality status. DEGRADED is always set when NTP\
            \ leap indicators conflict across servers (LeapUnsync), regardless of\
            \ the profile's leapSecondGuard setting"
        measuredDriftMs:
          type: number
          format: double
          description: Measured clock drift from NTP reference time in milliseconds;
            null when drift could not be determined
        reachableServers:
          type: integer
          format: int32
          description: Number of NTP servers that were reachable during this check
          minimum: 0
        reason:
          type: string
          description: "Human-readable reason for the resulting status, if applicable"
        leapSecondWarning:
          $ref: "#/components/schemas/LeapSecondWarning"
          description: Leap second warning derived from NTP leap indicators. Set to
            NONE when indicators conflict
        measurements:
          type: array
          description: Per-server measurement details for this check
          items:
            $ref: "#/components/schemas/NtpServerMeasurementResult"
          minItems: 1
      required:
      - configurationId
      - leapSecondWarning
      - measurements
      - name
      - reachableServers
      - status
      - timestamp
    TimeQualityStatus:
      type: string
      enum:
      - ok
      - degraded
    ErrorMessageDto:
      type: object
      properties:
        message:
          type: string
          description: Error message detail
          examples:
          - Error message
      required:
      - message
    TimeQualityConfig:
      type: object
      description: NTP-based time quality configuration carried within a configuration
        snapshot
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier of the time quality configuration
        name:
          type: string
          description: Display name of the time quality configuration
          minLength: 1
        ntpServers:
          type: array
          description: List of NTP server addresses used for time quality checks
          example:
          - pool.ntp.org
          - time.google.com
          items:
            type: string
            minLength: 1
          minItems: 1
        ntpCheckInterval:
          type: string
          description: "Interval between NTP checks, in ISO 8601 duration format"
          example: PT0.5S
        ntpSamplesPerServer:
          type: integer
          format: int32
          description: Number of NTP samples to take per server during each check
          example: 3
          exclusiveMinimum: 0
        ntpCheckTimeout:
          type: string
          description: "Timeout for the entire NTP check cycle, in ISO 8601 duration\
            \ format"
          example: PT0.1S
        ntpServersMinReachable:
          type: integer
          format: int32
          description: Minimum number of NTP servers that must be reachable for the
            check to be valid
          example: 1
          exclusiveMinimum: 0
        maxClockDrift:
          type: string
          description: "Maximum allowed clock drift from the NTP reference time, in\
            \ ISO 8601 duration format"
          example: PT1S
        leapSecondGuard:
          type: boolean
          description: "Whether to guard against leap second anomalies. When true,\
            \ signing operations are blocked for approximately two seconds around\
            \ midnight on days when NTP servers announce an upcoming leap second.\
            \ Set to false to allow signing through that window at the cost of potential\
            \ one-second timestamp inaccuracy during the leap event."
          example: true
      required:
      - id
      - maxClockDrift
      - name
      - ntpCheckInterval
      - ntpCheckTimeout
      - ntpSamplesPerServer
      - ntpServers
      - ntpServersMinReachable
    TimeQualityConfigSnapshot:
      type: object
      description: "Full snapshot of all NTP-based time quality configurations, sent\
        \ by Core to Time Quality Monitor"
      properties:
        correlationId:
          type: string
          format: uuid
          description: Correlation identifier carried from the matching TimeQualityConfigRequest.
            Null when Core publishes the snapshot proactively.
          example: 550e8400-e29b-41d4-a716-446655440000
        generatedAt:
          type: string
          format: date-time
          description: "Timestamp when the snapshot was generated, in ISO 8601 UTC\
            \ format"
        configurations:
          type: array
          description: "Complete list of active NTP-based time quality configurations;\
            \ always a full snapshot, never a delta"
          items:
            $ref: "#/components/schemas/TimeQualityConfig"
      required:
      - configurations
      - generatedAt
    TimeQualityConfigRequest:
      type: object
      description: Sent by Time Quality Monitor to Core to request the current time
        quality configuration snapshot
      properties:
        correlationId:
          type: string
          format: uuid
          description: Unique correlation identifier carried back in the matching
            TimeQualityConfigSnapshot so the requester can pair the response with
            this request
          example: 550e8400-e29b-41d4-a716-446655440000
        requestedAt:
          type: string
          format: date-time
          description: "Timestamp when the config request was sent, in ISO 8601 UTC\
            \ format"
      required:
      - correlationId
      - requestedAt