TS29520_Nnwdaf_MLModelMonitor.yaml

openapi: 3.0.0

info:
  title: Nnwdaf_MLModelMonitor
  version: 1.0.0-alpha.2
  description: |
    Nnwdaf_MLModelMonitor API Service.  
    © 2024, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: 3GPP TS 29.520 V18.5.0; 5G System; Network Data Analytics Services.
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.520/

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

security:
  - {}
  - oAuth2ClientCredentials:
    - nnwdaf-mlmodelmonitor

paths:
  /registrations:
    post:
      summary: Create a new Individual NWDAF ML Model monitoring registration resource.
      operationId: CreateNWDAFMLModelMonitoringRegistration
      tags:
        - registrations (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MLModelMonitorReg'
      responses:
        '201':
          description: Create a new Individual NWDAF ML Model monitoring registration resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MLModelMonitorReg'
          headers:
            Location:
              description: >
                Contains the URI of the newly created resource, according to the structure
                {apiRoot}/nnwdaf-mlmodelmonitor/<apiVersion>/registrations/{registrationId}.
              required: true
              schema:
                type: string
        '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'

  /registrations/{registrationId}:
    delete:
      summary: Delete an existing Individual NWDAF ML model monitoring registration.
      operationId: DeleteNWDAFMLModelMonitoringRegistration
      tags:
        - Individual NWDAF ML model monitoring registration (Document)
      parameters:
        - name: registrationId
          in: path
          description: String identifying a registration to the Nnwdaf_MLModelMonitor Service.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: >
            No Content. The Individual NWDAF ML Model monitoring registration matching the
            registrationId was deleted.
        '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'
        '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'

  /subscriptions:
    post:
      summary: Create a new Individual NWDAF ML model monitoring Subscription.
      operationId: CreateNWDAFMLModelMonitoringSubscription
      tags:
        - NWDAF ML model monitoring Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MLModelMonitorSub'
      responses:
        '201':
          description: Create a new Individual NWDAF ML model monitoring Subscription resource.
          headers:
            Location:
              description: >
                Contains the URI of the newly created resource, according to the structure
                {apiRoot}/nnwdaf-mlmodelmonitor/<apiVersion>/subscriptions/{subscriptionId}
              required: true
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MLModelMonitorSub'
        '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:
        myNotification:
          '{$request.body#/notificationUri}': 
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      type: array
                      items:
                        $ref: '#/components/schemas/MLModelMonitorNotify'
                      minItems: 1
              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'

  /subscriptions/{subscriptionId}:
    put:
      summary: Update an existing Individual NWDAF ML model monitoring Subscription resource.
      operationId: UpdateNWDAFMLModelMonitoringSubscription
      tags:
        - Individual NWDAF ML model monitoring Subscription resource (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MLModelMonitorSub'
      parameters:
        - name: subscriptionId
          in: path
          description: String identifying a subscription to the Nnwdaf_MLModelMonitor Service.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: >
            The Individual NWDAF ML model monitoring Subscription resource was modified successfully
            and a representation of that resource is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MLModelMonitorSub'
        '204':
          description: >
            The Individual NWDAF ML model monitoring Subscription resource was modified
            successfully.
        '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'
        '501':
          $ref: 'TS29571_CommonData.yaml#/components/responses/501'
        '502':
          $ref: 'TS29571_CommonData.yaml#/components/responses/502'
        '503':
          $ref: 'TS29571_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29571_CommonData.yaml#/components/responses/default'
    delete:
      summary: Delete an existing Individual NWDAF ML model monitoring Subscription.
      operationId: DeleteNWDAFMLModelMonitoringSubscription
      tags:
        - Individual NWDAF ML model monitoring Subscription (Document)
      parameters:
        - name: subscriptionId
          in: path
          description: String identifying a subscription to the Nnwdaf_MLModelMonitor Service
          required: true
          schema:
            type: string
      responses:
        '204':
          description: >
            No Content. The Individual NWDAF ML model monitoring Subscription resource matching the
            subscriptionId was deleted.
        '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'
        '429':
          $ref: 'TS29571_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29571_CommonData.yaml#/components/responses/500'
        '501':
          $ref: 'TS29571_CommonData.yaml#/components/responses/501'
        '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:
            nnwdaf-mlmodelmonitor: Access to the Nnwdaf_MLModelMonitor API

  schemas:
    MLModelMonitorReg:
      description: Represents a ML Model monitoring registration.
      type: object
      properties:
        consumerId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/NfInstanceId'
        consumerSetId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/NfSetId'
        modelId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        modelAccuInd:
          type: boolean
          description: >
            Indicates the ML Model accuracy transfer indication. Set to "true" to indicate that the
            monitoring of the accuracy of the ML model is supported, otherwise set to "false".
            Default value is "false" if omitted.
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - modelId
      oneOf:
        - required: [consumerId]
        - required: [consumerSetId]

    MLModelMonitorSub:
      description: >
        Represents parameters to request the modification of a ML Model monitoring registration.
      type: object
      properties:
        modelIds:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
          minItems: 1
          description: Represents the ML Model IDs.
        notificationUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        notifCorrId:
          type: string
          description: Notification correlation identifier.
        modelMetric:
          $ref: 'TS29520_Nnwdaf_MLModelProvision.yaml#/components/schemas/MLModelMetric'
        accuThreshold:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        eventReportReq:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        immReports:
          $ref: '#/components/schemas/MLModelMonitorNotify'
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - modelIds
        - notificationUri
        - notifCorrId

    MLModelMonitorNotify:
      description: Represents notifications on events that occurred.
      type: object
      properties:
        notifCorrId:
          type: string
          description: Notification correlation identifier.
        modelAccuInfos:
          type: array
          items:
            $ref: '#/components/schemas/MLModelAccuracyInfo'
          minItems: 1
          description: The accuracy related information of the ML model.
        anaFeedbacks:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsFeedback'
          minItems: 1
          description: The analytics feedback information.
        accuMeetInd:
          type: boolean
          description: >
            Set to "true" to indicate that the analytics accuracy of the ML model meet the
            requirement of accuracy for the ML model. Otherwise, default value is "false" if
            omitted.
      required:
        - notifCorrId
      anyOf:
        - required: [modelAccuInfos]
        - required: [anaFeedbacks]

    MLModelAccuracyInfo:
      description: Represents the ML Model accuracy information.
      type: object
      properties:
        modelId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        deviation:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Float'
        inferenceNum:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        adrfId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/NfInstanceId'
        adrfSetId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/NfSetId'
        dataSetTag:
          $ref: 'TS29575_Nadrf_DataManagement.yaml#/components/schemas/DataSetTag'
        modelMetric:
          $ref: 'TS29520_Nnwdaf_MLModelProvision.yaml#/components/schemas/MLModelMetric'
        mlModelAcc:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        monitorInterval:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
      required:
        - modelId

    AnalyticsFeedback:
      description: Represents the analytics feedback.
      type: object
      properties:
        events:
          type: array
          items:
            $ref: 'TS29520_Nnwdaf_EventsSubscription.yaml#/components/schemas/NwdafEvent'
          minItems: 1
          description: Indicates the Analytics IDs that were used to take this action.
        modelIds:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
          minItems: 1
          description: Indicates the ML Model identifier that were used to take this action.
        groundDataImpactInd:
          type: boolean
          description: >
            Indication whether the action will affect on ground truth data. Set to "true" to
            indicate that the action will affect on ground truth data. Otherwise set to "false",
            default value is "false" if omitted.
        timeStamp:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
      required:
        - events
        - modelIds