TS29576_Nmfaf_3caDataManagement.yaml

openapi: 3.0.0

info:
  version: 1.1.0-alpha.2
  title: Nmfaf_3caDataManagement
  description: |
    MFAF 3GPP Consumer Adaptor (3CA) Data Management Service.  
    © 2023, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: 3GPP TS 29.576 V18.2.0; 5G System; Messaging Framework Adaptor Services; Stage 3.
  url: 'https://www.3gpp.org/ftp/Specs/archive/29_series/29.576/'

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

security:
  - oAuth2ClientCredentials:
    - nmfaf-3cadatamanagement
  - {}

paths:
  /mfaf-data-analytics:
    post:
    # This is a pseudo operation, clients shall NOT invoke this method!
      requestBody:
        required: true
        content:
          application/json:
            # Unspecified schema for the JSON body, since this is used by neither the NF service consumer nor the MFAF.
            schema: {}
      responses:
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'
      callbacks:
        Notification:
          '{notificationURI}':
          # The URI in {notificationURI} is obtained out of band by the MFAF, i.e. it is provided via the Nmfaf-3daDataManagement API during the configuration for mapping data or analytics.
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/NmfafDataRetrievalNotification'
              responses:
                '204':
                  description: The receipt of the Notification is acknowledged.
                '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'
                default:
                  $ref: 'TS29571_CommonData.yaml#/components/responses/default'
              callbacks:
                Fetch:
                  '{request.body#/fetchInstruction/fetchUri}':
                    post:
                      requestBody:
                        required: true
                        content:
                          application/json:
                            schema: 
                              type: array
                              items:
                                type: string
                              minItems: 1
                              description: Indicate the fetch correlation identifier.
                      responses:
                        '200':
                          description: Expected response to a valid request.
                          content:
                            application/json:
                              schema:
                                $ref: '#/components/schemas/NmfafDataAnaNotification'
                        '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'
                        default:
                          $ref: 'TS29571_CommonData.yaml#/components/responses/default'


components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{nrfApiRoot}/oauth2/token'
          scopes:
            nmfaf-3cadatamanagement: Access to the nmfaf-3cadatamanagement API

  schemas:
    NmfafDataRetrievalNotification:
      description: >
        Represents the data or analytics or notification of availability of data or analytics
        to notification endpoints.
      type: object
      required:
        - correId
      oneOf:
        - required: [dataAnaNotif]
        - required: [fetchInstruction]
      properties:
        correId:
          type: string
          description: >
            Represents the Analytics Consumer Notification Correlation ID
            or Data Consumer Notification Correlation ID. It shall be set to the same
            value as the "correId" attribute of MessageConfiguration data type.
        dataAnaNotif:
          $ref: '#/components/schemas/NmfafDataAnaNotification'
        fetchInstruction:
          $ref: '#/components/schemas/FetchInstruction'

    FetchInstruction:
      description: >
        The fetch instructions indicate whether the data or analytics are to be fetched by the
        consumer.
      type: object
      required:
        - fetchUri
        - fetchCorrIds
      properties:
        fetchUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        fetchCorrIds:
          type: array
          items:
            type: string
          minItems: 1
          description: The fetch correlation identifier(s) of the MFAF Data or Analytics.
        expiry:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'

    NmfafDataAnaNotification:
      description: MFAF data or analytics.
      type: object
      oneOf:
        - required: [anaNotifications]
        - required: [dataNotif]
      properties:
        anaNotifications:
          type: array
          items:
            $ref: 'TS29520_Nnwdaf_EventsSubscription.yaml#/components/schemas/NnwdafEventsSubscriptionNotification'
          minItems: 1
          description: List of analytics subscription notifications.
        dataNotif:
          $ref: 'TS29575_Nadrf_DataManagement.yaml#/components/schemas/DataNotification'