geospatial_map.yaml

openapi: 3.0.2
info:
  title: Geospatial Map Provider Automated Testing Interface
  version: 0.2.3
  license:
    name: Apache License v2.0
    url: https://github.com/interuss/automated_testing_interfaces/blob/main/LICENSE.md
  description: >-
    This interface is implemented to provide uss_qualifier (and perhaps other similar clients) with the
    capability to pretend to be a user interacting with the USS's geospatial map representation for the purpose of
    evaluating potential flight plans.
    
    This interface is used by InterUSS's geospatial feature comprehension tests, so every USS wishing to be tested by
    those tests must provide this interface.
    
    The automated testing suite may call this interface to first load test data into the USS system under test, and then
    will perform virtual queries on the USS's geospatial map to evaluate its processing and interpretation of the
    relevant geospatial data.

servers:
  - url: https://uss.example.com/geospatial_map

components:
  securitySchemes:
    TestAuthority:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            interuss.geospatial_map.direct_automated_test: |-
              Client may determine the test-readiness of the USS and instruct the USS admin to load geospatial data from
              specified data sources (acting as a test director).
            interuss.geospatial_map.query: |-
              Client may read information from the USS's geospatial map as visible to a user of the USS's geospatial map.
      description: |-
        Authorization from, or on behalf of, an authorization authority, augmenting standard Geo-Awareness 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/geospatial_map/geospatial_data_sources/32ef0162-30c4-4e56-9ce0-b204155ef93d, 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:
    UUIDv4Format:
      description: >-
        String whose 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 "Geospatial Map Provider Automated Testing Interface".
          type: string
          example: Geospatial Map Provider Automated Testing Interface
        api_version:
          description: |-
            Indication of the API version implemented at this URL.  Must be "v0.2.2" when implementing this version of the API.
          type: string
          example: v0.2.2

    CreateGeospatialDataSourceRequest:
      type: object
      properties:
        https_source:
          $ref: '#/components/schemas/GeospatialHttpsSource'

    GeospatialHttpsSource:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: url
          description: The URL at which the Geospatial data shall be downloaded from.
          example: https://caa.example.com/geozones.json
        format:
          type: string
          description: The format of the response expected from the source.
          enum: [ED-269]
          example: ED-269

    GeospatialDataSourceStatus:
      type: object
      required:
        - id
        - status
      properties:
        id:
          description: >-
            ID of this geospatial data source
          anyOf:
            - $ref: '#/components/schemas/UUIDv4Format'
        status:
          description: >-
            The status of the Geospatial source and the handling of its data by the USS.

            - `Activating`: the USS is processing the request and is currently activating the geospatial data.

            - `Ready`: the geospatial data has been successfully activated and the USS is ready to receive test requests.

            - `Deactivating`: the geospatial dataset is being deactivated.
            
            - `Deactivated`: the geospatial dataset has been deactivated (the USS may instead return 404 as well).

            - `Unsupported`: the USS cannot process the dataset type specified, or some valid feature within the dataset. The message field is required in this case.

            - `Rejected`: the geospatial data source was rejected because it failed content validation or was otherwise unsuitable to use. The message field is required in this case.

            - `Error`: the geospatial data activation or deactivation failed for a reason not covered by one of the previous options. The message field is required in this case.
          type: string
          enum: [Activating, Ready, Deactivating, Deactivated, Unsupported, Rejected, Error]
          example: Ready
        message:
          description: Human-readable explanation of the result for debugging purpose only. This field is required when the result value is `Error`.
          type: string
          example: |-
            Unable to download the dataset https://caa.example.com/geozones.json. Connection refused.

    GeospatialDataSourceResponse:
      type: object
      required:
        - data_source
      properties:
        data_source:
          $ref: '#/components/schemas/GeospatialDataSourceStatus'

    ListGeospatialDataSourcesResponse:
      type: object
      properties:
        data_sources:
          type: array
          items:
            $ref: '#/components/schemas/GeospatialDataSourceStatus'

    Position:
      type: object
      required:
        - location
      properties:
        altitude:
          description: >-
            Position's height above a vertical reference datum.
          anyOf:
            - $ref: './astm_f3548_21.yaml#/components/schemas/Altitude'
        location:
          description: >-
            Position's horizontal (along Earth's surface) location.
          anyOf:
            - $ref: './astm_f3548_21.yaml#/components/schemas/LatLngPoint'

    GeospatialMapQueryRequest:
      type: object
      required:
        - checks
      properties:
        checks:
          type: array
          items:
            $ref: '#/components/schemas/GeospatialMapCheck'

    GeospatialMapCheck:
      type: object
      required:
        - filterSets
      properties:
        filter_sets:
          description: >-
            Select geospatial features which match any of the specified filter sets.
          type: array
          items:
            $ref: '#/components/schemas/GeospatialFeatureFilterSet'

    GeospatialFeatureFilterSet:
      description: >-
        Set of filters to select only a subset of geospatial features.  Only geospatial features which are applicable to all specified filters within this filter set should be selected.
      type: object
      properties:
        position:
          description: >-
            If specified, only select geospatial features encompassing this position.
          anyOf:
            - $ref: '#/components/schemas/Position'
        volumes4d:
          description: >-
            If specified, only select geospatial features at least partially intersecting one or more of these volumes.
          type:
            array
          items:
            $ref: './astm_f3548_21.yaml#/components/schemas/Volume4D'
        after:
          description: >-
            If specified, only select geospatial features which encompass at least some times at or after this time.
          type: string
          format: date-time
        before:
          description: >-
            If specified, only select geospatial features which encompass at least some times at or before this time.
          type: string
          format: date-time
        restriction_source:
          description: >-
            If specified, only select geospatial features originating from the named source.  The acceptable values for
            this field will be established by the test designers and will generally be used to limit responses to only
            the intended datasets under test even when the USS may have more additional geospatial features from other
            sources that may otherwise be relevant.
          type: string
          example: FAA_LAANC
        operation_rule_set:
          description: >-
            If specified, only select geospatial features that would be relevant when planning an operation under the
            specified rule set.  The acceptable values for this field will be established by the test designers and will
            generally correspond to sets of rules under which the system under test plans operations.
          type: string
          example: Part107
        resulting_operational_impact:
          description: >-
            If specified, only select geospatial features that would cause the specified outcome if a user attempted to
            plan a flight applicable to all the other criteria in this filter set.
            
            'Block': The geospatial feature would cause rejection of that flight (the USS would decline to plan the
              flight).
            
            'Advise': The geospatial feature would cause the USS to accompany a successful flight plan (if the flight
              was successfully planned) with an advisory or condition provided to the operator.
            
            'BlockOrAdvise': The geospatial feature would cause one of 'Block' or 'Advise' to be be true.
          type: string
          enum:
            - Block
            - Advise
            - BlockOrAdvise
        ed269:
          $ref: '#/components/schemas/ED269Filters'

    ED269Filters:
      description: >-
        Filter criteria for the selection of Geozones according to ED-269 characteristics.
      type: object
      properties:
        u_space_class:
          description: >-
            If specified, only select Geozones which are of the specified `u_space_class`.
          anyOf:
            - $ref: './ed269.yaml#/components/schemas/USpaceClass'
        acceptable_restrictions:
          description: >-
            If specified and non-empty, only select Geozones which are one of the specified restriction types.
          type: array
          items:
            $ref: './ed269.yaml#/components/schemas/Restriction'

    GeospatialMapQueryReply:
      type: object
      properties:
        results:
          description: >-
            Responses to each of the `checks` in the request.  The number of entries in this array should match the number of entries in the `checks` field of the request.
          type: array
          items:
            $ref: '#/components/schemas/GeospatialMapCheckResult'
          default: []

    GeospatialMapCheckResult:
      type: object
      required:
        - featuresSelectionOutcome
      properties:
        features_selection_outcome:
          type: string
          description: >-
            Indication of whether one or more applicable geospatial features were selected according to the selection criteria of the corresponding check.
            
            - `Present`: One or more applicable geospatial features were selected.
            
            - `Absent`: No applicable geospatial features were selected.
            
            - `UnsupportedFilter`: Applicable geospatial features could not be selected because one or more filter criteria are not supported by the USS.  If this value is specified, `message` must be populated.
            
            - `Error`: An error or condition not enumerated above occurred.  If this value is specified, `message` must be populated.
          enum:
            - Present
            - Absent
            - UnsupportedFilter
            - Error
        message:
          type: string
          description: >-
            A human-readable description of why the unsuccessful `featuresSelectionOutcome` was reported.  Should only be populated when appropriate according to the value of the `featuresSelectionOutcome` field.
          example: >-
            ED-269 comprehension is not supported.

