flight_planning.yaml

openapi: 3.0.2
info:
  title: Flight Planning Automated Testing Interface
  version: 0.5.0
  description: >-
    This interface is provided by a USS wishing to participate in automated tests involving attempts to plan flights.
    
    A client (usually uss_qualifier) instructs a virtual user interacting with the USS's flight planning user interface
    attempting to plan, update, and close flight plans.  The client provides the information a USS user may be expected
    to provide to the USS when using the USS, and the USS responds with only the information the USS provides to its
    normal users when they perform an equivalent flight planning action.  The USS should implement execution of these
    flight planning actions using as many of the code paths involved in serving a normal user as practical.
    
    A client may also (with a separate authorization scope) act as the test director to determine the status of the
    USS's system under test, and request that the test area be cleared of any dangling flight plans.  The USS may
    provide fulfillment of these actions using non-standard code paths or those not available to normal users.
    
    Note: Unless otherwise specified, fields specified in a message but not declared in the API or otherwise known to
    the server or client (as applicable) must be ignored.

components:
  securitySchemes:
    Authority:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            interuss.flight_planning.direct_automated_test: |-
              Client may determine the test-readiness of the USS and instruct the USS or USS admin to perform various
              actions to prepare for tests involving flight planning (acting as test director).
            interuss.flight_planning.plan: |-
              Client may issue instructions to a virtual user attempting to plan a flight, modify an existing flight
              plan, or close an existing flight plan, and ask the virtual user for their observations while performing
              these tasks.
      description: |-
        Authorization from, or on behalf of, an authorization authority, augmenting standard strategic conflict detection or other similar authorization for the purpose of automated testing.
        
        This authority will issue access tokens that are JSON Web Tokens as defined in RFC 7519, using the `RS256` algorithm for the signature, and publish to all providers the public key for verifying that signature.

        The following fields must be included in the JWT claim for access tokens issued by this authority:

        * `exp`, with a time no further than 1 hour in the future.

        * `sub`, with unique ID of the client requesting the access token.

        * `scope`, with a string composed of a space-separated list of strings indicating the scopes granted, per RFC 6749.

        * `aud`, with the fully qualified domain name of the URL the access token will be used to access.  For example, if a USS were querying the endpoint at https://uss.example.com:8888/flight_planning/v1/flight_plans/db41f454-b255-470e-98d6-4c5096a295a1, the access token included in the request should specify `"aud": "uss.example.com"`.

        Clients must provide these access tokens in an `Authorization` header in the form `Bearer <token>` in accordance with RFC 6750.

  schemas:
    FlightPlanID:
      description: >-
        String identifying a user flight plan.  Format matches a version-4 UUID according to RFC 4122.
      maxLength: 36
      minLength: 36
      type: string
      format: uuid
      pattern: >-
        ^[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-4[0-9a-fA-F]{3}\-[8-b][0-9a-fA-F]{3}\-[0-9a-fA-F]{12}$
      example: 03e5572a-f733-49af-bc14-8a18bd53ee39

    StatusResponse:
      type: object
      required:
        - status
      properties:
        status:
          description: >-
            The status of this automated testing interface.

            - `Starting`: the interface is starting and the automated test driver should wait before sending requests.

            - `Ready`: the interface is ready to receive test requests.
          type: string
          enum: [Starting, Ready]
          example: Ready
        api_name:
          description: |-
            Indication of the API implemented at this URL.  Must be "Flight Planning Automated Testing Interface".
          type: string
          example: Flight Planning Automated Testing Interface
        api_version:
          description: |-
            Indication of the API version implemented at this URL.  Must be "v0.5.0" when implementing this version of the API.
          type: string
          example: v0.5.0

    FlightPlan:
      description: >-
        Details of user's intent to create or modify a flight plan.
      required:
        - basic_information
      type: object
      properties:
        basic_information:
          $ref: '#/components/schemas/BasicFlightPlanInformation'
        astm_f3548_21:
          $ref: './astm_f3548v21.yaml#/components/schemas/ASTMF354821OpIntentInformation'
        uspace_flight_authorisation:
          $ref: './uspace.yaml#/components/schemas/FlightAuthorisationData'
        rpas_operating_rules_2_6:
          $ref: './au.yaml#/components/schemas/RPAS26FlightDetails'
        additional_information:
          description: >-
            Any information relevant to a particular jurisdiction or use case not described in the standard schema. The
            keys and values must be agreed upon between the test designers and test participants.
          type: object

    BasicFlightPlanInformation:
      description: >-
        Basic information about a flight plan that a user and/or UAS can be expected to provide in most flight planning
        scenarios.
      type: object
      required:
        - usage_state
        - uas_state
      properties:
        usage_state:
          description: >-
            User's current usage of the flight plan.
            
            `Planned`: The user intends to fly according to this flight plan, but is not currently using the defined
              area with an active UAS.
            
            `InUse`: The user is currently using the defined area with an active UAS.
            
            `Closed`: The user is no longer using, or planning to use, the flight plan.
          type: string
          enum:
            - Planned
            - InUse
            - Closed
        uas_state:
          description: >-
            State of the user's UAS associated with this flight plan.
            
              - `Nominal`: The user or UAS reports or implies that it is performing nominally, or has not indicated
                `OffNominal` or `Contingent`.
            
              - `OffNominal`: The user or UAS reports or implies that it is temporarily not conforming to its intent,
                but may expect to be able to recover to normal operation.
            
              - `Contingent`: The user or UAS reports or implies that it is not conforming to its intent and may be
                unable to recover to normal operation.
            
              - `NotSpecified`: The UAS status is not currently available or known (for instance, if the flight is
                planned in the future and the UAS that will be flying has not yet connected to the system).
          type: string
          enum:
            - Nominal
            - OffNominal
            - Contingent
            - NotSpecified
        area:
          description: >-
            The complete area in which the user intends to fly, or may fly, as known by the user.  The user intends to
            fly, or may fly, anywhere in this entire area.
            
            This means, for instance, that an ASTM F3548-21 operational intent supporting this flight must have volumes
            that are a superset of this area.  If the operational intent did not cover this entire area, then all of the
            intended flight would not be covered by the operational intent (for at least part of the flight, the
            operator intends to fly outside the operational intent).
          type: array
          items:
            $ref: './geotemporal.yaml#/components/schemas/Volume4D'
          default: []

    ExecutionStyle:
      type: string
      description: >-
        The style of execution of a specified flight planning action that the operator would like the USS to perform.
        
          - `Hypothetical`: The user does not want the USS to actually perform any action regarding the actual flight plan.  Instead, the user would like to know the likely outcome if the action were hypothetically attempted.  The response to this request will not refer to an actual flight plan, or an actual state change in an existing flight plan, but rather a hypothetical flight plan or a hypothetical change to an existing flight plan.
        
          - `IfAllowed`: The user would like to perform the requested action if it is allowed.  If the requested action is allowed, the USS should actually perform the action (e.g., actually create a new ASTM F3548-21 operational intent).  If the requested action is not allowed, the USS should indicate that the action is Rejected and not perform the action.  The response to this request will refer to an actual flight plan when appropriate, and never refer to a hypothetical flight plan or status.

          - `InReality`: The user is communicating an actual state of reality.  The USS should consider the user to be actually performing (or attempting to perform) this action, regardless of whether or not the action is allowed under relevant UTM rules.
      enum: [Hypothetical, IfAllowed, InReality]
      example: IfAllowed

    UpsertFlightPlanRequest:
      description: >-
        Client request to emulate a user performing a flight planning action.
      type: object
      required:
        - flight_plan
        - execution_style
        - request_id
      properties:
        flight_plan:
          description: Complete new or updated information about the flight describing the flight planning action to be taken.
          anyOf:
            - $ref: '#/components/schemas/FlightPlan'
        execution_style:
          description: Style of execution for the requested flight planning action.
          anyOf:
            - $ref: '#/components/schemas/ExecutionStyle'
        request_id:
          type: string
          description: >-
            ID uniquely identifying the upsertion request.  If additional requests are received with the same
            request_id, the response from the first request should be returned, or an error indicated.

    PlanningActivityResult:
      type: string
      description: >-
        The result of a flight planning activity.

          - `Completed`: The user's flight plan has been updated according to the situation specified by the user. 

          - `Rejected`: The updates the user requested to their flight plan are not allowed according to the rules under which the flight plan is being managed.  The reasons for rejection may include a disallowed conflict with another flight during preflight.
        
          - `Failed`: The USS was not able to successfully authorize or update the flight plan due to a problem with the USS or a downstream system.

          - `NotSupported`: The USS's implementation does not support the attempted interaction.  For instance, if the request specified a high-priority flight and the USS does not support management of high-priority flights.
      enum: [Completed, Rejected, Failed, NotSupported]
      example: Completed

    FlightPlanStatus:
      type: string
      description: >-
        The status of the user's flight plan.

          - `NotPlanned`: The USS has not created an authorized flight plan for the user.

          - `Planned`: The USS has created an authorized flight plan for the user, but the user may not yet start flying (even if within the time bounds of the flight plan).

          - `OkToFly`: The flight plan is in a state such that it is ok for the user to nominally fly within the bounds (including time) of the flight plan.

          - `OffNominal`: The flight plan now reflects the user's actions, but the flight plan is not in a nominal state (e.g., the USS has placed the ASTM F3548-21 operational intent into one of the Nonconforming or Contingent states).

          - `Closed`: The flight plan was closed successfully by the USS and is now out of the UTM system.
      enum: [NotPlanned, Planned, OkToFly, OffNominal, Closed]
      example: Planned

    AdvisoryInclusion:
      type: string
      description: >-
        Indication of whether any advisories or conditions were provided to the user along with the result of an
        associated flight planning attempt.

          - `Unknown`: It is unknown or irrelevant whether advisories or conditions were provided to the user

          - `AtLeastOneAdvisoryOrCondition`: At least one advisory or condition was provided to the user.

          - `NoAdvisoriesOrConditions`: No advisories or conditions were provided to the user.
      enum: [Unknown, AtLeastOneAdvisoryOrCondition, NoAdvisoriesOrConditions]
      default: Unknown
      example: NoAdvisoriesOrConditions

    UpsertFlightPlanResponse:
      type: object
      required:
        - planning_result
        - flight_plan_status
      properties:
        planning_result:
          description: >-
            The result of the flight plan creation or update attempt by the emulated user.
            If any option other than `Completed` is specified, the `notes` field should be populated with the reason for the unsuccessful outcome.
          anyOf:
            - $ref: '#/components/schemas/PlanningActivityResult'
        notes:
          description: >-
            Human-readable explanation of the observed result.  This explanation
            may be made available to a human reviewing the test results, and
            ideally should explain why an undesirable result was obtained.  For
            instance, if the injection attempt Failed, then these notes may
            indicate that the attempt failed because the DSS indicated 400 to a
            valid request (perhaps also including the valid request as proof).
          type: string
          example: Requested flight intersected operational intent c036326c-c97b-4926-bf9f-c60dc83d2b57
        flight_plan_status:
          description: >-
            The status of the user's flight plan following the flight planning activity.
          anyOf:
            - $ref: '#/components/schemas/FlightPlanStatus'
        includes_advisories:
          description: >-
            Nature of advisories included in the response to the user regarding their attempt to perform this flight
            planning activity.
          anyOf:
            - $ref: '#/components/schemas/AdvisoryInclusion'

    DeleteFlightPlanResponse:
      type: object
      required:
        - planning_result
        - flight_plan_status
      properties:
        planning_result:
          description: >-
            The result of attempted flight plan cancellation/closure by the USS admin.
            If any option other than `Completed` is specified, the `notes` field should be populated with the reason for the unsuccessful outcome.
          anyOf:
            - $ref: '#/components/schemas/PlanningActivityResult'
        notes:
          description: >-
            Human-readable explanation of the observed result.
          type: string
          example: DSS was unreachable when attempting to delete operational intent reference
        flight_plan_status:
          description: >-
            The status of the user's flight plan following the flight planning activity.
          anyOf:
            - $ref: '#/components/schemas/FlightPlanStatus'
        includes_advisories:
          description: >-
            Nature of advisories included in the response to the user regarding their attempt to cancel/close their
            flight plan.
          anyOf:
            - $ref: '#/components/schemas/AdvisoryInclusion'

    ClearAreaRequest:
      type: object
      required:
        - request_id
        - extent
      properties:
        request_id:
          description: >-
            Unique string identifying this request.  If a second request with an
            identical ID is received, the USS may return the same response from
            the previous operation rather than attempting to clear the area
            again (the USS may also attempt to clear the area again).
          type: string
        extent:
          description: >-
            The USS admin should cancel and remove any flight plan it manages where
            any part of that flight plan intersects this area.
          anyOf:
            - $ref: './geotemporal.yaml#/components/schemas/Volume4D'
    ClearAreaOutcome:
      type: object
      properties:
        success:
          description: >-
            True if, and only if, all flight plans in the specified area managed by the
            USS were canceled and removed.
          type: boolean
          default: false
        message:
          description: >-
            If the USS admin was unable to clear the entire area, this message can
            provide information on the problem encountered.
          type: string
          example: >-
            DSS at dss.example.com returned 500 when attempting to delete
            operational intent 57e98b17-aefa-4eee-a376-5140e4a8385f
        details:
          description: Optional free-form structured data to augment `message`.
          type: object
    ClearAreaResponse:
      type: object
      required:
        - outcome
      properties:
        outcome:
          $ref: '#/components/schemas/ClearAreaOutcome'

    QueryUserNotificationsResponse:
      type: object
      description: Response object for query request for notifications observed by the virtual user.
      required:
        - user_notifications
      properties:
        user_notifications:
          description: List of applicable observed user notifications.
          type: array
          items:
            $ref: './user_notification.yaml#/components/schemas/UserNotification'

paths:
  /status:
    get:
      security:
        - Authority:
            - interuss.flight_planning.direct_automated_test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
          description: >-
            This automated testing interface is available and its status was retrieved successfully.
        '401':
          description: Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.
        '403':
          description: The access token was decoded successfully but did not include a scope appropriate to this endpoint.
        '404':
          description: This automated testing interface is not available.
      summary: Status of this automated testing interface
      description: Get the status of this automated testing interface.
      operationId: GetStatus

  /clear_area_requests:
    post:
      security:
        - Authority:
            - interuss.flight_planning.direct_automated_test

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClearAreaRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearAreaResponse'
          description: Requested area was cleared successfully
        '401':
          description: Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.
        '403':
          description: The access token was decoded successfully but did not include a scope appropriate to this endpoint.

      summary: Clear area
      operationId: ClearArea
      description: >-
        This endpoint requests that the USS admin cancel and remove all flight plans in the specified area.

  /flight_plans/{flight_plan_id}:
    parameters:
      - name: flight_plan_id
        in: path
        required: true
        description: A UUID-formatted string identifying the user's flight plan intent.
        schema:
          $ref: '#/components/schemas/FlightPlanID'

    put:
      security:
        - Authority:
            - interuss.flight_planning.plan

      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertFlightPlanRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpsertFlightPlanResponse'
          description: Requested data was processed successfully
        '401':
          description: Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.
        '403':
          description: The access token was decoded successfully but did not include a scope appropriate to this endpoint.
        '409':
          description: The request contains a duplicate request_id and the response for that request is not available, or another conflict condition occurred.

      summary: Upsert flight plan
      operationId: UpsertFlightPlan
      description: >-
        This endpoint simulates a user intention to submit a new or updated flight plan.

    delete:
      security:
        - Authority:
            - interuss.flight_planning.direct_automated_test

      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteFlightPlanResponse'
          description: Flight plan was deleted successfully
        '401':
          description: Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.
        '403':
          description: The access token was decoded successfully but did not include a scope appropriate to this endpoint.
        '404':
          description: The specified flight plan could not be found (it may have already been deleted).

      summary: Close flight plan
      operationId: DeleteFlightPlan
      description: >-
        This endpoint allows the test director to instruct the USS to remove a flight plan that is no longer needed for testing.

  /user_notifications:
    get:
      operationId: QueryUserNotifications
      security:
        - Authority:
            - interuss.flight_planning.plan
      parameters:
        - name: after
          description: >-
            Do not include any notifications observed before this time. 
            The property 'observed_at' in UserNotification is to be used for comparison.
          schema:
            type: string
            format: date-time
          example: '2024-04-22T16:36:50.52Z'
          in: query
          required: true
        - name: before
          description: >-
            Do not include any notifications observed after this time. 
            This time must be after the time specified in 'after' parameter. 
            If not provided, then the value defaults to now. 
            The property 'observed_at' in UserNotification is to be used for comparison.
          schema:
            type: string
            format: date-time
          example: '2024-04-22T16:41:50.52Z'
          in: query
          required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueryUserNotificationsResponse'
          description: User notifications sent retrieved successfully.
        '400':
          description: The request was missing 'after' query parameter, or the request was otherwise invalid.
        '401':
          description: Bearer access token was not provided in Authorization header, token could not be decoded, or token was invalid.
        '403':
          description: The access token was decoded successfully but did not include a scope appropriate to this endpoint.
      summary: User notifications
      description: >-
        Returns the list of user notifications observed by the virtual user and applicable to the query parameters.  
        The implementation of this endpoint requires that the user notifications be available for querying until the end of a test run.
        The user notifications should be available to be queried within 5 seconds of observation by the virtual user.