openapi: 3.2.0
info:
  title: CDR Common Data Holder Operations API
  version: 1.36.0
  description: Specifications for common endpoints applicable to all data holders (except secondary data holders).
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  contact:
    name: Data Standards Body
    email: contact@dsb.gov.au
    url: https://dsb.gov.au/
servers:
- description: MTLS
  url: https://mtls.dh.example.com/cds-au/v1
tags:
- name: Data Holder Operations
  x-shortName: Operations
  description: Data Holder Operations endpoints
paths:
  /discovery/status:
    get:
      servers:
      - description: TLS
        url: https://tls.dh.example.com/cds-au/v1
      tags:
      - Data Holder Operations
      summary: Get Status
      description: Obtain a health check status for the implementation.
      operationId: getStatus
      parameters:
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      responses:
        '200':
          $ref: '#/components/responses/GetStatus200'
        '400':
          $ref: '#/components/responses/GetStatus400'
        '406':
          $ref: '#/components/responses/GetStatus406'
      x-version: '1'
  /discovery/outages:
    get:
      servers:
      - description: TLS
        url: https://tls.dh.example.com/cds-au/v1
      tags:
      - Data Holder Operations
      summary: Get Outages
      description: Obtain a list of scheduled outages for the implementation.
      operationId: getOutages
      parameters:
      - $ref: '#/components/parameters/HeaderXV'
      - $ref: '#/components/parameters/HeaderXMinV'
      responses:
        '200':
          $ref: '#/components/responses/GetOutages200'
        '400':
          $ref: '#/components/responses/GetOutages400'
        '406':
          $ref: '#/components/responses/GetOutages406'
      x-version: '1'
components:
  schemas:
    DiscoveryOutage:
      required:
      - duration
      - explanation
      - outageTime
      type: object
      properties:
        outageTime:
          type: string
          description: Date and time that the outage is scheduled to begin.
          x-cds-type: DateTimeString
        duration:
          type: string
          description: Planned duration of the outage. Formatted according to [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) (excludes recurrence syntax).
          x-cds-type: ExternalRef
        isPartial:
          type: boolean
          description: Flag that indicates, if present and set to `true`, that the outage is only partial meaning that only a subset of normally available endpoints will be affected by the outage.
        explanation:
          type: string
          description: Provides an explanation of the current outage that can be displayed to an end customer.
    ResponseDiscoveryOutagesList:
      required:
      - data
      - links
      type: object
      properties:
        data:
          required:
          - outages
          type: object
          properties:
            outages:
              type: array
              description: List of scheduled outages. Property is mandatory but may contain an empty list if no outages are scheduled.
              items:
                $ref: '#/components/schemas/DiscoveryOutage'
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorV2:
      type: object
      required:
      - code
      - title
      - detail
      x-conditional:
      - meta
      properties:
        code:
          type: string
          description: The code of the error encountered. Where the error is specific to the respondent, an application-specific error code, expressed as a string value. If the error is application-specific, the URN code that the specific error extends must be provided in the _meta_ object. Otherwise, the value is the error code URN.
        title:
          type: string
          description: A short, human-readable summary of the problem that **MUST NOT** change from occurrence to occurrence of the problem represented by the error code.
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem.
        meta:
          type: object
          x-conditional:
          - urn
          description: Additional data for customised error codes.
          properties:
            urn:
              type: string
              description: The CDR error code URN which the application-specific error code extends. Mandatory if the error _code_ is an application-specific error rather than a standardised error code.
    Meta:
      type: object
    ResponseCommonDiscoveryStatus:
      required:
      - data
      - links
      type: object
      properties:
        data:
          required:
          - status
          - updateTime
          type: object
          properties:
            status:
              type: string
              description: 'Enumeration with values: <ul><li>`OK`: (implementation is fully functional).<li>`PARTIAL_FAILURE`: (one or more endpoints are unexpectedly unavailable).<li>`UNAVAILABLE`: (the full implementation is unexpectedly unavailable).<li>`SCHEDULED_OUTAGE`: (an advertised outage is in effect).</ul>'
              enum:
              - OK
              - PARTIAL_FAILURE
              - SCHEDULED_OUTAGE
              - UNAVAILABLE
            explanation:
              type: string
              description: Provides an explanation of the current outage that can be displayed to an end customer. Mandatory if the status property is any value other than `OK`.
            detectionTime:
              type: string
              description: The date and time that the current outage was detected. Should only be present if the status property is `PARTIAL_FAILURE` or `UNAVAILABLE`.
              x-cds-type: DateTimeString
            expectedResolutionTime:
              type: string
              description: The date and time that full service is expected to resume (if known). Should not be present if the status property has a value of `OK`.
              x-cds-type: DateTimeString
            updateTime:
              type: string
              description: The date and time that this status was last updated by the Data Holder.
              x-cds-type: DateTimeString
          x-conditional:
          - explanation
        links:
          $ref: '#/components/schemas/Links'
        meta:
          $ref: '#/components/schemas/Meta'
    Links:
      required:
      - self
      type: object
      properties:
        self:
          type: string
          description: Fully qualified link that generated the current response document.
          x-cds-type: URIString
    ResponseErrorListV2:
      type: object
      required:
      - errors
      properties:
        errors:
          description: List of errors.
          type: array
          items:
            $ref: '#/components/schemas/ErrorV2'
  headers:
    XV:
      description: The [payload version](#response-headers) that the endpoint has responded with.
      required: true
      schema:
        type: string
  responses:
    GetStatus200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseCommonDiscoveryStatus'
    GetStatus406:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetOutages406:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[406 - Unsupported Version](#error-406-header-unsupported-version)</li></ul>
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetStatus400:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetOutages400:
      description: The following error codes **MUST** be supported:<br/><ul class="error-code-list"><li>[400 - Invalid Field](#error-400-field-invalid)</li><li>[400 - Missing Required Field](#error-400-field-missing)</li><li>[400 - Invalid Version](#error-400-header-invalid-version)</li></ul>
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseErrorListV2'
    GetOutages200:
      description: Successful response
      headers:
        x-v:
          $ref: '#/components/headers/XV'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ResponseDiscoveryOutagesList'
  parameters:
    HeaderXV:
      name: x-v
      in: header
      description: Version of the API endpoint requested by the client. Must be set to a positive integer. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If the value of [_x-min-v_](#request-headers) is equal to or higher than the value of [_x-v_](#request-headers) then the [_x-min-v_](#request-headers) header should be treated as absent. If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`. See [HTTP Headers](#request-headers).
      required: true
      schema:
        type: string
    HeaderXMinV:
      name: x-min-v
      in: header
      description: Minimum version of the API endpoint requested by the client. Must be set to a positive integer if provided. The endpoint should respond with the highest supported version between [_x-min-v_](#request-headers) and [_x-v_](#request-headers). If all versions requested are not supported then the endpoint **MUST** respond with a `406 Not Acceptable`.
      schema:
        type: string