openapi: 3.0.0

info:
  title: Nnef_ECSAddressConfigurationInformation
  version: 1.1.0-alpha.1
  description: |
    NEF ECS Address Service.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: >
    3GPP TS 29.591 V19.3.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-ecs-addr-cfg-info/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 4.4 of 3GPP TS 29.501

security:
  - {}
  - oAuth2ClientCredentials:
    - nnef-ecs-addr-cfg-info

paths:

  /subscriptions:
    post:
      summary: subscribe to notifications
      operationId: CreateIndividualSubcription
      tags:
        - Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EcsAddrCfgInfoSub'
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EcsAddrCfgInfoSub'
          headers:
            Location:
              description: >
                Contains the URI of the newly created resource, according to the structure
                {apiRoot}/nnef-ecs-addr-cfg-info/<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/EcsAddrCfgInfoNotification'
              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}:
    parameters:
      - name: subscriptionId
        in: path
        description: Subscription ID
        required: true
        schema:
          type: string

    get:
      summary: retrieve subscription
      operationId: GetIndividualSubcription
      tags:
        - IndividualSubscription (Document)
      responses:
        '200':
          description: OK. Resource representation is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EcsAddrCfgInfoSub'
        '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: fully update subscription
      operationId: ReplaceIndividualSubcription
      tags:
        - IndividualSubscription (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EcsAddrCfgInfoSub'
      responses:
        '200':
          description: OK. Resource was succesfully modified and representation is returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EcsAddrCfgInfoSub'
        '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'

    patch:
      summary: Partially update subscription
      operationId: ModifyIndividualSubcription
      tags:
        - IndividualSubscription (Document)
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/EcsAddrCfgInfoSubPatch'
      parameters:
        - name: subscriptionId
          in: path
          description: 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/EcsAddrCfgInfoSub'
        '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)
      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-ecs-addr-cfg-info: Access to the Nnef_ECSAddress API

  schemas:
    EcsAddrCfgInfoSub:
      description: Represents an Individual ECS Address Configuration Information subscription data.
      type: object
      properties:
        notifUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        notifCorrId:
          type: string
          description: Notification correlation identifier.
        dnns:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnn'
          minItems: 1
          description: Each element identifies a DNN.
        snssais:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Snssai'
          minItems: 1
          description: Each element identifies a slice.
        immRepInd:
          type: boolean
          description: >
            Indication of immediate reporting. If included, when it is set to true it indicates
            immediate reporting of the subscribed events, if available. Otherwise, reporting will
            occur when the event is met.
        immReports:
          type: array
          items:
            $ref: '#/components/schemas/EcsAddrCfgInfoNotification'
          minItems: 1
          description: >
            Immediate report with ECS Address Configuration Information that match this subscription.
        supportedFeatures:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - notifUri
        - notifCorrId

    EcsAddrCfgInfoNotification:
      description: Represents notifications for ECS Address Configuration Information data.
      type: object
      properties:
        notifCorrId:
          type: string
          description: Notification correlation identifier.
        ecsAddrCfgInfo:
          type: array
          items:
            $ref: 'TS29522_ECSAddress.yaml#/components/schemas/EcsAddrInfo'
          minItems: 1
          description: Contains the ECS Address Configuration Information.
      required:
        - notifCorrId
        - ecsAddrCfgInfo

    EcsAddrCfgInfoSubPatch:
      description: Represents an updated ECS Address Configuration Information subscription data.
      type: object
      properties:
        notifUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        notifCorrId:
          type: string
          description: Notification correlation identifier.
        dnns:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Dnn'
          minItems: 1
          description: Each updated element identifies a DNN.
        snssais:
          type: array
          items:
            $ref: 'TS29571_CommonData.yaml#/components/schemas/Snssai'
          minItems: 1
          description: Each updated element identifies a slice.
        immRepInd:
          type: boolean
          description: >
            Indication of immediate reporting. If included, when it is set to true it indicates
            immediate reporting of the subscribed events, if available. Otherwise, reporting will
            occur when the event is met.
