openapi: 3.0.0

info:
  version: '1.3.0-alpha.2'
  title: 'LMF Broadcast'
  description: |
    LMF Broadcast Service.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: 3GPP TS 29.572 V19.3.0; 5G System; Location Management Services; Stage 3
  url: 'https://www.3gpp.org/ftp/Specs/archive/29_series/29.572/'

servers:
  - url: '{apiRoot}/nlmf-broadcast/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 4.4 of 3GPP TS 29.501

paths:
  /cipher-key-data:
    post:
      summary: Request ciphering key data
      operationId: CipheringKeyData
      tags:
        - Request Ciphering Key Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CipherRequestData'
        required: true
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CipherResponseData'
        '307':
          $ref: 'TS29571_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29571_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29571_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29571_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29571_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29571_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29571_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29571_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29571_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        '504':
          $ref: 'TS29571_CommonData.yaml#/components/responses/504'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'
      callbacks:
        CipheringKeyData:
          '{$request.body#/amfCallBackURI}':
            post:
              requestBody:
                description: Ciphering Key Data Notification
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/CipheringKeyInfo'
              responses:
                '200':
                  description: Expected response to a valid request
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/CipheringKeyResponse'
                '307':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/307'
                '308':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/308'
                '400':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/400'
                '401':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/401'
                '403':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/403'
                '404':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/404'
                '411':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/411'
                '413':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/413'
                '415':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/415'
                '429':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/429'
                '500':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/500'
                '502':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/502'
                '503':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/503'
                '504':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/504'
                default:
                  $ref: 'TS29571_CommonData.yaml#/components/responses/default'

components:
  schemas:
#
# STRUCTURED TYPES
#
    CipheringKeyInfo:
      description: Information within Ciphering Key Data Notification request.
      type: object
      required:
        - cipheringData
      properties:
        cipheringData:
          type: array
          items:
            $ref: '#/components/schemas/CipheringDataSet'
          minItems: 1
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

    CipheringKeyResponse:
      description: Information within Ciphering Key Data Notification Response.
      type: object
      properties:
        cipheringDataReport:
          type: array
          items:
            $ref: '#/components/schemas/CipheringSetReport'
          minItems: 1

    CipheringDataSet:
      description: Represents a Ciphering Data Set.
      type: object
      required:
        - cipheringSetID
        - cipheringKey
        - c0
        - validityStartTime
        - validityDuration
      properties:
        cipheringSetID:
          $ref: '#/components/schemas/CipheringSetID'
        cipheringKey:
          $ref: '#/components/schemas/CipheringKey'
        c0:
          $ref: '#/components/schemas/C0'
        ltePosSibTypes:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Bytes'
        nrPosSibTypes:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Bytes'
        validityStartTime:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        validityDuration:
          $ref: '#/components/schemas/ValidityDuration'
        taiList:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Bytes'

    CipheringSetReport:
      description: Represents a report of Ciphering Data Set storage.
      type: object
      required:
        - cipheringSetID
        - storageOutcome
      properties:
        cipheringSetID:
          $ref: '#/components/schemas/CipheringSetID'
        storageOutcome:
          $ref: '#/components/schemas/StorageOutcome'

    CipherRequestData:
      description: Information within Ciphering Key Data request.
      type: object
      required:
        - amfCallBackURI
      properties:
        amfCallBackURI:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'

    CipherResponseData:
      description: Information within Ciphering Key Data Response.
      type: object
      required:
        - dataAvailability
      properties:
        dataAvailability:
          $ref: '#/components/schemas/DataAvailability'
#
#
# SIMPLE TYPES
#
    CipheringSetID:
      description: Ciphering Data Set Identifier.
      type: integer
      minimum: 0
      maximum: 65535

    CipheringKey:
      description: Ciphering Key.
      format: byte
      type: string

    C0:
      description: First component of the initial ciphering counter.
      format: byte
      type: string

    ValidityDuration:
      description: Validity Duration of the Ciphering Data Set.
      type: integer
      minimum: 1
      maximum: 65535
#
# ENUMS
#
    StorageOutcome:
      description: Indicates the result of Ciphering Data Set storage.
      anyOf:
        - type: string
          enum:
            - STORAGE_SUCCESSFUL
            - STORAGE_FAILED

    DataAvailability:
      description: Indicates availability of ciphering key data at an LMF.
      anyOf:
        - type: string
          enum:
            - CIPHERING_KEY_DATA_AVAILABLE
            - CIPHERING_KEY_DATA_NOT_AVAILABLE
