Add general-purpose versioning API

README.md

@@ -17,3 +17,5 @@ This repository houses the interfaces a USS/USSP must implement in order to be t
   * [v1 YAML](scd/v1/scd.yaml)
 * [Flight planning](flight_planning/README.md)
   * [v1 YAML](flight_planning/v1/flight_planning.yaml)
+* [Versioning](versioning/README.md)
+  * [YAML](versioning/versioning.yaml)

flight_planning/v1/flight_planning.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.2
 info:
   title: Flight Planning Automated Testing Interface
-  version: 0.1.0
+  version: 0.2.0
   description: >-
     This interface is implemented by a USS wishing to participate in automated tests involving attempts to plan flights.
 
@@ -47,21 +47,16 @@ components:
           type: string
           enum: [Starting, Ready]
           example: Ready
-        system_version:
-          description: |-
-            Arbitrary string representing the version of the USS system to be tested.
-          type: string
-          example: v0.0.1-445ad3
         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.1.0" when implementing this version of the API.
+            Indication of the API version implemented at this URL.  Must be "v0.2.0" when implementing this version of the API.
           type: string
-          example: v0.1.0
+          example: v0.2.0
 
     FlightPlan:
       description: >-

geo-awareness/v1/geo-awareness.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.2
 info:
   title: Geo-Awareness Automated Test Interfaces
-  version: 0.1.0
+  version: 0.2.0
   license:
     name: Apache License v2.0
     url: https://github.com/interuss/dss/blob/master/LICENSE
@@ -53,11 +53,6 @@ components:
           type: string
           enum: [Starting, Ready]
           example: Ready
-        version:
-          description: |-
-            Arbitrary string representing the version of the USS system to be tested.
-          type: string
-          example: v0.0.1-445ad3
 
     CreateGeozoneSourceRequest:
       type: object

geospatial_map/v1/geospatial_map.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.2
 info:
   title: Geospatial Map Provider Automated Testing Interface
-  version: 0.1.0
+  version: 0.2.0
   license:
     name: Apache License v2.0
     url: https://github.com/interuss/automated_testing_interfaces/blob/main/LICENSE.md
@@ -63,21 +63,16 @@ components:
           type: string
           enum: [Starting, Ready]
           example: Ready
-        system_version:
-          description: |-
-            Arbitrary string representing the version of the USS system to be tested.
-          type: string
-          example: v0.0.1-445ad3
         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.1.0" when implementing this version of the API.
+            Indication of the API version implemented at this URL.  Must be "v0.2.0" when implementing this version of the API.
           type: string
-          example: v0.1.0
+          example: v0.2.0
 
     CreateGeospatialDataSourceRequest:
       type: object

scd/v1/scd.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.2
 info:
   title: Strategic Coordination Test Data Injection
-  version: 0.1.0
+  version: 0.2.0
   description: >-
     This interface is implemented by every USS wishing to enable the automated testing framework to interact with the
     USS as a user planning flights.  This interaction capability is required by some automated tests.
@@ -35,11 +35,6 @@ components:
           type: string
           enum: [Starting, Ready]
           example: Ready
-        version:
-          description: |-
-            Arbitrary string representing the version of the USS system to be tested.
-          type: string
-          example: v0.0.1-445ad3
     ################################################################################
     #################### Start of ASTM-standard definitions    #####################
     #################### interfaces/astm-utm/Protocol/utm.yaml #####################

versioning/README.md

@@ -0,0 +1,11 @@
+# Versioning automated testing interface
+
+## Purpose
+
+The goal of automated testing is to verify that a system under test meets desired sets of requirements.  The primary statement a test participant generally wants to make after successfully completing an automated test run is that their system under test has been verified to be compliant with one or more particular sets of requirements.  But, this statement begs the question of which system was under test.
+
+The API is intended to allow USSs to identify the exact system under test (by reporting its version) at the time the test is conducted.  Under typical release practices, a release candidate would be required to pass automated tests in a qualification environment before being promoted to production.  Under those practices, the expectation would be that the version of software in production always matches a version with a passing test report in the qualification environment.  This interface provides the means by which that version can be determined both in the qualification environment during test and in production (for verification of these release practices).
+
+## Overview
+
+[This API](versioning.yaml) is designed to enable USSs to respond to the question, "What version of your system is running?"  This question is complicated by the fact that a USS needs a clear definition of the scope of "system" in order to answer the question meaningfully.  Rather than try to create that system scope/boundary definition itself, this API resolves this question by allowing the questioner to refer to a system boundary definition defined external to this interface but known to both the USS and the questioner.

versioning/versioning.yaml

@@ -0,0 +1,88 @@
+openapi: 3.0.2
+info:
+  title: Versioning Automated Testing Interface
+  version: 0.1.0
+  description: >-
+    This interface is implemented by a USS wishing to provide information about the version(s) of its software to
+    authorized recipients in an automated fashion.
+
+    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.versioning.read_system_versions: |-
+              Client may read the version(s) of the USS's software deployed in this environment.
+      description: |-
+        Authorization from, or on behalf of, an authorization authority, for the purpose of facilitating automated testing.
+
+  schemas:
+    SystemBoundaryIdentifier:
+      type: string
+      description: >-
+        Identifier of a system boundary, known to both the client and the USS separate from this API, for which a USS
+        can provide a version.  While the format is not prescribed by this API, any value must be URL-safe.  It is
+        recommended to use an approach similar to reverse-order Internet domain names and Java packages where the global
+        scope is described with increasingly-precise identifiers joined by periods.  For instance, the system boundary
+        containing the mandatory Network Identification U-space service might be identified with
+        `gov.eu.uspace.v1.netid` because the authority defining this system boundary is a governmental organization
+        (specifically, the European Union) with requirements imposed on the system under test by the U-space regulation
+        (first version) -- specifically, the Network Identification Service section.
+      example: gov.au.casa.operating_rules.v2_6
+
+    VersionIdentifier:
+      type: string
+      description: >-
+        Identifier of a particular version of a system (defined by a known system boundary).  While the format is not
+        prescribed by this API, a semantic version (https://semver.org/) prefixed with a `v` is recommended.
+      example: v2.19.53117-rc8+d3a7521f
+
+    GetVersionResponse:
+      type: object
+      properties:
+        system_identity:
+          description: The requested system identity/boundary.
+          anyOf:
+            - $ref: '#/components/schemas/SystemBoundaryIdentifier'
+        system_version:
+          description: The USS's version for the system with the specified system identity/boundary.
+          anyOf:
+            - $ref: '#/components/schemas/VersionIdentifier'
+
+paths:
+  /versions/{system_identity}:
+    parameters:
+      - name: system_identity
+        in: path
+        required: true
+        description: The system identity/boundary for which a version should be provided, if known.
+        schema:
+          $ref: '#/components/schemas/SystemBoundaryIdentifier'
+
+    get:
+      security:
+        - Authority:
+            - interuss.versioning.read_system_versions
+      responses:
+        '200':
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GetVersionResponse'
+          description: >-
+            The USS successfully provided the version of the system identity/boundary that was requested.
+        '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 requested system identity/boundary is not known, or the versioning automated testing interface is not available.
+      summary: System version
+      description: Get the requested system version.
+      operationId: GetVersion