openapi: 3.0.0

info:
  title: SS_ADAE_AIMLMemberCapabilityAnalytics
  description: |
    API for ADAE AIML member capability analytics analytics service.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.
  version: "1.0.0"

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-aimlmca/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 6.5 of 3GPP TS 29.549

paths:
  /application-aimlmcas:
    post:
      summary: Request the creation of AIML Member Capability Analytics Subscription.
      operationId: CreateIndAimlmcaSubsc
      tags:
        - AIML Member Capability Analytics Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppAimlMemCapSub'
      callbacks:
        paNotification:
          '{$request.body#/notifUri}':
            post:
              requestBody:  # contents of the callback message
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/AppAimlMemCapNotif'
              responses:
                '204':
                  description: No Content (successful notification)
                '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'
      responses:
        '201':
          description: The AIML Member Capability Analytics Subscription is successfully
            created and a representation of the created Individual AIML Member Capability Analytics
            Subscription resource shall be returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppAimlMemCapSub'
          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'

  /application-aimlmcas/{appAimlmcaId}:
    parameters:
      - name: appAimlmcaId
        in: path
        description: >
          Represents the identifier of an Individual AIML Member Capability Analytics Subscription
          resource.
        required: true
        schema:
          type: string

    get:
      summary: Retrieves an existing Individual AIML Member Capability Analytics Subscription.
      operationId: ReadIndAimlmcaSubsc
      tags:
        - Individual AIML Member Capability Analytics Subscription (Document)
      responses:
        '200':
          description: >
            The requested Individual AIML Member Capability Analytics subscription matching the appAimlmcaId shall be returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppAimlMemCapSub'
        '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 AIML Member Capability Analytics Subscription resource.
      operationId: UpdateIndAimlmcaSubsc
      tags:
        - Individual AIML Member Capability Analytics Subscription (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppAimlMemCapSub'
      responses:
        '200':
          description: >
            OK. The Individual AIML Member Capability 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/AppAimlMemCapSub'
        '204':
          description: >
            No Content. The Individual AIML Member Capability 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 AIML Member Capability Analytics Subscription resource.
      operationId: ModifyIndAimlmcaSubsc
      tags:
        - Individual AIML Member Capability Analytics Subscription (Document)
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/AppAimlMemCapSubPatch'
      responses:
        '200':
          description: >
            OK. The Individual AIML Member Capability 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/AppAimlMemCapSub'
        '204':
          description: >
            No Content. The Individual AIML Member Capability 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 AIML Member Capability Analytics Subscription resource.
      operationId: DeleteIndAimlmcaSubsc
      tags:
        - Individual AIML Member Capability Analytics Subscription (Document)
      parameters:
        - name: appAimlmcaId
          in: path
          description: Identifier of an Individual AIML member Capability Analytics Subscription.
          required: true
          schema:
            type: string
      responses:
        '204':
          description: >
            The Individual AIML Member Capability Analytics Subscription matching the appAimlmcaId is 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:
    AppAimlMemCapSub:
      description: Represents an individual AIML member capability analytics event subscription resource.
      type: object
      properties:
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        analyticsId:
          $ref: '#/components/schemas/AppAimlMemCapAnalytics'
        analyticsType:
          $ref: 'TS29549_SS_ADAE_VALPerformanceAnalytics.yaml#/components/schemas/AnalyticsType'
        analyticsSub:
          $ref: '#/components/schemas/AppAimlMemCapAnalyticsSub'
        confLevel:
          type: integer
          minimum: 0
          maximum: 100
        timeValidity:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
        repReq:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - notifUri
        - analyticsId
        - analyticsType
        - analyticsSub

    AppAimlMemCapNotif:
      description: Represents notification of the AIML member capability analytics event.
      type: object
      properties:
        analyticsOutput:
          $ref: '#/components/schemas/AppAimlMemCapAnalyticsOutput'
        confLevel:
          type: integer
          minimum: 0
          maximum: 100
      required:
        - analyticsOutput


    AppAimlMemCapSubPatch:
      description: Represents the requested modification to a Individual AIML member capability analytics subscription resource.
      type: object
      properties:
        analyticsSub:
          $ref: '#/components/schemas/AppAimlMemCapAnalyticsSub'
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        confLevel:
          type: integer
          minimum: 0
          maximum: 100
        timeValidity:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
        repReq:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'

    AppAimlMemCapAnalyticsSub:
      description: Represents the information related to the analytics subscription.
      type: object
      properties:
        ueIds:
          type: array
          items:
            type: string
          minItems: 1
          description: >
            One or more VAL UE IDs whose analytics or data collection are subject to subcription.
        aimlMemberIds:
          type: array
          items:
            $ref: '#/components/schemas/AimlMemberId'
          minItems: 1
          description: >
            One or more AIML members whose analytics or data collection are subject to subcription.
        aimlMemCapAttribute:
          $ref: '#/components/schemas/AppAimlMemCapAttributes'
        area:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/LocationArea5G'
      required:
        - aimlMemCapAttribute
      oneOf:
        - required: [ueIds]
        - required: [aimlMemberIds]

    AppAimlMemCapAnalyticsOutput:
      description: Represents analytics output information in the notification.
      type: object
      properties:
        analyticsId:
          $ref: '#/components/schemas/AppAimlMemCapAnalytics'
        analyticsOutput:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsOutput'
          minItems: 1
          description: >
            Contains a list of identities of one or more VAL UEs or AIML members, the data
            collection related to, in the case of the notification is on the AIML member capability
            data collection.
      required:
        - analyticsId

    AnalyticsOutput:
      description: Represents analytics output information in the notification.
      type: object
      properties:
        ueId:
          type: string
        aimlMemberId:
          items:
            $ref: '#/components/schemas/AimlMemberId'
        timeValidity:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
        aimlMemAvails:
          type: array
          items:
            $ref: 'TS29122_CpProvisioning.yaml#/components/schemas/ScheduledCommunicationTime'
          minItems: 1
        aimlMemCap:
          $ref: '#/components/schemas/AimlMemCapability'
      required:
        - aimlMemAvails
      oneOf:
        - required: [ueId]
        - required: [aimlMemberId]


    AimlMemCapability:
      description: Represents AIML member capability information in the notification.
      type: object
      properties:
        maxAimlMemConn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        minAimlMemConn:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'



# SIMPLE DATA TYPES
#

    AimlMemberId:
      description: Represents unique identifier of a AIMLE Member.
      type: string


#
# ENUMERATIONS
#

    AppAimlMemCapAnalytics:
      anyOf:
      - type: string
        enum:
           - APP_MEMBER_CAPABILITY
      - 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 Connection Status Events.  
        Possible values are:
        - APP_MEMBER_CAPABILITY_ANALYTICS: Indicates that the identifier of the Application layer AIML member capability analytics event.

    AppAimlMemCapAttributes:
      anyOf:
      - type: string
        enum:
           - COMMUNICATION_CAPABILITY
      - 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 Connection Status Events.  
        Possible values are:
        - COMMUNICATION_CAPABILITY: Indicates that the requested attribute to be analyzed is 
          communication capability.
