observation.yaml

openapi: 3.0.2
info:
  title: Remote ID Display Data Observation
  version: 0.3.0
  description: >-
    This interface is provided by every Display Provider wishing to be tested by the automated testing framework.
    The automated testing suite calls this interface to obtain current remote ID information from the perspective of a user of the Display Provider.
paths:
  /display_data:
    get:
      parameters:
        -
          examples:
            pyramids:
              value: '29.97816,31.13296,29.98025,31.13535'
          name: view
          description: >-
            The area of this view: lat1,lng1,lat2,lng2.  The view is the smallest box bounded by
            the provided corner points.
          schema:
            type: string
          in: query
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDisplayDataResponse'
          description: Current remote ID display data was retrieved successfully.
      operationId: getDisplayData
      summary: Poll display data
      description: Request current remote ID display data as would be visualized by a Display Application.
      security:
        - RIDAuth:
            - dss.read.identification_service_areas
  /display_data/{id}:
    get:
      parameters:
        -
          examples:
            default:
              value: '1e3adb99-acc9-424f-a04e-a0743538849a'
          name: id
          description: >-
            ID of flight identified in `/display_data`.
          schema:
            type: string
          in: path
          required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDetailsResponse'
          description: Details about the requested flight were retrieved successfully.
        '404':
          description: Requested flight was not found.
      operationId: getDetails
      summary: Get flight details
      description: Get the details of a flight identified in `/display_data`.
      security:
        - RIDAuth:
            - dss.read.identification_service_areas
components:
  schemas:
    GetDisplayDataResponse:
      description: Response to a request for current data that would be visualized by a Display Application.
      type: object
      properties:
        flights:
          description: Current information for set of discovered flights whose precise locations are known.
          type: array
          items:
            $ref: '#/components/schemas/Flight'
          default: []
        clusters:
          description: >-
            Current information for sets of discovered flights whose precise locations are not
            known.
          type: array
          items:
            $ref: '#/components/schemas/Cluster'
          default: []
    GetDetailsResponse:
      description: Response to a request to get details about a flight.
      type: object
      properties:
        operator:
          anyOf:
            - $ref: '#/components/schemas/Operator'
        uas:
          anyOf:
            - $ref: '#/components/schemas/UAS'
    Flight:
      description: ''
      required:
        - id
      type: object
      properties:
        id:
          description: >-
            Identifier of flight that may be used to obtain details about the flight.
            This is not necessarily the UTM/flight ID in the remote ID system.
          type: string
        aircraft_type:
          anyOf:
            - $ref: 'commons.yaml#/components/schemas/UAType'
          description: Aircraft type of the flight.
        current_state:
          $ref: '#/components/schemas/CurrentState'
        most_recent_position:
          description: Most recent position known for the flight.
          allOf:
            - $ref: '#/components/schemas/Position'
        recent_paths:
          description: Paths the flight recently traveled, if available.
          type: array
          items:
            $ref: '#/components/schemas/Path'
    CurrentState:
      description: 'Current state of an aircraft.'
      type: object
      properties:
        timestamp:
          description: Time at which the message containing the current state information was generated by the display provider.
          type: string
        timestamp_accuracy:
          $ref: 'commons.yaml#/components/schemas/TimestampAccuracy'
        operational_status:
          $ref: 'commons.yaml#/components/schemas/RIDOperationalStatus'
        track:
          $ref: 'commons.yaml#/components/schemas/RIDTrack'
        speed:
          $ref: 'commons.yaml#/components/schemas/RIDSpeed'
        speed_accuracy:
          anyOf:
            - $ref: 'commons.yaml#/components/schemas/SpeedAccuracy'
          description: Accuracy of horizontal ground speed.
        vertical_speed:
          $ref: 'commons.yaml#/components/schemas/VerticalSpeed'
        # TODO for next version: Move most_recent_position here.
    Operator:
      description: "Operator's information"
      type: object
      properties:
        id:
          description: >-
            CAA-issued registration/license ID for the remote pilot or operator.
          type: string
        location:
          anyOf:
            - $ref: 'commons.yaml#/components/schemas/LatLngPoint'
        altitude:
          anyOf:
            - $ref: 'commons.yaml#/components/schemas/OperatorAltitude'
    UAS:
      description: 'UAS information'
      type: object
      properties:
        id:
          description: Observed arbitrary and format agnostic (string) identification of a UAS.
          type: string
        eu_classification:
          description: When this field is specified, the Classification Type is "European
            Union".  If no other classification field is specified, the Classification Type
            is "Undeclared".
          anyOf:
            - $ref: 'commons.yaml#/components/schemas/UAClassificationEU'
    Cluster:
      description: 'A general area containing one or more flight.'
      type: object
      required:
        - corners
        - area_sqm
        - number_of_flights
      properties:
        corners:
          description: Two opposite corners of a rectangular lat-lng box bounding the cluster.
          type: array
          items:
            $ref: '#/components/schemas/Position'
          minItems: 2
          maxItems: 2
        area_sqm:
          description: Area of the cluster in square meters.
          type: number
          format: double
        number_of_flights:
          description: Number of flights within the cluster.
          type: number
          format: int32
          minimum: 1
    Position:
      description: 'A position on Earth.'
      required:
        - lat
        - lng
      type: object
      properties:
        lat:
          $ref: 'commons.yaml#/components/schemas/Latitude'
        lng:
          $ref: 'commons.yaml#/components/schemas/Longitude'
        alt:
          $ref: 'commons.yaml#/components/schemas/Altitude'
        accuracy_h:
          anyOf:
            - $ref: 'commons.yaml#/components/schemas/HorizontalAccuracy'
          description: Horizontal error that is likely to be present in this reported
            position.
        accuracy_v:
          anyOf:
            - $ref: 'commons.yaml#/components/schemas/VerticalAccuracy'
          description: Vertical error that is likely to be present in this reported
            position.
        msl_alt:
          $ref: 'commons.yaml#/components/schemas/MSLAltitude'
        height:
          $ref: 'commons.yaml#/components/schemas/RIDHeight'
    Path:
      description: Path followed by a flight.
      required:
        - positions
      type: object
      properties:
        positions:
          description: Sequential positions available for a flight.
          type: array
          items:
            $ref: '#/components/schemas/Position'
  securitySchemes:
    RIDAuth:
      flows:
        clientCredentials:
          tokenUrl: https://example.com/oauth/token
          scopes:
            dss.read.identification_service_areas: Client may read current remote ID information.
      type: oauth2
      description: |-
        Authorization from, or on behalf of, an authorization authority, matching standard remote ID authorization.

        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/rid_observation/display_data/a1711ef3-2373-4ea2-bbbc-f92f57285406, 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.
security:
  - RIDAuth:
      - dss.read.identification_service_areas