openapi: 3.0.0

info:
  title: 3gpp-uav-flight-assistance
  version: 1.0.0-alpha.2
  description: |
    API for UAV Flight Assistance.  
    © 2025, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).  
    All rights reserved.

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

servers:
  - url: '{apiRoot}/3gpp-uav-flight-assistance/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}/configurations:
    parameters:
      - name: afId
        in: path
        description: Represents the identifier of the AF.
        required: true
        schema:
          type: string

    get:
      summary: Request to retrieve all the active UAV Flight Assistance Configurations at the NEF.
      operationId: GetUavFlightAssistConfig
      tags:
        - UAV Flight Assistance Configurations (Collection)
      responses:
        '200':
          description: >
            OK. All the Individual UAV Flight Assistance Configuration resources managed by the NEF
            are returned.
            If there are no existing Individual UAV Flight Assistance Configuration resources
            managed at the NEF, an empty array is returned.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UavFlightAssistance'
                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: Request the creation of a new UAV Flight Assistance Configuration.
      operationId: CreateUavFlightAssistConfig
      tags:
        - UAV Flight Assistance Configurations (Collection)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UavFlightAssistance'
      responses:
        '201':
          description: >
            Created. The UAV Flight Assistance Configuration is successfully created and a
            representation of the created Individual UAV Flight Assistance Configuration resource
            shall be returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UavFlightAssistance'
          headers:
            Location:
              description: >
                Contains the URI of the created Individual UAV Flight Assistance Configuration
                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:
        UavFlightAssistNotif:
          '{$request.body#/notifUri}':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/UAVFlightAssistNotif'
              responses:
                '200':
                  description: >
                    OK. The notification is successfully received and acknowledged, and notification
                    related information is returned in the response body.
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/UAVFlightAssistNotifResp'
                '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}/configurations/{configurationId}:
    parameters:
      - name: afId
        description: Represents the identifier of the AF.
        in: path
        required: true
        schema:
          type: string
      - name: configurationId
        description: >
          Represents the identifier of the IndividualUAV Flight Assistance Configuration resource.
        in: path
        required: true
        schema:
          type: string

    get:
      summary: Request to retrieve an existing Individual UAV Flight Assistance Configuration resource.
      operationId: GetIndUavFlightAssistConfig
      tags:
        - Individual UAV Flight Assistance Configuration (Document)
      responses:
        '200':
          description: >
            OK. The requested Individual UAV Flight Assistance Configuration resource is returned in
            the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UavFlightAssistance'
        '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 to update an existing Individual UAV Flight Assistance Configuration.
      operationId: UpdateUavFlightAssistConfig
      tags:
        - Individual UAV Flight Assistance Configuration (Document)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UavFlightAssistance'
      responses:
        '200':
          description: >
            OK. The Individual UAV Flight Assistance Configuration resource is successfully
            updated and a representation of the updated resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UavFlightAssistance'
        '204':
          description: >
            No Content. The Individual UAV Flight Assistance Configuration resource is successfully
            updated and no content is returned in the response body.
        '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'
        '501':
          $ref: 'TS29571_CommonData.yaml#/components/responses/501'
        '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: Request the modification of an existing Individual UAV Flight Assistance Configuration resource.
      tags:
        - Individual Group Parameters Provisioning (Document)
      operationId: ModifyUavFlightAssistConfig
      requestBody:
        description: >
          Contains the parameters to request the modification of the Individual UAV Flight
          Assistance Configuration resource.
        required: true
        content:
          application/merge-patch+json:
            schema:
              $ref: '#/components/schemas/UavFlightAssistancePatch'
      responses:
        '200':
          description: >
            OK. The Individual UAV Flight Assistance Configuration resource is successfully modified
            and a representation of the updated resource is returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UavFlightAssistance'
        '204':
          description: >
            No Content. The Individual UAV Flight Assistance Configuration 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 UAV Flight Assistance Configuration.
      operationId: DeleteUavFlightAssistConfig
      tags:
        - Individual UAV Flight Assistance Configuration (Document)
      responses:
        '204':
          description: >
            No Content. The Individual UAV Flight Assistance Configuration resource is successfully
            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'
        '501':
          $ref: 'TS29571_CommonData.yaml#/components/responses/501'
        '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: '{tokenUrl}'
          scopes: {}

  schemas:

#
# STRUCTURED DATA TYPES
#

    UavFlightAssistance:
      description: Represents the UAV Flight Assistance Configuration.
      type: object
      properties:
        uavId:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Gpsi'
        reqPurpose:
          $ref: '#/components/schemas/RequestPurpose'
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        flightPath:
          $ref: '#/components/schemas/FlightPath'
        altReports:
          type: array
          items:
            $ref: '#/components/schemas/AltitudeReport'
          minItems: 1
          description: Indicates the UAV altitude report.
        suppFeat:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/SupportedFeatures'
      required:
        - reqPurpose
        - uavId
        - notifUri

    FlightPath:
      description: Represents a flight path.
      type: object
      properties:
        pathSegInfo:
          type: array
          items:
            $ref: '#/components/schemas/FlightPathSegInfo'
          minItems: 1
      required:
        - pathSegInfo

    FlightPathSegInfo:
      description: Represents a flight path segment.
      type: object
      properties:
        flightSeg:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/LocationArea5G'
        uavSpeed:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Float'
        altitude:
          $ref: 'TS29572_Nlmf_Location.yaml#/components/schemas/Altitude'
        timeSchedule:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/TimeWindow'
        timeDuration:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/DurationSec'
      required:
        - flightSeg
      not:
        required: [timeSchedule, timeDuration]

    UAVFlightAssistNotif:
      description: Notify the UAV status.
      type: object
      properties:
        subscriptionId:
          type: string
        uavStatus:
            $ref: '#/components/schemas/UavStatus'
        borderPoint:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/LocationArea5G'
        altitude:
          $ref: 'TS29572_Nlmf_Location.yaml#/components/schemas/Altitude'
        altReportReqs:
          $ref: '#/components/schemas/AltReportReqs'
      required:
        - subscriptionId
        - uavStatus

    UAVFlightAssistNotifResp:
      description: Represents the response to the notification.
      type: object
      properties:
        ussChgInd:
          type: boolean
          description: >
            This attribute is used to indicate whether the USS changeover is completed successfully.
            true indicates that USS changeover is completed
            successfully; false (default): USS changeover failed.
      required:
        - ussChgInd

    UavFlightAssistancePatch:
      description: Represents the requested modifications to a UAV Flight Assistance Configuration.
      type: object
      properties:
        notifUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        flightPath:
          $ref: '#/components/schemas/FlightPath'

    AltReportReqs:
      description: Represents the UAV altitude reporting requirements.
      type: object
      properties:
        altThreshold:
          $ref: '#/components/schemas/AltRange'
        altReportPeriod:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/DurationSec'
        altReportEvent:
          $ref: '#/components/schemas/AltReportEvent'

    AltitudeReport:
      description: Represents the UAV altitude report.
      type: object
      properties:
        altitude:
          $ref: 'TS29572_Nlmf_Location.yaml#/components/schemas/Altitude'
        timeStamp:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/DateTime'

    AltRange:
      description: Represents the UAV altitude range for reporting.
      type: object
      properties:
        lowerBound:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'
        upperBound:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Uinteger'

#
# ENUMERATIONS
#
    UavStatus:
      anyOf:
        - type: string
          enum:
          - LEAVING
          - ENTERING
          - DEVIATING
        - 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 the status of the UAV.  
        Possible values are:
        - LEAVING: Indicates that the status is leaving an area which is part of the planned
          flight path.
        - ENTERING: Indicates that the status is entering an area which is part of the planned
          flight path.
        - DEVIATING: Indicates that the status is deviating from the planned flight path.

    RequestPurpose:
      anyOf:
      - type: string
        enum:
          - USS_CHANGEOVER
          - PRE_FLIGHT_PLANNING
          - IN_FLIGHT_MONITORING
      - 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 UAV Flight Assitance request purpose.  
        Possible values are:
          - USS_CHANGEOVER: Indicates that the purpose of the request is pre-flight planning.
          - PRE_FLIGHT_PLANNING: Indicates that the purpose of the request is USS changeover.
          - IN_FLIGHT_MONITORING:Indicates that the purpose of the request is in flight monitoring.

    AltReportEvent:
      anyOf:
        - type: string
          enum:
          - TA_CHANGE
          - RAN_NODE_CHANGE
        - 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 the Altitude reporting events.  
        Possible values are:
        - TA_CHANGE: Indicates the change of UAV’s serving TA.
        - RAN_NODE_CHANGE: Indicates the change of UAV’s serving RAN node.
