openapi: 3.0.0

info:
  title: SS_ADAE_UeRatConnectivityAnalytics
  version: 1.0.0
  description: |
    API for ADAE UE RAT Connectivity Analytics service.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: >
    3GPP TS 29.549 V19.5.0 Service Enabler Architecture Layer for Verticals (SEAL);
    Application Programming Interface (API) specification; Stage 3.
  url: https://www.3gpp.org/ftp/Specs/archive/29_series/29.549/

security:
  - {}
  - oAuth2ClientCredentials: []

servers:
  - url: '{apiRoot}/ss-adae-uerat/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 6.5 of 3GPP TS 29.549 

paths:
  /subscriptions:
    post:
      summary: Create a new UE RAT Connectivity Analytics Subscription.
      operationId: CreateUeRatConnAnalyticsSubsc
      tags:
        - UE RAT Connectivity Analytics Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UeRatConnectivitySub'
      responses:
        '201':
          description: >
            Created. The UE RAT Connectivity Analytics Subscription is successfully created and a
            representation of the created Individual UE RAT Connectivity Analytics Subscription
            resource shall be returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UeRatConnectivitySub'
          headers:
            Location:
              description: Contains the URI of the newly created resource.
              required: true
              schema:
                type: string
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'
      callbacks:
        UeRatConnAnalyticsNotif:
          '{$request.body#/notifUri}': 
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/UeRatConnectivityNotif'
              responses:
                '204':
                  description: >
                    No Content. The UE RAT Connectivity Analytics Notification is successfully
                    received and acknowledged.
                '307':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/307'
                '308':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/308'
                '400':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/400'
                '401':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/401'
                '403':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/403'
                '404':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/404'
                '411':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/411'
                '413':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/413'
                '415':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/415'
                '429':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/429'
                '500':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/500'
                '503':
                  $ref: 'TS29122_CommonData.yaml#/components/responses/503'
                default:
                  $ref: 'TS29122_CommonData.yaml#/components/responses/default'

  /subscriptions/{subscriptionId}:
    parameters:
      - name: subscriptionId
        in: path
        description: >
          Represents the identifier of the UE RAT Connectivity Analytics Subscription.
        required: true
        schema:
          type: string

    get:
      summary: Retrieve an existing Individual UE RAT Connectivity Analytics Subscription resource.
      operationId: GetIndUeRatConnAnalyticsSubsc
      tags:
        - Individual UE RAT Connectivity Analytics Subscription (Document)
      responses:
        '200':
          description: >
            OK. The requested Individual UE RAT Connectivity Analytics Subscription
            resource is returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UeRatConnectivitySub'
        '307':  
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '406':
          $ref: 'TS29122_CommonData.yaml#/components/responses/406'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    put:
      summary: Request the update of an existing Individual UE RAT Connectivity Analytics Subscription resource.
      operationId: UpdateIndUeRatConnAnalyticsSubsc
      tags:
        - Individual UE RAT Connectivity Analytics Subscription (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UeRatConnectivitySub'
      responses:
        '200':
          description: >
            OK. The Individual UE RAT Connectivity Analytics Subscription resource is successfully
            updated and a representation of the updated resource shall be returned in the response
            body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UeRatConnectivitySub'
        '204':
          description: >
            No Content. The Individual UE RAT Connectivity Analytics Subscription resource is
            successfully updated and no content is returned in the response body.
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    patch:
      summary: Request the modification of an existing Individual UE RAT Connectivity Analytics Subscription resource.
      operationId: ModifyIndUeRatConnAnalyticsSubsc
      tags:
        - Individual UE RAT Connectivity Analytics Subscription (Document)
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UeRatConnectivitySubPatch'
      responses:
        '200':
          description: >
            OK. The Individual UE RAT Connectivity Analytics Subscription resource is successfully
            modified and a representation of the updated resource shall be returned in the response
            body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UeRatConnectivitySub'
        '204':
          description: >
            No Content. The Individual UE RAT Connectivity Analytics Subscription resource is
            successfully modified and no content is returned in the response body.
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '411':
          $ref: 'TS29122_CommonData.yaml#/components/responses/411'
        '413':
          $ref: 'TS29122_CommonData.yaml#/components/responses/413'
        '415':
          $ref: 'TS29122_CommonData.yaml#/components/responses/415'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

    delete:
      summary: Request the deletion of an existing Individual UE RAT Connectivity Analytics Subscription resource.
      operationId: RemoveUeRatConnectivityAnalytics
      tags:
        - Individual UE RAT Connectivity Analytics Subscription (Document)
      responses:
        '204':
          description: >
            The Individual UE RAT Connectivity Analytics Subscription resource
            is successfully deleted.
        '307':
          $ref: 'TS29122_CommonData.yaml#/components/responses/307'
        '308':
          $ref: 'TS29122_CommonData.yaml#/components/responses/308'
        '400':
          $ref: 'TS29122_CommonData.yaml#/components/responses/400'
        '401':
          $ref: 'TS29122_CommonData.yaml#/components/responses/401'
        '403':
          $ref: 'TS29122_CommonData.yaml#/components/responses/403'
        '404':
          $ref: 'TS29122_CommonData.yaml#/components/responses/404'
        '429':
          $ref: 'TS29122_CommonData.yaml#/components/responses/429'
        '500':
          $ref: 'TS29122_CommonData.yaml#/components/responses/500'
        '503':
          $ref: 'TS29122_CommonData.yaml#/components/responses/503'
        default:
          $ref: 'TS29122_CommonData.yaml#/components/responses/default'

components:
  securitySchemes:
    oAuth2ClientCredentials:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: '{tokenUrl}'
          scopes: {}

  schemas:

# Structured Data Types

    UeRatConnectivitySub:
      description: >
        Represents the UE RAT Connectivity Analytics subscription.
      type: object
      properties:
        analyticsSubs:
          type: array
          items:
            $ref: '#/components/schemas/UeRatAnalyticsSub'
          minItems: 1
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        reports:
          type: array
          items:
            $ref: '#/components/schemas/UeRatAnalyticsOutput'
          minItems: 1
        reportingReqs:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        timeInterval:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - analyticsSubs
        - notifUri

    UeRatConnectivitySubPatch:
      description: >
        Represents the requested modifications to a UE RAT Connectivity Analytics subscription.
      type: object
      properties:
        analyticsSubs:
          type: array
          items:
            $ref: '#/components/schemas/UeRatAnalyticsSub'
          minItems: 1
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        reportingReqs:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        timeInterval:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'

    UeRatConnectivityNotif:
      description: >
        Represents the UE RAT Connectivity Analytics Notification.
      type: object
      properties:
        subscriptionId:
          type: string
        analyticsOut:
          type: array
          items:
            $ref: '#/components/schemas/UeRatAnalyticsOutput'
          minItems: 1
      required:
        - subscriptionId
        - analyticsOut

    UeRatAnalyticsOutput:
      description: >
        Represents the UE RAT Connectivity Analytics output information.
      type: object
      properties:
        analyticsIds:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsIdUeRat'
          minItems: 1
        areaApp:
          $ref: '#/components/schemas/AreaPrediction'
        timeApp:
          $ref: '#/components/schemas/TimeWindowPrediction'
        valUeIds:
          type: array
          items:
            type: string
          minItems: 1
        valSvcId:
          type: string
      required:
        - analyticsIds
      anyOf:
        - required: [areaApp]
        - required: [timeApp]

    UeRatAnalyticsSub:
      description: >
        Represents the UE RAT Connectivity Analytics Subscription related information.
      type: object
      properties:
        analyticsIds:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsIdUeRat'
          minItems: 1
        analyticsType:
          $ref: 'TS29549_SS_ADAE_VALPerformanceAnalytics.yaml#/components/schemas/AnalyticsType'
        valUeIds:
          type: array
          items:
            type: string
          minItems: 1
        valGroupId:
          type: string
        ueMobs:
          type: object
          additionalProperties:
            $ref: 'TS29520_Nnwdaf_EventsSubscription.yaml#/components/schemas/UeMobility'
          minProperties: 1
          description: >
            Contains the mobility and route information of the target VAL UEs.
            The key of the map shall be set to the value of the identifier of the VAL UE 
            (among the ones provided within the valUeIds attribute or the members of the VAL group
            identified by the valGroupId attribute) to which the mobility and route information
            provided within the map value is related.
        valSvcId:
          type: string
          description: Identity of the VAL service
        confLevel:
          type: integer
          minimum: 0
          maximum: 100
        area:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/LocationArea5G'
      required:
        - analyticsIds
        - analyticsType
      oneOf:
        - required: [valUeIds]
        - required: [valGroupId]

    AreaPrediction:
      description: >
        Represents the RAT type changes for a given way point.
      type: object
      properties:
        satRatType:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/RatType'
        area:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/LocationArea5G'
        timePer:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
        confLevel:
          type: integer
          minimum: 0
          maximum: 100
      required:
        - satRatType
        - area

    TimeWindowPrediction:
      description: >
        Represents the time periods for predictions.
      type: object
      properties:
        satRatType:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/RatType'
        timePer:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
        confLevel:
          type: integer
          minimum: 0
          maximum: 100
      required:
        - satRatType
        - timePer


# Simple data types and Enumerations

    AnalyticsIdUeRat:
      anyOf:
      - type: string
        enum:
           - UE_RAT_CONNECTIVITY_ANALYTICS
      - type: string
        description: >
          This string provides forward-compatibility with future extensions to the enumeration
          and is not used to encode content defined in the present version of this API.
      description: |
        Represents the analytics ID for UE RAT connectivity.  
        - UE_RAT_CONNECTIVITY_ANALYTICS: Indicates that the analytics ID for UE RAT Connectivity is
          UE RAT Connectivity Analytics.