paths:
  /status:
    get:
      operationId: GetStatus
      security:
        - TestAuthority:
            - interuss.geospatial_map.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.

  /geospatial_data_sources:
    get:
      security:
        - TestAuthority:
            - interuss.geospatial_map.direct_automated_test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGeospatialDataSourcesResponse'
          description: >-
            The USS's geospatial data sources loaded through this interface were 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.
      operationId: ListGeospatialDataSources
      summary: List geospatial data sources
      description: Lists the geospatial data sources loaded by the USS admin at the request of the test director.

  /geospatial_data_sources/{geospatial_data_source_id}:
    parameters:
      - name: geospatial_data_source_id
        in: path
        required: true
        description: A UUID string identifying a geospatial data source.
        schema:
          $ref: '#/components/schemas/UUIDv4Format'

    put:
      security:
        - TestAuthority:
            - interuss.geospatial_map.direct_automated_test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGeospatialDataSourceRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeospatialDataSourceResponse'
          description: >-
            Request has been correctly handled and the USS has been instructed to import and activate the geospatial data from the source.
        '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: A request with this ID has already been made to load a different data source.
      operationId: PutGeospatialDataSource
      summary: Import and activate a geospatial data source
      description: Instructs the USS admin to import and activate the geospatial data from the specified source.

    get:
      security:
        - TestAuthority:
            - interuss.geospatial_map.direct_automated_test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeospatialDataSourceResponse'
          description: >-
            The geospatial data source is known by the USS admin 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: The geospatial data source has been successfully deactivated or didn't exist.
      operationId: GetGeospatialDataSourceStatus
      summary: Status of a geospatial data source
      description: Get the status of the geospatial data source in the USS.

    delete:
      security:
        - TestAuthority:
            - interuss.geospatial_map.direct_automated_test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeospatialDataSourceResponse'
          description: >-
            Request has been correctly handled and the geospatial dataset may be deleted by the USS admin.
            Status of the dataset may be checked using the GET method until it returns a 404.
        '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.
      operationId: DeleteGeospatialDataSource
      summary: Deactivate a geospatial data source
      description: Instructs the USS admin to deactivate the geospatial data source and its data.

  /map/queries:
    post:
      security:
        - TestAuthority:
            - interuss.geospatial_map.query
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeospatialMapQueryRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeospatialMapQueryReply'
          description: >-
            The query was successfully performed.
        '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.
      operationId: QueryGeospatialMap
      summary: Check for applicable geospatial features
      description: Check if one or multiple geospatial features are applicable at the position of interest for the specified period of time and operational conditions.