openapi: 3.0.0

info:
  title: 3gpp-vfl-training
  version: 1.0.1
  description: |
    API for VFL Training.  
    © 2026, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

externalDocs:
  description: >
    3GPP TS 29.522 V19.6.0; 5G System; Network Exposure Function Northbound APIs.
  url: 'https://www.3gpp.org/ftp/Specs/archive/29_series/29.522/'

servers:
  - url: '{apiRoot}/3gpp-vfl-training/v1'
    variables:
      apiRoot:
        default: https://example.com
        description: apiRoot as defined in clause 5.2.4 of 3GPP TS 29.122.

security:
  - {}
  - oAuth2ClientCredentials: []

paths:
  /{afId}/subscriptions:
    parameters:
      - name: afId
        in: path
        description: Represents the identifier of the AF
        required: true
        schema:
          type: string

    get:
      summary: Retrieve all the active VFL Training Subscriptions.
      operationId: GetVFLTrainingSubscriptions
      tags:
        - VFL Training Subscriptions (Collection)
      responses:
        '200':
          description: >
            OK. All the Individual VFL Training Subscription resource(s) managed
            by the NEF are returned.
            If there are no active Individual VFL Training Subscription resources
            at the NEF, an empty array is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VflTrainingSubs'
                minItems: 0
        '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'

    post:
      summary: Create a new Individual VFL Training Subscription.
      operationId: CreateVFLTrainingSubscription
      tags:
        - VFL Training Subscriptions (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VflTrainingSubs'
      responses:
        '201':
          description: >
            Created. A representation of the created Individual VFL Training Subscription
            resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VflTrainingSubs'
          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:
        VFLTrainingNotification:
          '{$request.body#/notifUri}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: 'TS29520_Nnwdaf_VFLTraining.yaml#/components/schemas/VflTrainingNotify'
              responses:
                '204':
                  description: >
                    No Content. The 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'


  /{afId}/subscriptions/{subId}:
    parameters:
      - name: afId
        in: path
        description: Represents the identifier of the AF.
        required: true
        schema:
          type: string
      - name: subId
        in: path
        description: Represents the identifier of the Individual VFL Training Subscription resource.
        required: true
        schema:
          type: string

    get:
      summary: Retrieve an existing Individual VFL Training Subscription resource.
      operationId: GetVFLTrainingSubscription
      tags:
        - Individual VFL Training Subscription (Document)
      responses:
        '200':
          description: >
            OK. The requested Individual VFL Training Subscription resource is
            successfully returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VflTrainingSubs'
        '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 VFL Training Subscription resource.
      operationId: UpdateVFLTrainingSubscription
      tags:
        - Individual VFL Training Subscription (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VflTrainingSubs'
      responses:
        '200':
          description: >
            OK. The Individual VFL Training Subscription resource is successfully updated
            and a representation of the updated resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VflTrainingSubs'
        '204':
          description: >
            No Content. The Individual VFL Training 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 modification of an existing Individual VFL Training Subscription resource.
      operationId: ModifyVFLTrainingSubscription
      tags:
        - Individual VFL Training Subscription (Document)
      requestBody:
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/VflTrainingSubsPatch'
      responses:
        '200':
          description: >
            OK. The Individual VFL Training Subscription resource is successfully modified
            and a representation of the updated resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VflTrainingSubs'
        '204':
          description: >
            No Content. The Individual VFL Training 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 deletion of an existing Individual VFL Training Subscription resource.
      operationId: DeleteVFLTrainingSubscription
      tags:
        - Individual VFL Training Subscription (Document)
      responses:
        '204':
          description: >
            No Content. The Individual VFL Training 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:

    VflTrainingSubs:
      description: Represents VFL Training subscription.
      type: object
      properties:
        notifUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        notifCorrId:
          type: string
          description: Notification correlation identifier.
        vflPreFlag:
          type: boolean
          description: >
            Indicates the subscription is for preparation of VFL, when it is included and set to
            "true". The default value is "false" if omitted.
        vflTrainSubs:
          type: array
          items:
            $ref: 'TS29520_Nnwdaf_VFLTraining.yaml#/components/schemas/VflTrainingSub'
          minItems: 1
        extNwdafId:
          type: string
          description: >
            Contains the external identifier of the NWDAF that is being requested to act
            as VFL client.
        reportingReqs:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'
        trainReports:
          type: array
          items:
            $ref: 'TS29520_Nnwdaf_VFLTraining.yaml#/components/schemas/VflTrainingNotify'
          minItems: 1
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - vflTrainSubs
        - extNwdafId

    VflTrainingSubsPatch:
      description: Represents contents for modifying a VFL Training subscription.
      type: object
      properties:
        vflTrainSubs:
          type: array
          items:
            $ref: 'TS29520_Nnwdaf_VFLTraining.yaml#/components/schemas/VflTrainingSub'
          minItems: 1
        notifUri:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uri'
        notifCorrId:
          type: string
          description: Notification correlation identifier.
        reportingReqs:
          $ref: 'TS29523_Npcf_EventExposure.yaml#/components/schemas/ReportingInformation'