TS29591_Nnef_EventExposure.yaml

openapi: 3.0.0

info:
  title: Nnef_EventExposure
  version: 1.3.0-alpha.5
  description: |
    NEF Event Exposure Service.  
    © 2024, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: >
    3GPP TS 29.591 V18.5.0; 5G System; Network Exposure Function Southbound Services; Stage 3.
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.591/

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

security:
  - {}
  - oAuth2ClientCredentials:
    - nnef-eventexposure

paths:
  /subscriptions:
    post:
      summary: subscribe to notifications
      operationId: CreateIndividualSubcription
      tags:
        - Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NefEventExposureSubsc'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NefEventExposureSubsc'
          headers:
            Location:
              description: >
                Contains the URI of the newly created resource, according to the structure
                {apiRoot}/nnef-eventexposure/<apiVersion>/subscriptions/{subscriptionId}
              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'
      callbacks:
        myNotification:
          '{$request.body#/notifUri}': 
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/NefEventExposureNotif'
              responses:
                '204':
                  description: No Content, Notification was succesfull
                '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}:
    get:
      summary: retrieve subscription
      operationId: GetIndividualSubcription
      tags:
        - IndividualSubscription (Document)
      parameters:
        - name: subscriptionId
          in: path
          description: Event Subscription ID
          required: true
          schema:
            type: string
        - name: supp-feat
          in: query
          description: Features supported by the NF service consumer
          required: false
          schema:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      responses:
        '200':
          description: OK. Resource representation is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NefEventExposureSubsc'
        '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'
        '406':
          $ref: 'TS29571_CommonData.yaml#/components/responses/406'
        '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'

    put:
      summary: update subscription
      operationId: ReplaceIndividualSubcription
      tags:
        - IndividualSubscription (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NefEventExposureSubsc'
      parameters:
        - name: subscriptionId
          in: path
          description: Event Subscription ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK. Resource was succesfully modified and representation is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NefEventExposureSubsc'
        '204':
          description: No Content. Resource was succesfully modified
        '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'

    delete:
      summary: unsubscribe from notifications
      operationId: DeleteIndividualSubcription
      tags:
        - IndividualSubscription (Document)
      parameters:
        - name: subscriptionId
          in: path
          description: Event Subscription ID
          required: true
          schema:
            type: string
      responses:
        '204':
          description: No Content. Resource was succesfully 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'


components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{nrfApiRoot}/oauth2/token'
          scopes:
            nnef-eventexposure: Access to the Nnef_EventExposure API

  schemas:
    NefEventExposureSubsc:
      description: Represents an Individual Network Exposure Event Subscription resource.
      type: object
      properties:
        dataAccProfId:
          type: string
        eventsSubs:
          type: array
          items:
            $ref: '#/components/schemas/NefEventSubs'
          minItems: 1
        eventsRepInfo:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        notifUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        notifId:
          type: string
        eventNotifs:
          type: array
          items:
            $ref: '#/components/schemas/NefEventNotification'
          minItems: 1
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - eventsSubs
        - notifId
        - notifUri

    NefEventExposureNotif:
      description: >
        Represents notifications on network exposure event(s) that occurred for an Individual Network
        Exposure Event Subscription resource.
      type: object
      properties:
        notifId:
          type: string
        eventNotifs:
          type: array
          items:
            $ref: '#/components/schemas/NefEventNotification'
          minItems: 1
      required:
        - notifId
        - eventNotifs

    NefEventNotification:
      description: Represents information related to an event to be reported.
      type: object
      properties:
        event:
          $ref: '#/components/schemas/NefEvent'
        timeStamp:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        svcExprcInfos:
          type: array
          items:
            $ref: '#/components/schemas/ServiceExperienceInfo'
          minItems: 1
        ueMobilityInfos:
          type: array
          items:
            $ref: '#/components/schemas/UeMobilityInfo'
          minItems: 1
        ueCommInfos:
          type: array
          items:
            $ref: '#/components/schemas/UeCommunicationInfo'
          minItems: 1
        excepInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/ExceptionInfo'
          minItems: 1
        congestionInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/UserDataCongestionCollection'
          minItems: 1
        perfDataInfos:
          type: array
          items:
            $ref: '#/components/schemas/PerformanceDataInfo'
          minItems: 1
        dispersionInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/DispersionCollection'
          minItems: 1
        collBhvrInfs:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/CollectiveBehaviourInfo'
          minItems: 1
        msQoeMetrInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/MsQoeMetricsCollection'
          minItems: 1
          deprecated: true
        msQoeMetrics:
          type: array
          items:
            $ref: 'TS26512_EventExposure.yaml#/components/schemas/QoEMetricsCollection'
          minItems: 1
          description: Represents the Media Streaming QoE metrics event notification.
        msConsumpInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/MsConsumptionCollection'
          minItems: 1
          deprecated: true
        msConsumpReports:
          type: array
          items:
            $ref: 'TS26512_EventExposure.yaml#/components/schemas/ConsumptionReportingUnitsCollection'
          minItems: 1
          description: Represents the Media Streaming Consumption event notification.
        msNetAssInvInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/MsNetAssInvocationCollection'
          minItems: 1
          deprecated: true
        msNetAssistInvocation:
          type: array
          items:
            $ref: 'TS26512_EventExposure.yaml#/components/schemas/NetworkAssistanceInvocationsCollection'
          minItems: 1
          description: >
            Represents the Media Streaming Network Assistance Invocations event notification.
        msDynPlyInvInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/MsDynPolicyInvocationCollection'
          minItems: 1
          deprecated: true
        msDynPlyInvocation:
          type: array
          items:
            $ref: 'TS26512_EventExposure.yaml#/components/schemas/DynamicPolicyInvocationsCollection'
          minItems: 1
          description: Represents the Media Streaming Dynamic Policy Invocations event notification.
        msAccActInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/MSAccessActivityCollection'
          minItems: 1
          deprecated: true
        msAccess:
          type: array
          items:
            $ref: 'TS26512_EventExposure.yaml#/components/schemas/MediaStreamingAccessesCollection'
          minItems: 1
          description: Represents the Media Streaming access event notification.
        gnssAssistDataInfo:
          $ref: '#/components/schemas/GNSSAssistDataInfo'
        datVolTransTimeInfos:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/DatVolTransTimeCollection'
          minItems: 1
      required:
        - event
        - timeStamp

    NefEventSubs:
      description: Represents an event to be subscribed and the related event filter information.
      type: object
      properties:
        event:
          $ref: '#/components/schemas/NefEvent'
        eventFilter:
          $ref: '#/components/schemas/NefEventFilter'
        eventRepInfo:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
      required:
        - event

    NefEventFilter:
      description: Represents event filter information for an event.
      type: object
      properties:
        tgtUe:
          $ref: '#/components/schemas/TargetUeIdentification'
        appIds:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
          minItems: 1
        locArea:
          $ref: 'TS29554_Npcf_BDTPolicyControl.yaml#/components/schemas/NetworkAreaInfo'
        collAttrs:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/CollectiveBehaviourFilter'
          minItems: 1
      required:
        - tgtUe

    TargetUeIdentification:
      description: Identifies the UE to which the request applies.
      type: object
      properties:
        supis:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
          minItems: 1
        interGroupIds:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/GroupId'
          minItems: 1
        anyUeId:
          type: boolean
        ueIpAddr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/IpAddr'

    ServiceExperienceInfo:
      description: Contains service experience information associated with an application.
      type: object
      properties:
        appId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        supis:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
          minItems: 1
        svcExpPerFlows:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/ServiceExperienceInfoPerFlow'
          minItems: 1
        contrWeights:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
          minItems: 1
      required:
        - svcExpPerFlows

    UeMobilityInfo:
      description: >
        Contains UE mobility information associated with an application. If the "appId" attribute is 
        not present, then indicates the collected UE mobility information is applicable to all the 
        applications for the UE.
      type: object
      properties:
        supi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
        appId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        ueTrajs:
          type: array
          items:
            $ref: '#/components/schemas/UeTrajectoryInfo'
          minItems: 1
        areas:
          type: array
          items:
            $ref: 'TS29554_Npcf_BDTPolicyControl.yaml#/components/schemas/NetworkAreaInfo'
          minItems: 1
      required:
        - supi
        - ueTrajs

    UeCommunicationInfo:
      description: Contains UE communication information associated with an application.
      type: object
      properties:
        supi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Supi'
        interGroupId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/GroupId'
        appId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        comms:
          type: array
          items:
            $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/CommunicationCollection'
          minItems: 1
      required:
        - comms

    UeTrajectoryInfo:
      description: Contains UE trajectory information.
      type: object
      properties:
        ts:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
        location:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/UserLocation'
      required:
        - ts
        - location

    PerformanceDataInfo:
      description: Contains Performance Data Analytics related information collection.
      type: object
      properties:
        appId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/ApplicationId'
        ueIpAddr:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/IpAddr'
        ipTrafficFilter:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/FlowInfo'
        userLoc:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/UserLocation'
        appLocs:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnai'
          minItems: 1
        asAddr:
          $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/AddrFqdn'
        perfData:
          $ref: 'TS29517_Naf_EventExposure.yaml#/components/schemas/PerformanceData'
        timeStamp:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DateTime'
      required:
        - perfData
        - timeStamp

    GNSSAssistDataInfo:
      description: Represents GNSS Assistance Data related information.
      type: object
      properties:
        gnssAssistData:
          $ref: '#/components/schemas/GNSSAssistData'
        servArea:
          $ref: '#/components/schemas/GNSSServArea'
        sourceInfo:
          $ref: 'TS29572_Nlmf_Location.yaml#/components/schemas/GeographicalCoordinates'
      required:
        - gnssAssistData
        - servArea

    GNSSServArea:
      description: Represents the serving area of the GNSS Assistance Data.
      type: object
      properties:
        geographicalArea:
          $ref: 'TS29572_Nlmf_Location.yaml#/components/schemas/GeographicArea'
        taiList:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Tai'
          minItems: 1
      oneOf:
        - required: [geographicalArea]
        - required: [taiList]

# Simple data types and Enumerations

    NefEvent:

      anyOf:
      - type: string
        enum:
          - SVC_EXPERIENCE
          - UE_MOBILITY
          - UE_COMM
          - EXCEPTIONS
          - USER_DATA_CONGESTION
          - PERF_DATA
          - DISPERSION
          - COLLECTIVE_BEHAVIOUR
          - MS_QOE_METRICS
          - MS_CONSUMPTION
          - MS_NET_ASSIST_INVOCATION
          - MS_DYN_POLICY_INVOCATION
          - MS_ACCESS_ACTIVITY
          - GNSS_ASSISTANCE_DATA
          - DATA_VOLUME_TRANSFER_TIME
      - type: string
        description: >
          This string provides forward-compatibility with future extensions to the enumeration but
          is not used to encode content defined in the present version of this API.
      description: |
        Represents a Network Exposure Event.  
        Possible values are:
        - SVC_EXPERIENCE: Indicates that the subscribed/notified event is service experience
          information for an application.
        - UE_MOBILITY: Indicates that the subscribed/notified event is UE mobility information.
        - UE_COMM: Indicates that the subscribed/notified event is UE communication information.
        - EXCEPTIONS: Indicates that the subscribed/notified event is exceptions information.
        - USER_DATA_CONGESTION: Indicates that the subscribed/notified event is user data congestion
          analytics related information.
        - PERF_DATA: Indicates that the subscribed/notified event is performance data information.
        - DISPERSION: Indicates that the subscribed/notified event is dispersion information.
        - COLLECTIVE_BEHAVIOUR: Indicates that the subscribed/notified event is collective behaviour
          information.
        - MS_QOE_METRICS: Indicates that the subscribed/notified event is Media Streaming QoE
          metrics.
        - MS_CONSUMPTION: Indicates that the subscribed/notified event is Media Streaming
          consumption reports.
        - MS_NET_ASSIST_INVOCATION: Indicates that the subscribed/notified event is Media Streaming
          network assistance invocation.
        - MS_DYN_POLICY_INVOCATION: Indicates that the subscribed/notified event is Media Streaming
          dynamic policy invocation.
        - MS_ACCESS_ACTIVITY: Indicates that the subscribed/notified event is Media Streaming access
          activity.
        - GNSS_ASSISTANCE_DATA: Indicates that the subscribed/notified event is GNSS Assistance Data
          Collection.

    GNSSAssistData:
      type: string
      description: >
        Represents GNSS Assistance Data encoded as specified in clause 6.5.2.1 of
        3GPP TS 37.355 [31].