TS29257_UAE_C2OperationModeManagement.yaml

openapi: 3.0.0
info:
  title: uae-c2opmode-mngt
  version: 1.0.0-alpha.1
  description: |
    UAE Server C2 Operation Mode Management Service.
    © 2021, 3GPP Organizational Partners (ARIB, ATIS, CCSA, ETSI, TSDSI, TTA, TTC).
    All rights reserved.

externalDocs:
  description: 3GPP TS 29.257 V0.2.0; Application layer support for Uncrewed Aerial System (UAS); UAS Application Enabler (UAE) Server Services; Stage 3.
  url: http://www.3gpp.org/ftp/Specs/archive/29_series/29.257/

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

security:
  - {}
  - oAuth2ClientCredentials:
    - uae-c2opmode-mngt

paths:
  /configure:
    post:
      summary: Request the provisioning of C2 Operation Mode configuration information for a UAS (i.e. pair of UAV and UAV-C).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConfigureData'
      responses:
        '200':
          description: The communicated C2 Operation Mode configuration information was successfully received. The response body contains the feedback of the UAE Server on whether this C2 Operation Mode configuration request is confirmed (i.e. can be undertaken by the UAE Server) or not.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/C2Result'
        '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'
      callbacks:
        SelectedC2CommunicationModeNotification:
          '{$request.body#/notificationUri}/inform-selec-c2mode':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/SelectedC2CommModeNotif'
              responses:
                '204':
                  description: No Content, Notification was succesfull. The C2 Communication Mode selected by the concerned UAS (i.e. pair of UAV and UAV-C) is successfully received and acknowledged by the UASS.
                '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'
                '503':
                  $ref: 'TS29571_CommonData.yaml#/components/responses/503'
                default:
                  $ref: 'TS29571_CommonData.yaml#/components/responses/default'
        C2CommunicationModeSwitchingNotification:
          '{$request.body#/notificationUri}/inform-c2mode-switch':
            post:
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/C2CommModeSwitchNotif'
              responses:
                '200':
                  description: OK. The targeted C2 Communication Mode switching for the concerned UAS (i.e. pair of UAV and UAV-C) is successfully received. The response body contains the feedback of the UASS on whether this C2 Communication Mode switching is confirmed (i.e. validated) or not.
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/C2Result'
                '204':
                  description: No Content. The targeted C2 Communication Mode switching for the concerned UAS (i.e. pair of UAV and UAV-C) is successfully received and acknowledged, and the UASS does not need to confirm (i.e. validate) it.
                '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'
                '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:
            <API name in lower letters with underscores>: Access to the <API Name> API

  schemas:
    ConfigureData:
      description: Represents the parameters to request to provision C2 Operation Mode configuration information for a UAS (i.e. pair of UAV and UAV-C).
      type: object
      properties:
        uassId:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        uasId:
          $ref: '#/components/schemas/UasId'
        allowedC2CommModes:
          type: array
          items:
            $ref: '#/components/schemas/C2CommMode'
          minItems: 1
        c2CommModeSwitchReq:
          type: array
          items:
            $ref: '#/components/schemas/C2CommModeSwitching'
          minItems: 1
        notificationUri:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        primaryC2CommMode:
          $ref: '#/components/schemas/C2CommMode'
        secondaryC2CommMode:
          $ref: '#/components/schemas/C2CommMode'
      required:
        - uassId
        - uasId
        - allowedC2CommModes
        - c2CommModeSwitchReq
        - notificationUri
        - primaryC2CommMode

    SelectedC2CommModeNotif:
      description: Represents information on the C2 Communication Mode slected by a UAS (i.e. pair of UAV and UAV-C).
      type: object
      properties:
        uasId:
          $ref: '#/components/schemas/UasId'
        selPrimaryC2CommMode:
          $ref: '#/components/schemas/C2CommMode'
        selSecondaryC2CommMode:
          $ref: '#/components/schemas/C2CommMode'
      required:
        - uasId
        - selPrimaryC2CommMode

    C2CommModeSwitchNotif:
      description: Represents information on the targeted C2 Communication Mode switching for a UAS (i.e. pair of UAV and UAV-C).
      type: object
      properties:
        uaeServerId:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/Uri'
        uasId:
          $ref: '#/components/schemas/UasId'
        c2CommModeSwitchType:
          $ref: '#/components/schemas/C2CommModeSwitching'
      required:
        - uaeServerId
        - uasId
        - c2CommModeSwitchType

    C2Result:
      description: Represents the result of an action related to C2 of a UAS.
      type: object
      properties:
        c2OpConfirmed:
          type: boolean
      required:
        - c2OpConfirmed

    UasId:
      description: Represents the identifier of a UAS (i.e. pair of UAV and UAV-C).
      type: object
      properties:
        groupId:
          $ref: 'TS29122_CommonData.yaml#/components/schemas/ExternalGroupId'
        individualUasId:
          type: array
          items:
            $ref: '#/components/schemas/UavId'

    UavId:
      description: Represents the identifier of a UAV (e.g. UAV, UAV-C).
      type: object
      properties:
        gpsi:
          $ref: 'TS29571_CommonData.yaml#/components/schemas/Gpsi'
        caaId:
          type: string

# ENUMS:

    C2CommMode:
      description: Represents C2 Communication Modes.
      anyOf:
        - type: string
          enum:
          - DIRECT_C2_COMMUNICATION
          - NETWORK_ASSISTED_C2_COMMUNICATION
          - UTM_NAVIGATED_C2_COMMUNICATION
        - type: string

    C2CommModeSwitching:
      description: Represents C2 Communication Mode Switching types.
      anyOf:
        - type: string
          enum:
          - DIRECT_TO_NETWORK_ASSISTED_C2
          - NETWORK_ASSISTED_TO_DIRECT_C2
          - DIRECT_TO_UTM_NAVIGATED_C2
          - NETWORK_ASSISTED_TO_UTM_NAVIGATED_C2
        - type: string