geo-awareness.yaml

openapi: 3.0.2
info:
  title: Geo-Awareness Automated Test Interfaces
  version: 0.2.2
  license:
    name: Apache License v2.0
    url: https://github.com/interuss/dss/blob/master/LICENSE
  description: >-
    This interface is implemented by every USS wishing to be tested by the automated testing framework.
    The automated testing suite calls this interface to load test data into the USS system under test and
    read Geo-Awareness information to evaluate its processing and interpretation.

servers:
  - url: https://uss.example.com/geo-awareness

components:
  securitySchemes:
    Authority:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.example.com/oauth/token
          scopes:
            geo-awareness.test: |-
              Client may instruct the USS under test to load Geozone data and may read Geo-Awareness information.
      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/geoawareness/geozone_sources/133bd471-ba61-4f1f-ae51-11570c2b3bb9, 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 the USS automated testing interface.

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

            - `Ready`: the USS is ready to receive test requests.
          type: string
          enum: [Starting, Ready]
          example: Ready

    CreateGeozoneSourceRequest:
      type: object
      properties:
        https_source:
          $ref: '#/components/schemas/GeozoneHttpsSource'

    GeozoneHttpsSource:
      type: object
      required:
        - url
      properties:
        url:
          type: string
          format: url
          description: The URL at which the Geozone 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

    GeozoneSourceResponse:
      type: object
      required:
        - result
      properties:
        result:
          description: >-
            The status of the Geozone source and the handling of its data by the USS.

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

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

            - `Deactivating`: the Geozone data is being deactivated.

            - `Unsupported`: the USS cannot process the dataset type specified.

            - `Rejected`: the Geozone data was rejected because it is invalid.

            - `Error`: the Geozone data activation or deactivation failed. The message field is required in this case.
          type: string
          enum: [Activating, Ready, Deactivating, 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.

    #######################################################################
    #################### Start of ED-269 definitions    ###################
    #######################################################################

    UomDimensions:
      type: string
      enum:
        - M
        - FT

    VerticalReferenceType:
      type: string
      enum:
        - AGL
        - AMSL

    USpaceClass:
      type: string
      maxLength: 100

    Restriction:
      type: string
      enum:
        - PROHIBITED
        - REQ_AUTHORISATION
        - CONDITIONAL
        - NO_RESTRICTION

    #######################################################################
    #################### END of ED-269 definitions    #####################
    #######################################################################

    Position:
      type: object
      required:
        - uomDimensions
        - verticalReferenceType
      properties:
        uomDimensions:
          $ref: '#/components/schemas/UomDimensions'
        verticalReferenceType:
          $ref: '#/components/schemas/VerticalReferenceType'
        height:
          description: >-
            Height above vertical reference datum indicated in `verticalReferenceType`, in units of `uomDimensions`.
          type: number
          default: 0
        longitude:
          description: >-
            Longitude, degrees east of prime meridian.
          type: number
          default: 0
        latitude:
          description: >-
            Latitude, degrees north of the equator.
          type: number
          default: 0

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

    GeozonesCheck:
      type: object
      required:
        - filterSets
      properties:
        filterSets:
          description: >-
            Select Geozones which match any of the specified filter sets.
          type: array
          items:
            $ref: '#/components/schemas/GeozonesFilterSet'

    GeozonesFilterSet:
      description: >-
        Set of filters to select only a subset of Geozones.  Only Geozones which are applicable to all specified filters within this filter set should be selected.
      type: object
      properties:
        position:
          description: >-
            If specified, only select Geozones encompassing this position.
          anyOf:
            - $ref: '#/components/schemas/Position'
        after:
          description: >-
            If specified, only select Geozones which encompass at least some times at or after this time.
          type: string
          format: date-time
        before:
          description: >-
            If specified, only select Geozones which encompass at least some times at or before this time.
          type: string
          format: date-time
        ed269:
          $ref: '#/components/schemas/ED269Filters'

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

    GeozonesCheckReply:
      type: object
      properties:
        applicableGeozone:
          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/GeozonesCheckResult'
          default: []

    GeozonesCheckResult:
      type: object
      required:
      - geozone
      properties:
        geozone:
          type: string
          description: >-
            Indication of whether one or more applicable Geozones were selected according to the selection criteria of the corresponding check.
            
            * Present: One or more applicable Geozones were selected.
            * Absent: No applicable Geozones were selected.
            * UnsupportedFilter: Applicable Geozones could not be selected because one or more filter criteria are not supported by the USSP.  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 non-standard `geozone` value was reported.  Should only be populated when appropriate according to the value of the `geozone` field.
          example: >-
            U-space flight authorisations are not blocked by the USSP according to geo-awareness data (GM1 Article 10 (7)).

paths:
  /status:
    get:
      operationId: GetStatus
      security:
        - Authority:
            - geo-awareness.test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
          description: >-
            The USS automated testing interface is activated 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 USS automated testing interface is not activated.
      summary: Status of the USS automated testing interface
      description: Get the status of the USS automated testing interface.

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

    put:
      security:
        - Authority:
            - geo-awareness.test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGeozoneSourceRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeozoneSourceResponse'
          description: >-
            Request has been correctly handled and the USS has been instructed to import and activate the Geozone 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.
      operationId: PutGeozoneSource
      summary: Import and activate a Geozone source
      description: Instructs the USS to import and activate the Geozone data from this source.

    get:
      security:
        - Authority:
            - geo-awareness.test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeozoneSourceResponse'
          description: >-
            The Geozone source exists in the USS 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 Geozone source has been successfully deactivated or didn't exist.
      operationId: GetGeozoneSourceStatus
      summary: Status of a Geozone source
      description: Get the status of the Geozone source and its data.

    delete:
      security:
        - Authority:
            - geo-awareness.test
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeozoneSourceResponse'
          description: >-
            Request has been correctly handled and the Geozones dataset will be deleted by the USS.
            Status of the dataset shall 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: DeleteGeozoneSource
      summary: Deactivate a Geozone source
      description: Instructs the USS to deactivate the Geozone source and its data.

  /geozones/check:
    post:
      security:
        - Authority:
            - geo-awareness.test
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GeozonesCheckRequest'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeozonesCheckReply'
          description: >-
            The check 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: CheckGeozones
      summary: Check for applicable Geozones
      description: Check if one or multiple Geozones are applicable at the position of interest for the specified period of time and operational conditions.