├── .gitignore ├── README.md ├── _config.yml ├── diagrams ├── UTM Architecture Chart v2017.10.12.png └── tcl4-statemachine.png ├── fims-api └── swagger.yaml ├── fimsauthz-api ├── CHANGELOG.md ├── README.md ├── assets │ ├── jws1-construction.png │ ├── jws2-request-token.png │ ├── jws3-reconstruct-sig.png │ ├── jws4-get-pubkey.png │ └── jws5-respose.png ├── fims-authz.yaml ├── nup-oauth2.yaml ├── nup-roles.yaml └── pseudo-client.md ├── nuss-operator-api ├── README.md ├── images │ ├── conformance-regions.png │ ├── state-v2-1.png │ └── v4-states.png └── swagger.yaml ├── oper-api ├── README.md ├── nup-operator-api.yml ├── nup-operator-roles.yaml ├── operator-api.yaml └── user-to-roles.yaml ├── public-safety-uss ├── README.md ├── images │ └── vehid.png └── swagger.yaml ├── urep-api ├── README.md └── swagger.yaml ├── uss-api ├── README.md └── swagger.yaml ├── uss-discovery-api ├── README.md └── swagger.yaml ├── utm-domains ├── utm-domain-commons.yaml ├── utm-domain-geojson.yaml ├── utm-domain-metadata.yaml └── utm-domain-performance-auth.yaml └── vehicle └── swagger.yaml /.gitignore: -------------------------------------------------------------------------------- 1 | .idea 2 | .DS_Store 3 | utm-apis.iml 4 | .idea/* 5 | .idea 6 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # UTM APIs 2 | 3 | This repository contains the collection of OpenAPI specification APIs within the NASA's research version of the UTM System. Many of UTM's data models are common and these are maintained using Swagger's "Domain" references. 4 | 5 | ## References 6 | 7 | - [UTM Home Page](https://utm.arc.nasa.gov/) 8 | - [UTM Publications](https://utm.arc.nasa.gov/documents.shtml) 9 | - [UTM Swaggerhub](https://app.swaggerhub.com/organizations/utm) 10 | 11 | 12 | ## Sandbox and RELEASE branch 13 | 14 | utm-apis commits pinned to our Sandbox are represented in the RELEASE branch, and the master branch is our development branch. You will generally find the master branch to be ahead of the Sandbox. The tags in RELEASE correspond with our sandbox releases. 15 | 16 | For codegen you generally will point to RELEASE. 17 | 18 | 19 | ## Viewing Local Swagger Spec files 20 | 21 | You have choices to edit/view local swagger files. IMO option 1 is better for viewing all files. A local swagger editor is good if you want rendering. 22 | 23 | 1. Use a text editor that supports YAML: 24 | - Sublime Text 2 highlights YAML well 25 | - [Atom](https://atom.io/) works well and has a [Swagger Lint Plugin](https://atom.io/packages/linter-swagger) that provides a good first cut at valid OpenAPI 2.0 correctness 26 | 27 | 2. Install local [Swagger Editor](https://swagger.io/swagger-editor/) 28 | 29 | 3. Bring up an [online swagger editor](https://editor.swagger.io/) and copy or import the source swagger. 30 | 31 | 32 | ## Codegen 33 | 34 | You can generate code from OpenAPI Specifications (swagger). 35 | 36 | Swagger Hub has a feature where the site will generate code into a zip file which is downloaded. This is a great first checkout, however, it uses the default language-specific configurations. 37 | 38 | One option (which we use) is to generate all the data models into a library. 39 | Note that codegen parses only from API Specifications, not directly from Swagger Domains. 40 | An approach to creating a model-only library is to codegen against all the APIs whereby the generation 41 | output is filtered for model-only. 42 | The argument to the input spec can be a local file or internet 43 | 44 | ```````` 45 | GENERATE="java -Dmodels -DmodelDocs=false -DapiDocs=false -jar $CODEGEN generate -l spring --config config.json" 46 | 47 | $GENERATE -i ${SWREPO}/fims-uss-api/swagger.yaml #localfile input 48 | or 49 | $GENERATE -i https://raw.githubusercontent.com/nasa/utm-apis/master/uss-api/swagger.yaml 50 | 51 | ```````` 52 | 53 | Your language-specific configurations can also generate model-specific data validations. 54 | For example using swagger-codegen's 'Spring server' language you can codegen bean validations 55 | and java8's OffsetDateTime class for date-time using this language-specific config. 56 | 57 | ```````` 58 | 59 | { 60 | "library": "spring-boot", 61 | "java8": "true", 62 | "dateLibrary":"java8", 63 | "modelPackage": "gov.nasa.utm.utmcommons.model", 64 | "useBeanValidation":"true" 65 | } 66 | 67 | ```````` 68 | -------------------------------------------------------------------------------- /_config.yml: -------------------------------------------------------------------------------- 1 | theme: jekyll-theme-slate -------------------------------------------------------------------------------- /diagrams/UTM Architecture Chart v2017.10.12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/diagrams/UTM Architecture Chart v2017.10.12.png -------------------------------------------------------------------------------- /diagrams/tcl4-statemachine.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/diagrams/tcl4-statemachine.png -------------------------------------------------------------------------------- /fims-api/swagger.yaml: -------------------------------------------------------------------------------- 1 | swagger: "2.0" 2 | info: 3 | description: >- 4 | This API describes the RESTful interface from a UAS Service Supplier (USS) 5 | to FIMS. 6 | 7 | version: "v4" 8 | title: "UTM Research Platform, FIMS-USS Interface" 9 | contact: 10 | name: NASA Ames Research Center, Aviation Systems Division 11 | url: https://utm.arc.nasa.gov/ 12 | email: joseph.rios@nasa.gov 13 | license: 14 | name: NASA Open Source Agreement 15 | url: https://ti.arc.nasa.gov/opensource/nosa/ 16 | termsOfService: | 17 | 18 | A. No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES IT "AS IS." 19 | 20 | B. Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT''S USE OF THE SUBJECT SOFTWARE RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING FROM, RECIPIENT''S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY LAW. RECIPIENT''S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, UNILATERAL TERMINATION OF THIS AGREEMENT. 21 | 22 | host: utm.defined.url 23 | basePath: "/fims" 24 | schemes: 25 | - https 26 | 27 | tags: # Have to add 'A' 'B' etc since ordering isn't respected in SwaggerUI. 28 | - name: A. Required Endpoints 29 | description: >- 30 | FIMS implements the USS API where appropriate. For endpoints from the USS API that FIMS does not support, FIMS may return a 404. 31 | - name: B. Version 32 | description: Get information about this server. 33 | - name: C. Data Types 34 | description: Psuedo endpoints used for the documentation of the data models 35 | 36 | securityDefinitions: 37 | fims_ops_security: 38 | type: oauth2 39 | tokenUrl: http://utm.defined.host/oauth/token 40 | flow: application 41 | scopes: 42 | 'utm.nasa.gov_write.operation': Subject can read, create, and update operational data such as operation plans and position reports 43 | 'utm.nasa.gov_write.message': Subject can read, create, and update UTM message data 44 | 'utm.nasa.gov_write.constraint': Subject can read, create, and update UTM constraint data. This means that the Subject can define areas that restrict other operations. 45 | 'utm.nasa.gov_read.fimsadmin': Subject can read data internal to FIMS. 46 | 47 | responses: 48 | WRONG_PROTOCOL: 49 | description: A RESTful call was made to this endpoint but this is not a REST endpoint. Do not use this endpoint for REST calls. 50 | 51 | paths: 52 | /api: 53 | get: 54 | tags: 55 | - B. Version 56 | security: [] 57 | produces: 58 | - application/json 59 | responses: 60 | 200: 61 | description: OK 62 | schema: 63 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Version' 64 | /schema/Operation: 65 | get: 66 | tags: 67 | - C. Data Types 68 | summary: Operation schema 69 | description: | 70 | Illustrates an operation in JSON. This endpoint is not intended for use. 71 | 72 | Note that if you are viewing this in a SwaggerUI, the "try it out" feature will not work since this is not a RESTful endpoint. 73 | produces: 74 | - application/json 75 | responses: 76 | 200: 77 | description: OK 78 | schema: 79 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Operation' 80 | 410: 81 | $ref: "#/responses/WRONG_PROTOCOL" 82 | 83 | /schema/Point: 84 | get: 85 | tags: 86 | - C. Data Types 87 | summary: Point schema 88 | description: | 89 | Illustrates an Point in JSON. This endpoint is not intended for use. 90 | 91 | Note that if you are viewing this in a SwaggerUI, the "try it out" feature will not work since this is not a RESTful endpoint. 92 | produces: 93 | - application/json 94 | responses: 95 | 200: 96 | description: OK 97 | schema: 98 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Point' 99 | 410: 100 | $ref: "#/responses/WRONG_PROTOCOL" 101 | 102 | /schema/LineString: 103 | get: 104 | tags: 105 | - C. Data Types 106 | summary: LineString schema 107 | description: | 108 | Illustrates an LineString in JSON. This endpoint is not intended for use. 109 | 110 | Note that if you are viewing this in a SwaggerUI, the "try it out" feature will not work since this is not a RESTful endpoint. 111 | produces: 112 | - application/json 113 | responses: 114 | 200: 115 | description: OK 116 | schema: 117 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/LineString' 118 | 410: 119 | $ref: "#/responses/WRONG_PROTOCOL" 120 | 121 | /schema/Polygon: 122 | get: 123 | tags: 124 | - C. Data Types 125 | summary: Polygon schema 126 | description: | 127 | Illustrates an Polygon in JSON. This endpoint is not intended for use. 128 | 129 | Note that if you are viewing this in a SwaggerUI, the "try it out" feature will not work since this is not a RESTful endpoint. 130 | produces: 131 | - application/json 132 | responses: 133 | 200: 134 | description: OK 135 | schema: 136 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Polygon' 137 | 410: 138 | $ref: "#/responses/WRONG_PROTOCOL" 139 | 140 | /schema/UTMMessage: 141 | get: 142 | tags: 143 | - C. Data Types 144 | summary: UTM Message schema 145 | description: | 146 | Illustrates the FIMS Alert Message. FIMS may send out Alert Messages from time to time. This endpoint is not intended for use. 147 | 148 | Note that if you are viewing this in a SwaggerUI, the "try it out" feature will not work since this is not a RESTful endpoint 149 | produces: 150 | - application/json 151 | responses: 152 | 200: 153 | description: OK 154 | schema: 155 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMMessage' 156 | 410: 157 | $ref: "#/responses/WRONG_PROTOCOL" 158 | 159 | /schema/ConstraintMessage: 160 | get: 161 | tags: 162 | - C. Data Types 163 | summary: Constraint Message schema 164 | description: | 165 | Illustrates the FIMS Constraint Message. FIMS will send out a Constraint Message when a new constraint is put in place. This endpoint is not intended for use. 166 | 167 | Note that if you are viewing this in a SwaggerUI, the "try it out" feature will not work since this is not a RESTful endpoint 168 | produces: 169 | - application/json 170 | responses: 171 | 200: 172 | description: OK 173 | schema: 174 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UASVolumeReservation' 175 | 410: 176 | $ref: "#/responses/WRONG_PROTOCOL" 177 | -------------------------------------------------------------------------------- /fimsauthz-api/CHANGELOG.md: -------------------------------------------------------------------------------- 1 | # Changelog 2 | 3 | ## v1.1.1 (10/25/2021) 4 | 5 | #### Enhancements: 6 | 7 | - Added optional audience claim support. 8 | - Added new scopes as needed by DSS [See nup-roles.yml for role info] 9 | -------------------------------------------------------------------------------- /fimsauthz-api/README.md: -------------------------------------------------------------------------------- 1 | # FIMS Authorization Server (FIMS-Authz) with Signature Authentication 2 | This API provides an oauth2 token and other endpoints for the FIMS Authorization Server. FIMS-Authz implements the API here https://github.com/nasa/utm-apis/blob/master/fimsauthz-api/fims-authz.yaml. 3 | 4 | ## Message Signing and Signature Authentication 5 | 6 | 1. Client constructs a `xUtmMessageSignatureJws` - 7 | * Client generates a `xUtmMessageSignatureJoseHeader` with the relevant data and assigns it as the header of the `xUtmMessageSignatureJws`. 8 | * Client uses the same character string as the HTTP body and assigns it as the payload of the `xUtmMessageSignatureJws`. 9 | * Client constructs the `xUtmMessageSignatureJws` by base64 encoding the header and payload. 10 | * Client generated the signature of the `xUtmMessageSignatureJws` by calculating the SHA-256 hash of the concatenated header and payload, and it's private key for the hashing. 11 | * Client assigns the generated the signature as the signature of the `xUtmMessageSignatureJws`. 12 | 13 | ![Construction](./assets/jws1-construction.png) 14 | 15 | 2. Client requests FIMS-AZ for an access_token 16 | 17 | * Client creates an HTTP request with the following configuration - 18 | * Request body must be the same character string as the one used for the `xUtmMessageSignatureJws`. 19 | * Request headers has a header called `x-utm-message-signature` which is formed by concatenating the `xUtmMessageSignatureJws`'s header and signature. 20 | 21 | * Clients sends this constructed request to FIMS-Authz 22 | 23 | __A note on url-encoding and signature generation__ 24 | 25 | It is important to note that when generating the signature of the `xUtmMessageSignatureJws`, the payload of the `xUtmMessageSignatureJws` must be the same character string as the HTTP request body. 26 | 27 | Through testing of various of HTTP client libraries, we learnt that there maybe additional _processing_ done by the HTTP client to url-encode the HTTP request's body, which may differ it from the `xUtmMessageSignatureJws`'s payload, thus invalidating the message signing flow. A strategy to avoid this would be to explicitly url-encode the payload string prior to constructing the `xUtmMessageSignatureJws`. Refer to the [pseudo-client.md](./pseudo-client.md) for more details. 28 | 29 | ![Get-token](./assets/jws2-request-token.png) 30 | 31 | 3. FIMS-Authz re-constructs the JWS 32 | 33 | ![reconstruct](./assets/jws3-reconstruct-sig.png) 34 | 35 | 4. FIMS-Authz Verifies the Signature 36 | 37 | FIMS-Authz acquires client's public key from the JoseHeader, and verifies signature using the acquired key 38 | 39 | ![get-pubkey](./assets/jws4-get-pubkey.png) 40 | 41 | 5. FIMS-Authz generates response with token 42 | 43 | ![get-pubkey](./assets/jws5-respose.png) 44 | 45 | # Roles and Scopes 46 | [./nup-roles.yaml](./nup-roles.yaml) maps scopes to roles and provides example usages. 47 | 48 | # Pseudo-Implementation 49 | 50 | A pseudo-implementation for interfacing with FIMS-AZ has been documented here - [pseudo-client.md](./pseudo-client.md) 51 | 52 | # References 53 | * [RFC 6749: OAuth 2.0](https://tools.ietf.org/html/rfc6749) 54 | * [RFC 6750: OAuth Bearer Token Usage](https://tools.ietf.org/html/rfc6750) 55 | * [RFC 7523: JSON Web Token](https://tools.ietf.org/html/rfc7519) 56 | * [RFC 7523: JSON Web Token Profile for OAuth](https://tools.ietf.org/html/rfc7523) 57 | * [RFC 7515: JSON Web Signature](https://tools.ietf.org/html/rfc7515) 58 | * [OAuth Server Metadata](https://tools.ietf.org/html/draft-ietf-oauth-discovery-06) 59 | * [RFC 7662: OAuth Token Introspection](https://tools.ietf.org/html/rfc7662) 60 | * [Java Cryptography Architecture: Standard Names](http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html) 61 | -------------------------------------------------------------------------------- /fimsauthz-api/assets/jws1-construction.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/fimsauthz-api/assets/jws1-construction.png -------------------------------------------------------------------------------- /fimsauthz-api/assets/jws2-request-token.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/fimsauthz-api/assets/jws2-request-token.png -------------------------------------------------------------------------------- /fimsauthz-api/assets/jws3-reconstruct-sig.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/fimsauthz-api/assets/jws3-reconstruct-sig.png -------------------------------------------------------------------------------- /fimsauthz-api/assets/jws4-get-pubkey.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/fimsauthz-api/assets/jws4-get-pubkey.png -------------------------------------------------------------------------------- /fimsauthz-api/assets/jws5-respose.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/fimsauthz-api/assets/jws5-respose.png -------------------------------------------------------------------------------- /fimsauthz-api/fims-authz.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.0 2 | info: 3 | version: 1.1.1 4 | title: Flight Information Management System (FIMS) Authorization (AZ) Server 5 | description: > 6 | 7 | The FIMS AZ service provides authorization services for FIMS stakeholders 8 | within UTM. It is written to the UAS Service Supplier Framework (UFAA) 9 | for Authentication and Authorization" at `https://utm.arc.nasa.gov/docs/2019-UTM_Framework-NASA-TM220364.pdf`. 10 | 11 | The FIMS Authorization Server facilitates the RFC-6749 Client 12 | Credentials flow for clients to USS Network resource servers. 13 | Typically these resource servers include other USSs and discovery systems. 14 | 15 | # Authentication using Message Signing 16 | 17 | Concepts are detailed in the UFAA. 18 | Implementation notes are in the README in this folder at `https://github.com/nasa/utm-apis/blob/master/fimsauthz-api/README.md`. 19 | 20 | This authentication method is designed to provide 21 | message integrity, non-repudiation, and message authentication. 22 | Clients authenticate by providing a JWS signature of the HTTP request body's 23 | `x-www-form-urlencoded` data. The signature is provided in the 24 | `x-utm-message-signature` HTTP header of the HTTP Request. 25 | As specified in the UFAA, the signature is performed using the private key 26 | associated with the certificate specified by `x5u` in the JOSE Header. 27 | 28 | # Roles 29 | 30 | Roles and their scopes are in this folder at `https://github.com/nasa/utm-apis/blob/master/fimsauthz-api/nup-roles.yaml` 31 | 32 | paths: 33 | /token: 34 | post: 35 | tags: 36 | - Token Endpoint 37 | summary: Request an access token. 38 | description: | 39 | The primary endpoint for this authorization server. Used to request an access token 40 | suitable for authorizing data exchanges within the USS Network. 41 | 42 | Implemented per https://tools.ietf.org/html/rfc6749#section-3.2 . 43 | 44 | security: 45 | - fims-jws: [] 46 | 47 | parameters: 48 | - in: header 49 | name: x-utm-message-signature 50 | schema: 51 | type: string 52 | required: true 53 | description: >- 54 | The `x-utm-message-signature` HTTP header is an encode string representation of the 55 | `#/components/schemas/xUtmMessageSignatureJws` with the payload field eliminated. 56 | 57 | Refer to UFAA's section 5.12.5. 58 | 59 | requestBody: 60 | description: Data supplied by the client for a token request. 61 | required: true 62 | content: 63 | application/x-www-form-urlencoded: 64 | schema: 65 | type: object 66 | required: 67 | - grant_type 68 | - client_id 69 | - scope 70 | - current_timestamp 71 | additionalProperties: false 72 | properties: 73 | grant_type: 74 | type: string 75 | description: Type of grant. Must be 'client_credentials'. 76 | enum: 77 | - client_credentials 78 | client_id: 79 | description: The client_id (uss_name) of the requesting USS. 80 | type: string 81 | example: "uss12345.co" 82 | scope: 83 | description: | 84 | The requested scope(s), a list of space-delimited, 85 | case-sensitive names. Same as in RFC 6749. 86 | type: string 87 | example: "utm.strategic_coordination utm.constraint_processing" 88 | audience: 89 | description: | 90 | The hostname of the server with which the resulting access token 91 | will be used. 92 | 93 | If valid, this resource value will be included in the access token 94 | as an aud claim. 95 | 96 | Note the format of this field is a single hostname. This authorization 97 | server does not produce of multi-audience tokens. 98 | 99 | See https://tools.ietf.org/html/rfc7519#section-4.1.3 for more info 100 | on how the aud claim is to be used. 101 | type: string 102 | format: hostname 103 | maxLength: 2000 104 | example: "npsu1.arc.nasa.gov" 105 | current_timestamp: 106 | description: | 107 | A timestamp of the current time generated by the client at request 108 | generation time. UTC only. UTM Commons format with millisecond precision. 109 | 110 | May be used by the authorization server to validate the request. 111 | type: string 112 | format: date-time 113 | example: "2020-06-19T13:37:52.562Z" 114 | 115 | responses: 116 | "200": 117 | description: OK 118 | content: 119 | application/json: 120 | schema: 121 | $ref: "#/components/schemas/HttpTokenResponse" 122 | 123 | "400": 124 | description: >- 125 | - Request did not conform to the API specification or failed validation. 126 | content: 127 | application/json: 128 | schema: 129 | $ref: "#/components/schemas/HttpErrorResponse" 130 | 131 | 132 | /.well-known/oauth-authorization-server: 133 | get: 134 | tags: 135 | - /.well-known/ 136 | summary: Provides metadata related to use of this authorization server 137 | description: | 138 | Per RFC8414, this endpoint provides metadata related to use of this authorization 139 | server. See https://tools.ietf.org/html/rfc8414#section-3 for more details. 140 | responses: 141 | "200": 142 | description: OK 143 | content: 144 | application/json: 145 | schema: 146 | $ref: "#/components/schemas/Metadata" 147 | 148 | /.well-known/jwks.json: 149 | get: 150 | tags: 151 | - /.well-known/ 152 | summary: Serves the public JWKS of the authorization server 153 | description: | 154 | This endpoint serves the signing key(s) the client uses to validate 155 | signatures from the authorization server. 156 | 157 | The JWK Set MAY also contain the server's encryption key or keys, 158 | which are used by clients to encrypt requests to the server. 159 | 160 | When both signing and encryption keys are made available, a "use" 161 | (public key use) parameter value is REQUIRED for all keys in the 162 | referenced JWK Set to indicate each key's intended usage. 163 | 164 | Refer to RFC7517 - https://tools.ietf.org/html/rfc7517 165 | responses: 166 | "200": 167 | description: OK 168 | content: 169 | application/json: 170 | schema: 171 | $ref: "#/components/schemas/JsonWebKeySet" 172 | 173 | servers: 174 | - url: "https://ansp-authority-baseurl/oauth/{info.version}" 175 | 176 | components: 177 | securitySchemes: 178 | fims-jws: 179 | description: | 180 | FIMS-Authz uses a JWS-based approach to authentication. 181 | 182 | USS clients are vetted/qualified in advance and provide an owned DNS 183 | name that serves as their primary identifer. That DNS name is then 184 | included in a certificate (as a subject alternative name) that the 185 | client procures from an approved CA. The private key related to that 186 | public certificate is then used to create a JWS by signing the HTTP 187 | body of the token request. 188 | 189 | The JWS is provided in a "Detached Content" manner, with just 190 | the JWS header and JWS signature fields provided in the HTTP 191 | header. The HTTP body can be used to reconstruct a full JWS. 192 | 193 | See RFC7515 for more information on the detached content approach: 194 | https://tools.ietf.org/html/rfc7515#appendix-F 195 | 196 | Details are provided in: 197 | https://utm.arc.nasa.gov/docs/2019-UTM_Framework-NASA-TM220364.pdf 198 | 199 | type: apiKey 200 | in: header 201 | name: x-utm-message-signature 202 | 203 | schemas: 204 | HttpTokenResponse: 205 | type: object 206 | additionalProperties: false 207 | properties: 208 | access_token: 209 | type: string 210 | format: JwsCompactSerialization 211 | description: see definitions/JwsCompactSerialization in this spec 212 | scope: 213 | type: string 214 | description: | 215 | The granted scope(s), a list of space-delimited, 216 | case-sensitive names. Same as in RFC 6749. 217 | token_type: 218 | type: string 219 | enum: 220 | - bearer 221 | expires_in: 222 | type: number 223 | format: integer 224 | description: see definitions/JwtClaimsSet.exp property in this spec 225 | sub: 226 | type: string 227 | description: see definitions/JwtClaimsSet in this spec 228 | jti: 229 | type: string 230 | format: uuid 231 | description: see definitions/JwtClaimsSet in this spec 232 | iss: 233 | type: string 234 | description: see definitions/JwtClaimsSet in this spec 235 | nbf: 236 | type: number 237 | description: see definitions/JwtClaimsSet in this spec 238 | aud: 239 | type: string 240 | description: see definitions/JwtClaimsSet in this spec 241 | example: 242 | access_token: tokenstring 243 | token_type: bearer 244 | expires_in: 3599 245 | scope: utm.strategic_coordination 246 | sub: nuss1.testing.nasa.gov 247 | nbf: 1509470774 248 | iss: fims.arc.nasa.gov/fimsAuthServer 249 | jti: 4d4c1a63-0959-48cc-885a-3648fd582db7 250 | aud: npsu1.arc.nasa.gov 251 | xUtmMessageSignatureJws: 252 | description: >- 253 | A JWS constructed by the client for requesting a token from FIMS-AZ. 254 | The client shall construct a JWS object with the header as specified by the 255 | `#/components/schemas/xUtmMessageSignatureJoseHeader`, and the payload 256 | as a character string of the HTTP body. The client shall sign the JWS 257 | with their private key. 258 | type: object 259 | additionalProperties: false 260 | properties: 261 | header: 262 | $ref: "#/components/schemas/xUtmMessageSignatureJoseHeader" 263 | payload: 264 | type: object 265 | description: >- 266 | The payload of the JWS will be the same character string as the HTTP body. 267 | signature: 268 | type: string 269 | description: >- 270 | The signature is calculated on the payload based on the information in the header. 271 | xUtmMessageSignatureJoseHeader: 272 | description: >- 273 | The JOSE (JSON Object Signing and Encryption) header of the JWS used in Message Signing. 274 | Refer to UFAA's section 5.12.1 for additional information. 275 | type: object 276 | properties: 277 | alg: 278 | type: string 279 | description: >- 280 | The algorithm used to sign the JWS, which is required to be a 281 | registered JSON Web Algorithm (JWA). See RFC 7518 for details on JWA. 282 | enum: 283 | - RS256 284 | typ: 285 | type: string 286 | description: >- 287 | The type is used by JWS applications to declare the media type of 288 | this complete JWS. In this case, it must be “JOSE” per ​RFC 7515​. 289 | enum: 290 | - JOSE 291 | x5u: 292 | type: string 293 | description: >- 294 | The "x5u" (X.509 URL) Header Parameter is a URI [​RFC 3986]​ that 295 | refers to a resource for the X.509 public key certificate or 296 | certificate chain [​RFC 5280​] corresponding to the key used to 297 | digitally sign the JWS. 298 | example: "https://example.com/.well-known/uas-traffic-management/public.der" 299 | kid: 300 | type: string 301 | description: >- 302 | The Key ID of the JWK used to sign. Note that the jku reference 303 | will provide a set of keys with unique key identifiers. Those 304 | identifiers will be searched to match against this kid. 305 | JsonWebToken: 306 | description: >- 307 | The token provided by the FIMS Authorization Server is a JWS 308 | representing a JWT. The token is actually a JWS Compact Serialization 309 | string as described in RFC 7515. For clarity of documentation, we 310 | represent the pre-serialized components here as a JSON schema. 311 | type: object 312 | additionalProperties: false 313 | properties: 314 | header: 315 | $ref: "#/components/schemas/JwtHeader" 316 | payload: 317 | $ref: "#/components/schemas/JwtClaimsSet" 318 | signature: 319 | type: string 320 | description: See RFC 7515 for details. 321 | JwtHeader: 322 | description: >- 323 | The header of the JWT Bearer Token returned by FIMS-AZ. 324 | type: object 325 | properties: 326 | alg: 327 | type: string 328 | enum: 329 | - RSA 330 | typ: 331 | type: string 332 | enum: 333 | - JWT 334 | description: >- 335 | The FIMS Authorization Server only support 'JWT' (JSON Web Token) as 336 | the algorithm type. 337 | JwtClaimsSet: 338 | type: object 339 | required: 340 | - iss 341 | - sub 342 | - exp 343 | - nbf 344 | - iat 345 | - jti 346 | - scope 347 | - aud 348 | additionalProperties: false 349 | description: Claims included within JWT Bearer Token returned by FIMS-AZ. 350 | properties: 351 | iss: 352 | type: string 353 | format: URL 354 | description: >- 355 | The "iss" (issuer) claim identifies the principal that issued the 356 | JWT. The URL of the FIMS Authorization Server. 357 | sub: 358 | type: string 359 | description: >- 360 | The "sub" (suv4-draft identifies the principal that is the subject 361 | of the JWT. 362 | exp: 363 | type: integer 364 | format: unix-time 365 | description: >- 366 | The "exp" (expiration time) claim identifies the expiration time on 367 | or after which the JWT MUST NOT be accepted for processing. The 368 | processing of the "exp" claim requires that the current date/time 369 | MUST be before the expiration date/time listed in the "exp" claim. 370 | nbf: 371 | type: integer 372 | format: unix-time 373 | description: >- 374 | The "nbf" (not before) claim identifies the time before which the 375 | JWT MUST NOT be accepted for processing. The processing of the 376 | "nbf" claim requires that the current date/time MUST be after or 377 | equal to the not-before date/time listed in the "nbf" claim. 378 | iat: 379 | type: integer 380 | format: unix-time 381 | description: >- 382 | The "iat" (issued at) claim identifies the time at which the JWT was 383 | issued. This claim can be used to determine the age of the JWT. 384 | jti: 385 | type: string 386 | format: uuid 387 | description: >- 388 | The "jti" (JWT ID) claim provides a unique identifier for the JWT. 389 | For this server, this is satisfied by the use of a UUID. 390 | scope: 391 | description: | 392 | The granted scope(s), a list of space-delimited, case-sensitive names. 393 | type: string 394 | example: "utm.strategic_coordination utm.constraint_processing" 395 | aud: 396 | description: | 397 | The "aud" (audience) claim identifies the recipients that the JWT is 398 | intended for. Each server intended to process the JWT MUST 399 | identify itself with a value in the audience claim. If the server 400 | processing the claim does not identify itself with a value in the 401 | "aud" claim when this claim is present, then the JWT MUST be 402 | rejected. "aud" will contain exactly one identifier of 403 | the intended recipient system. 404 | type: string 405 | format: hostname 406 | example: "npsu1.arc.nasa.gov" 407 | authorities: 408 | description: An array of all authorities that the client is associated with. 409 | type: array 410 | items: 411 | type: string 412 | example: "ASTM_USS_BASIC" 413 | minItems: 1 414 | client_id: 415 | description: The client_id (uss_name) of the requesting USS. 416 | type: string 417 | example: "uss.example.xyz" 418 | Metadata: 419 | type: object 420 | description: Information provided at the `/.well-known/oauth-authorization-server` endpoint. 421 | required: 422 | - iss 423 | - token_endpoint 424 | - jwks_uri 425 | - scopes_supported 426 | - response_types_supported 427 | - grant_types_supported 428 | - token_endpoint_auth_methods_supported 429 | - token_endpoint_auth_signing_alg_values_supported 430 | - service_documentation 431 | - jwt_claims 432 | - signed_metadata 433 | additionalProperties: false 434 | properties: 435 | iss: 436 | type: string 437 | format: url 438 | description: >- 439 | The authorization server's issuer identifier, which is a URL that 440 | uses the "https" scheme and has no query or fragment components. 441 | This is the location where ".well-known" RFC 8615 resources 442 | containing information about the authorization server are 443 | published. Using these well-known resources is described in Section 444 | 3. The issuer identifier is used to prevent authorization server 445 | mix-up attacks, as described in "OAuth 2.0 Mix-Up Mitigation". 446 | token_endpoint: 447 | type: string 448 | format: url 449 | description: >- 450 | URL of the authorization server's token endpoint [RFC6749]. This is 451 | REQUIRED unless only the implicit grant type is used. 452 | jwks_uri: 453 | type: string 454 | format: uri 455 | description: | 456 | URL of the authorization server's JWK Set 457 | document. The referenced document contains the signing key(s) the 458 | client uses to validate signatures from the authorization server. 459 | This URL MUST use the "https" scheme. The JWK Set MAY also 460 | contain the server's encryption key or keys, which are used by 461 | clients to encrypt requests to the server. When both signing and 462 | encryption keys are made available, a "use" (public key use) 463 | parameter value is REQUIRED for all keys in the referenced JWK Set 464 | to indicate each key's intended usage. 465 | scopes_supported: 466 | type: array 467 | items: 468 | type: string 469 | description: >- 470 | JSON array containing a list of the OAuth 2.0 [RFC6749] "scope" 471 | values that this authorization server supports. Servers MAY choose 472 | not to advertise some supported scope values even when this 473 | parameter is used. 474 | response_types_supported: 475 | type: array 476 | items: 477 | type: string 478 | enum: [none] 479 | minItems: 0 480 | maxItems: 0 481 | description: >- 482 | JSON array containing a list of the OAuth 2.0 "response_type" values 483 | that this authorization server supports. These values are required 484 | for responses from calls to the authorization endpoint, thus this 485 | array may be empty if no grant flows use the authorization endpoint, 486 | thus this server returns an empty array. (definitions in RFC 7591) 487 | 488 | This field is required per RFC 8414, but this auth server does not 489 | support the flows that use this field, thus an empty array is returned. 490 | grant_types_supported: 491 | type: array 492 | items: 493 | type: string 494 | enum: [client_credentials] 495 | minItems: 1 496 | maxItems: 1 497 | description: >- 498 | JSON array containing a list of the OAuth 2.0 grant type values that 499 | this authorization server supports. (definitions in RFC 7591) 500 | token_endpoint_auth_methods_supported: 501 | type: array 502 | items: 503 | type: string 504 | enum: [private_key_jwt] 505 | minItems: 1 506 | maxItems: 1 507 | description: >- 508 | JSON array containing a list of client authentication methods 509 | supported by this token endpoint. Client authentication method 510 | values are used in the "token_endpoint_auth_method" parameter 511 | defined in Section 2 of [RFC7591]. If omitted, the default is 512 | "client_secret_basic" -- the HTTP Basic Authentication Scheme 513 | specified in Section 2.3.1 of OAuth 2.0 [RFC6749]. FIMS-Authz will 514 | only support private_key_jwt. 515 | token_endpoint_auth_signing_alg_values_supported: 516 | type: array 517 | items: 518 | type: string 519 | enum: [HS256, RS256, ES256] 520 | minItems: 3 521 | maxItems: 3 522 | uniqueItems: true 523 | description: |- 524 | JSON array containing a list of the JWS signing algorithms (alg 525 | values) supported by the token endpoint for the signature on the JWT 526 | [JWT] used to authenticate the client at the token endpoint for the 527 | `private_key_jwt` and `client_secret_jwt` authentication methods. 528 | Servers SHOULD support "RS256". The value "none" MUST NOT be used. 529 | 530 | See UFAA doc for details. 531 | service_documentation: 532 | type: string 533 | format: url 534 | description: >- 535 | URL of a page containing human-readable information that developers 536 | might want or need to know when using the authorization server. In 537 | particular, if the authorization server does not support Dynamic 538 | Client Registration, then information on how to register clients 539 | needs to be provided in this documentation. 540 | jwt_claims: 541 | $ref: "#/components/schemas/JwtClaimsSet" 542 | signed_metadata: 543 | type: string 544 | format: JWT 545 | description: | 546 | A JWT containing metadata values about the authorization server as 547 | claims. This is a string value consisting of the entire signed 548 | JWT. A "signed_metadata" metadata value SHOULD NOT appear as a 549 | claim in the JWT. 550 | 551 | Refer to RFC8414 - https://tools.ietf.org/html/rfc8414#section-2.1 552 | HttpErrorResponse: 553 | type: object 554 | properties: 555 | error: 556 | type: string 557 | example: "Error Title" 558 | error_description: 559 | type: string 560 | example: "Human readable description of the error." 561 | JsonWebKeySet: 562 | type: "object" 563 | properties: 564 | keys: 565 | type: "array" 566 | items: 567 | $ref: "#/components/schemas/JsonWebKey" 568 | JsonWebKey: 569 | type: "object" 570 | description: >- 571 | This schema defines what a client may expect to receive when requesting a JWK/JWKS. 572 | 573 | NOTE: Not all fields defined in this schema may be returned when in operational use. 574 | required: 575 | - kty 576 | properties: 577 | kty: 578 | type: "string" 579 | use: 580 | type: "string" 581 | enum: 582 | - sig 583 | - enc 584 | kid: 585 | type: "string" 586 | alg: 587 | type: "string" 588 | crv: 589 | type: "string" 590 | x: 591 | type: "string" 592 | "y": 593 | type: "string" 594 | d: 595 | type: "string" 596 | "n": 597 | type: "string" 598 | e: 599 | type: "string" 600 | k: 601 | type: "string" 602 | -------------------------------------------------------------------------------- /fimsauthz-api/nup-oauth2.yaml: -------------------------------------------------------------------------------- 1 | openapi: 3.0.1 2 | info: 3 | title: NUP OAuth2 Authorization Service API Documentation 4 | description: | 5 | NUP OAuth2 Authorization Service 6 | version: 0.1.0 7 | servers: 8 | - url: https://future.url.uam/nup-oauth2/oauth 9 | 10 | paths: 11 | "/token/": 12 | post: 13 | tags: 14 | - A. Client Credentials Flow 15 | summary: Request for an access token with params in the HTTP body. 16 | description: | 17 | This endpoint is required as per RFC 6749. A POST to this endpoint acts as a request for an access token. 18 | requestBody: 19 | content: 20 | application/x-www-form-urlencoded: 21 | schema: 22 | required: 23 | - grant_type 24 | - scope 25 | type: object 26 | properties: 27 | grant_type: 28 | type: string 29 | description: Type of grant. Must be 'client_credentials'. 30 | enum: 31 | - client_credentials 32 | scope: 33 | type: string 34 | description: 35 | Scope (one and only one) to be associated with the 36 | access token being requested. An error code of 400 will be returned 37 | if no scope, incorrect scope or more than one scope is specified. 38 | enum: 39 | - scope 40 | required: true 41 | responses: 42 | "200": 43 | description: OK 44 | content: 45 | application/json: 46 | schema: 47 | $ref: "#/components/schemas/TokenResponse" 48 | "400": 49 | description: >- 50 | - Request did not conform to the API specification or failed validation. 51 | content: 52 | application/json: 53 | schema: 54 | $ref: "#/components/schemas/ErrorResponse" 55 | "401": 56 | description: >- 57 | - Request used invalid or incorrect credentials. 58 | content: 59 | application/json: 60 | schema: 61 | $ref: "#/components/schemas/ErrorResponse" 62 | "429": 63 | description: >- 64 | - [NOT IMPLEMENTED] Client has been timed-out for making too many requests. 65 | content: 66 | application/json: 67 | schema: 68 | $ref: "#/components/schemas/ErrorResponse" 69 | security: 70 | - authenticate_using_client_credentials: [] 71 | 72 | "/token": 73 | post: 74 | tags: 75 | - A. Client Credentials Flow 76 | summary: Request for an access token with params in the HTTP URI as query params. 77 | description: | 78 | This endpoint is required as per RFC 6749. A POST to this endpoint acts as a request for an access token. 79 | parameters: 80 | - in: query 81 | name: grant_type 82 | required: true 83 | schema: 84 | type: string 85 | enum: 86 | - client_credentials 87 | description: Type of grant. Must be 'client_credentials'. 88 | - in: query 89 | name: scope 90 | required: true 91 | schema: 92 | type: string 93 | description: >- 94 | Scope (one and only one) to be associated with the access token 95 | being requested. An error code of 400 will be returned if no scope, 96 | incorrect scope or more than one scope is specified. 97 | responses: 98 | "200": 99 | description: OK 100 | content: 101 | application/json: 102 | schema: 103 | $ref: "#/components/schemas/TokenResponse" 104 | "400": 105 | description: >- 106 | - Request did not conform to the API specification or failed validation. 107 | content: 108 | application/json: 109 | schema: 110 | $ref: "#/components/schemas/ErrorResponse" 111 | "401": 112 | description: >- 113 | - Request used invalid or incorrect credentials. 114 | content: 115 | application/json: 116 | schema: 117 | $ref: "#/components/schemas/ErrorResponse" 118 | "429": 119 | description: >- 120 | - [NOT IMPLEMENTED] Client has been timed-out for making too many requests. 121 | content: 122 | application/json: 123 | schema: 124 | $ref: "#/components/schemas/ErrorResponse" 125 | security: 126 | - authenticate_using_client_credentials: [] 127 | 128 | 129 | "/token/ ": 130 | post: 131 | tags: 132 | - B. Password Credentials Flow 133 | summary: Request for an access token with params in the HTTP body. 134 | description: | 135 | A POST to this endpoint acts as a request for an access token. 136 | requestBody: 137 | content: 138 | application/x-www-form-urlencoded: 139 | schema: 140 | required: 141 | - grant_type 142 | - username 143 | - password 144 | type: object 145 | properties: 146 | grant_type: 147 | type: string 148 | description: Type of grant. Must be 'password'. 149 | enum: 150 | - password 151 | scope: 152 | type: string 153 | description: 154 | Scope (one and only one) to be associated with the 155 | access token being requested. An error code of 400 will be returned 156 | if no scope, incorrect scope or more than one scope is specified. 157 | enum: 158 | - scope 159 | username: 160 | type: string 161 | description: The user’s username for the 'password' grant type. 162 | password: 163 | type: string 164 | description: The user’s password for the 'password' grant type. 165 | required: true 166 | responses: 167 | "200": 168 | description: OK 169 | content: 170 | application/json: 171 | schema: 172 | $ref: "#/components/schemas/TokenResponse" 173 | "400": 174 | description: >- 175 | - Request did not conform to the API specification or failed validation. 176 | content: 177 | application/json: 178 | schema: 179 | $ref: "#/components/schemas/ErrorResponse" 180 | "401": 181 | description: >- 182 | - Request used invalid or incorrect credentials. 183 | content: 184 | application/json: 185 | schema: 186 | $ref: "#/components/schemas/ErrorResponse" 187 | "429": 188 | description: >- 189 | - [NOT IMPLEMENTED] Client has been timed-out for making too many requests. 190 | content: 191 | application/json: 192 | schema: 193 | $ref: "#/components/schemas/ErrorResponse" 194 | security: 195 | - authenticate_using_client_credentials: [] 196 | 197 | "/token ": 198 | post: 199 | tags: 200 | - B. Password Credentials Flow 201 | summary: Request for an access token with params in the HTTP URI as query params. 202 | description: | 203 | A POST to this endpoint acts as a request for an access token. 204 | parameters: 205 | - in: query 206 | name: grant_type 207 | required: true 208 | schema: 209 | type: string 210 | enum: 211 | - password 212 | description: Type of grant. Must be 'password'. 213 | - in: query 214 | name: scope 215 | schema: 216 | type: string 217 | description: >- 218 | Scope (one and only one) to be associated with the access token 219 | being requested. An error code of 400 will be returned if no scope, 220 | incorrect scope or more than one scope is specified. 221 | requestBody: 222 | content: 223 | application/x-www-form-urlencoded: 224 | schema: 225 | required: 226 | - username 227 | - password 228 | type: object 229 | properties: 230 | username: 231 | type: string 232 | description: The user’s username for the 'password' grant type. 233 | password: 234 | type: string 235 | description: The user’s password for the 'password' grant type. 236 | required: true 237 | responses: 238 | "200": 239 | description: OK 240 | content: 241 | application/json: 242 | schema: 243 | $ref: "#/components/schemas/TokenResponse" 244 | "400": 245 | description: >- 246 | - Request did not conform to the API specification or failed validation. 247 | content: 248 | application/json: 249 | schema: 250 | $ref: "#/components/schemas/ErrorResponse" 251 | "401": 252 | description: >- 253 | - Request used invalid or incorrect credentials. 254 | content: 255 | application/json: 256 | schema: 257 | $ref: "#/components/schemas/ErrorResponse" 258 | "429": 259 | description: >- 260 | - [NOT IMPLEMENTED] Client has been timed-out for making too many requests. 261 | content: 262 | application/json: 263 | schema: 264 | $ref: "#/components/schemas/ErrorResponse" 265 | security: 266 | - authenticate_using_client_credentials: [] 267 | 268 | 269 | /api: 270 | get: 271 | tags: 272 | - C. Version and Health 273 | summary: get server info. Can be used to check health. 274 | responses: 275 | 200: 276 | description: OK 277 | content: 278 | application/json: 279 | schema: 280 | $ref: "#/components/schemas/Version" 281 | components: 282 | schemas: 283 | TokenResponse: 284 | type: object 285 | properties: 286 | access_token: 287 | type: string 288 | description: see definitions/JwsCompactSerialization in this spec 289 | format: JwsCompactSerialization 290 | scope: 291 | type: string 292 | description: white space separated list of scopes 293 | token_type: 294 | type: string 295 | enum: 296 | - bearer 297 | expires_in: 298 | type: number 299 | description: see definitions/JwtClaimsSet.exp property in this spec 300 | format: integer 301 | sub: 302 | type: string 303 | description: see definitions/JwtClaimsSet in this spec 304 | jti: 305 | type: string 306 | description: see definitions/JwtClaimsSet in this spec 307 | format: uuid 308 | iss: 309 | type: string 310 | description: see definitions/JwtClaimsSet in this spec 311 | nbf: 312 | type: number 313 | description: see definitions/JwtClaimsSet in this spec 314 | example: 315 | access_token: tokenstring 316 | token_type: bearer 317 | expires_in: 3599 318 | scope: utm.nasa.gov_write.operation 319 | sub: nuss1.testing.nasa.gov 320 | nbf: 1509470774 321 | iss: fims.arc.nasa.gov/fimsAuthServer 322 | jti: 4d4c1a63-0959-48cc-885a-3648fd582db7 323 | JwtClaimsSet: 324 | type: object 325 | properties: 326 | iss: 327 | type: string 328 | description: 329 | The "iss" (issuer) claim identifies the principal that issued 330 | the JWT. The URL of the FIMS Authorization Server. 331 | format: URL 332 | sub: 333 | type: string 334 | description: 335 | The "sub" (suv4-draft identifies the principal that is the 336 | subject of the JWT. 337 | exp: 338 | type: integer 339 | description: 340 | The "exp" (expiration time) claim identifies the expiration 341 | time on or after which the JWT MUST NOT be accepted for processing. The 342 | processing of the "exp" claim requires that the current date/time MUST 343 | be before the expiration date/time listed in the "exp" claim. 344 | format: unix-time 345 | nbf: 346 | type: integer 347 | description: 348 | The "nbf" (not before) claim identifies the time before which 349 | the JWT MUST NOT be accepted for processing. The processing of the "nbf" 350 | claim requires that the current date/time MUST be after or equal to the 351 | not-before date/time listed in the "nbf" claim. 352 | format: unix-time 353 | iat: 354 | type: integer 355 | description: 356 | The "iat" (issued at) claim identifies the time at which the 357 | JWT was issued. This claim can be used to determine the age of the JWT. 358 | format: unix-time 359 | jti: 360 | type: string 361 | description: 362 | The "jti" (JWT ID) claim provides a unique identifier for the 363 | JWT. For this server, this is satisfied by the use of a UUID. 364 | format: uuid 365 | scope: 366 | type: object 367 | description: See securityDefinitions section in this spec. 368 | Version: 369 | type: object 370 | properties: 371 | title: 372 | type: string 373 | description: Title of the API 374 | version: 375 | type: string 376 | description: Version number for the API 377 | build_time: 378 | type: string 379 | description: Time of the latest build 380 | format: date-time 381 | example: 2015-08-20T14:11:56.118Z 382 | x-utm-data-accessibility: PUBLIC 383 | api_docs: 384 | type: array 385 | description: URL(s) for API Documentation 386 | items: 387 | type: string 388 | ErrorResponse: 389 | type: object 390 | properties: 391 | error: 392 | type: string 393 | example: "Error Title" 394 | error_description: 395 | type: string 396 | example: "Human readable description of the error." 397 | securitySchemes: 398 | application: 399 | type: oauth2 400 | description: A write scope allows reading. 401 | flows: 402 | clientCredentials: 403 | tokenUrl: https://utm.defined.host/oauth/token 404 | scopes: 405 | utm.nasa.gov_read.fimsadmin: Subject can read data internal to FIMS. 406 | utm.nasa.gov_write.fimsadmin: 407 | Subject can read, create, and update data 408 | internal to FIMS. 409 | utm.nasa.gov_read.operation: 410 | Subject can read operational data such as 411 | USS Instance data 412 | utm.nasa.gov_write.operation: 413 | Subject can read, create, and update operational 414 | data such as USS Instance data 415 | utm.nasa.gov_read.message: 416 | Subject can read message data such as UTM Message 417 | and Negotiations 418 | utm.nasa.gov_write.message: 419 | Subject can read, create, and update message 420 | data such as UTM Message and Negotiations 421 | utm.nasa.gov_read.publicsafety: 422 | Subject can read operations that are designated 423 | public safety operations. 424 | utm.nasa.gov_write.publicsafety: 425 | Subject can read, create, and update 426 | operations that are designated public safety operations. 427 | utm.nasa.gov_read.constraint: Subject can read UTM constraint data 428 | utm.nasa.gov_write.constraint: 429 | Subject can read, create, and update UTM 430 | constraint data. This means that the Subject can define areas that restrict 431 | other operations. 432 | utm.nasa.gov_read.conflictmanagement: 433 | Subject can read conflict management 434 | data. 435 | utm.nasa.gov_write.conflictmanagement: 436 | Subject can read and write conflict 437 | management data. 438 | authenticate_using_client_credentials: 439 | type: http 440 | description: | 441 | The FIMS AZ server authenticates clients using the HTTP Authorization header with the Basic keyword and the oauth2 client secret. Note that the FIMS Authorization Server facilitates the RFC-6749 Client Credentials flow for UTM components that are Oauth2 Resources servers. 442 | scheme: basic 443 | -------------------------------------------------------------------------------- /fimsauthz-api/nup-roles.yaml: -------------------------------------------------------------------------------- 1 | # NUP Roles for FIMS-AZ 2 | 3 | UTM_AUTHORITY: 4 | description: | 5 | A small set of trusted users who manage identities of all core UTM 6 | components such as USSs. 7 | authority: ANSP 8 | examples: 9 | - "UTM Authority vets USS1's additional capability for Public Service, and adds the CONSTRAINT_MANAGER role to USS1 in the master list." 10 | - "UTM Authority vets USS1, then adds an entry to master USS list and assigns the USS_BASIC role." 11 | 12 | USS_BASIC: 13 | description: | 14 | A USS. The UTM Authority assigns role after out-of-band vetting. 15 | Vetting includes some testing mechanism and liability assumptions TBD. 16 | 17 | According to the ASTM Spec - 1.0 18 | - Client may perform actions encompassed by the strategic coordination role including strategic conflict detection. 19 | - Client may read constraint references from the DSS and details from the partner USSs according to the constraint processing role. 20 | - Client may perform actions encompassed by the conformance monitoring for situational awareness role. 21 | 22 | authority: UTM_AUTHORITY 23 | examples: 24 | - "USS queries Discovery service to discover other USSs in its 4D area." 25 | scopes: 26 | - utm.strategic_coordination 27 | - utm.constraint_processing 28 | - utm.conformance_monitoring_sa 29 | 30 | CONSTRAINT_MANAGER: 31 | description: | 32 | This role can publish airspace constraints. 33 | The UTM Authority assigns this role after out-of-band 34 | vetting, which includes some testing mechanism and liability 35 | assumptions TBD. 36 | 37 | According to the ASTM Spec - 1.0 38 | - Client may manage (create, edit, and delete) constraints. 39 | 40 | authority: UTM_AUTHORITY 41 | examples: 42 | - "A Public Safety USS, acting on behalf of the ANSP, adds an ASTM Contraint to the UTM Network." 43 | scopes: 44 | - utm.constraint_management 45 | 46 | AVAILABILITY_MANAGER: 47 | description: | 48 | An user with this role can set the availability state of USSs in the DSS. 49 | The UTM Authority assigns this role after out-of-band 50 | vetting, which includes some testing mechanism and liability 51 | assumptions TBD. 52 | 53 | According to the ASTM Spec - 1.0 54 | - Client may set the availability state of USSs in the DSS. 55 | 56 | authority: UTM_AUTHORITY 57 | examples: 58 | - "A Public Safety USS, acting on behalf of the ANSP, sets an USS availability status to be DOWN to the UTM Network." 59 | scopes: 60 | - utm.availability_arbitration 61 | -------------------------------------------------------------------------------- /fimsauthz-api/pseudo-client.md: -------------------------------------------------------------------------------- 1 | # Pseudo-Implementation for interfacing with FIMS-AZ 2 | 3 | ## Disclaimer 4 | The following Python 3 snippet describes a possible implementation that a client of FIMS-AZ may reference to interface with FIMS-AZ to request a Bearer token. 5 | 6 | __This is intended as an example only and not as an executable code segment.__ 7 | 8 | References: [UAS Service Supplier Framework for Authentication and Authorization](https://utm.arc.nasa.gov/docs/2019-UTM_Framework-NASA-TM220364.pdf) 9 | Author: NASA Ames Research Center, Aviation Systems Division 10 | 11 | ```python 12 | from jwcrypto import jwk, jws # https://pypi.org/project/jwcrypto/ 13 | from jwcrypto.common import json_encode, json_decode 14 | import requests # https://pypi.org/project/requests/ 15 | import json 16 | 17 | priv_key_path = "../path/to/my/priv_key.pem" 18 | alg = "RS256" 19 | 20 | # Read the private key file 21 | with open(priv_key_path, "rb") as f: 22 | priv_key_file = f.read() 23 | 24 | # Cast the private key file to a JWK 25 | priv_key = jwk.JWK.from_pem(priv_key_file) 26 | 27 | # Define the JOSE Header 28 | jose_header = { 29 | "typ": "JOSE", 30 | "kid": "my_kid_here", 31 | "x5u": "https://example.com/.well-known/uas-traffic-management/public.der", 32 | "alg": alg, 33 | } 34 | 35 | # Define the Payload of the JWS - 36 | # - As defined by UFAA, the payload must be equal to the HTTP body. The request body / JWS payload must be URL encoded. 37 | # - current_timestamp must adhere to the timestamp model described as per - https://github.com/nasa/utm-apis/blob/master/utm-domains/utm-domain-commons.yaml#L45 38 | payload = "grant_type=client_credentials&client_id=example.com&scope=example.scope.read&audience=the-dss.co¤t_timestamp=2020-06-19T13%3A37%3A52.562Z" 39 | 40 | # Generate the JWS 41 | my_jws = jws.JWS(payload) 42 | 43 | # Sign the JWS with the private key 44 | my_jws.add_signature(priv_key, alg, json_encode(jose_header)) 45 | 46 | # Decode the signed JWS into a JSON 47 | signed_jws = my_jws.serialize() 48 | signed_jws_json = json_decode(signed_jws) 49 | 50 | # Create the x-utm-message-signature by eliminating the payload element of the signed JWS 51 | x_utm_message_signature = ( 52 | signed_jws_json["protected"] + ".." + signed_jws_json["signature"] 53 | ) 54 | 55 | # Define the required HTTP Request headers 56 | headers = { 57 | "content-type": "application/x-www-form-urlencoded", 58 | "x-utm-message-signature": x_utm_message_signature, 59 | "User-Agent": "AZ_EXAMPLE_CLIENT", 60 | } 61 | 62 | # Send request FIMS-AZ 63 | r = requests.post( 64 | url="https://example.com/fims/v1/token/", 65 | data=payload, # As defined by UFAA, the payload must be equal to the HTTP body 66 | headers=headers, 67 | ) 68 | ``` -------------------------------------------------------------------------------- /nuss-operator-api/README.md: -------------------------------------------------------------------------------- 1 | # NUSS-Operator Interface 2 | 3 | The NUSS-Operator interface is defined by this README and theses OpenAPI specs. V2.1 OpenAPI spec is based on V2.1 data models and is defined in !["swagger.yaml"](swagger.yaml "v2.1"). 4 | 5 | 6 | ## Conformance Monitoring 7 | If an active operation violates its conformance geography, that operation is transitioned to the nonconforming state, and it could eventually be transitioned to 8 | the rogue state. 9 | 10 | NUSS defines additional regions around the flight volumes called conformance and protected volumes. The protected volume is used to strategically deconflict operations from each other as well as from airspace constraints. 11 | 12 | Since the USS-API OperationVolume model defines validation requirements, the converted model needs to be validated before the first USS-API data exchange. 13 | 14 | ![alt text](images/conformance-regions.png "geometries") 15 | 16 | **Figure 1: Volumes of Flight, Conformance and Protected** 17 | 18 | --- 19 | 20 | 21 | ### Conformance Monitoring 22 | 23 | When Operator submits submits an intention to fly to NUSS, NUSS defines that region as the Flight Geography. NUSS expands that region into conformance and protected regions and maps the Operator geography into the UTM Commons geography. 24 | 25 | The UTM Commons Operation Volume is used for Strategic Deconfliction. The conversions from NUSS's Operator API's OperationVolume to UTM Commons Operation Volume is shown in Table 2. 26 | 27 | --- 28 | utm-commons | Operator Volume 29 | ------------ | ------------- 30 | Operation Volume | Protected Volume 31 | not specified | Conformance Volume 32 | not specified | Flight Volume 33 | 34 | **Table 2: Mapping from Operator OperationVolume to UTM Commons** 35 | 36 | --- 37 | 38 | Figure 2 lists default values for NUSS's conformance parameters. Theses defaults are bound at launch time. Additionally NUSS can bind conformance parameters at runtime; for example, conformance properties may be informed by an SDSP based on weather or surveillance findings. 39 | 40 | The update rate for position reports is at least 1 Hz to no more than 5 Hz. In the case that there are too few reports per second, the UTM System will transition the operation to the NONCONFORMING state and notify the UAS Operator. 41 | 42 | The conformance expand the operator's geography to a 4d conformance volume. A position within this region will trigger an Active to Non-Conformant state change. Similarly the protected values expand the conformance geography to define the Operation Volume. If an operation breaches its assigned protected geography, it will immediately be transitioned to the ROGUE state. 43 | 44 | minimum.altitude.feet is global to NUSS to define the a total minimum. 45 | 46 | reportingFrequency.minimum.hz specifies the max interval between position reports. This interval will trigger Active to Non-conforming, and eventually to Rogue. 47 | 48 | --- 49 | 50 | 51 | reportingFrequency.minimum.hz:0.33 52 | minimum.altitude.feet:-250 53 | conformance.lateral.feet:30 54 | conformance.altitude.feet:20 55 | conformance.time.ms:60000 56 | protected.lateral.feet:60 57 | protected.altitude.feet:20 58 | protected.time.ms:60000 59 | 60 | **Figure 2: Default Conformance Values** 61 | 62 | 63 | ## Operator Operation States 64 | 65 | Operator-API Operation States are shown in Figure 1. Note that Non-conforming to Closed is a valid state transition but is not captured this diagram. 66 | 67 | 68 | ![alt text](images/state-v2-1.png "TCL4 FSM") 69 | 70 | **Figure 4: Operator-API Operation States** 71 | 72 | 73 | Abbreviation | State 74 | ------------ | ------------- 75 | P | PROPOSED 76 | A | ACCEPTED 77 | R | REJECTED - terminal 78 | C | CLOSED - terminal 79 | X | CANCELED - terminal 80 | I | READIED 81 | E | EXPIRED - terminal 82 | G | ROGUECLOSED - terminal 83 | B | ABORTCLOSED - terminal 84 | U | ROGUE 85 | T | ABORTING 86 | F | NON-CONFORMING 87 | V | ACTIVE 88 | 89 | **Table 2: Operator-API Operation State Abbreviations** 90 | -------------------------------------------------------------------------------- /nuss-operator-api/images/conformance-regions.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/nuss-operator-api/images/conformance-regions.png -------------------------------------------------------------------------------- /nuss-operator-api/images/state-v2-1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/nuss-operator-api/images/state-v2-1.png -------------------------------------------------------------------------------- /nuss-operator-api/images/v4-states.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/nuss-operator-api/images/v4-states.png -------------------------------------------------------------------------------- /oper-api/README.md: -------------------------------------------------------------------------------- 1 | # Operator API for NUP 2 | -------------------------------------------------------------------------------- /oper-api/nup-operator-roles.yaml: -------------------------------------------------------------------------------- 1 | # Operator roles supporting privileges for USS and PSU Operator Services as well as 2 | # Federal use cases such as a federal-logical USS sub-network. 3 | 4 | UAM_OPERATOR: 5 | description: | 6 | todo analog to UTM_OPERATOR 7 | 8 | UAM_FEDERAL_OPERATOR: 9 | description: | 10 | todo analog to UTM_FEDERAL_OPERATOR 11 | 12 | UTM_FEDERAL_OPERATOR: 13 | description: | 14 | An actor with this role can use a USS to create and modify 15 | Operations, Positions and Messages in the federal UTM subnet. 16 | authority: ANSP 17 | examples: 18 | - "An actor with the UTM_FEDERAL_OPERATOR role can manage Operations in the federal subnet" 19 | scopes: 20 | - nup.federal_write.operation #all operational data (op, msg, posn) 21 | 22 | UTM_OPERATOR: 23 | description: | 24 | An actor with this role can use a USS to create and modify 25 | Operations, Positions and Messages, read UVRs and other basic fuctions. 26 | authority: UTM Service Provider 27 | examples: 28 | - "An actor with the UTM_OPERATOR read active UASVolumeReservations in the USS Network." 29 | scopes: 30 | - nup_write.operation 31 | - nup_read.uvr 32 | 33 | CONSTRAINT_MANAGER: 34 | description: | 35 | An actor with this role can author and submit airspace constraints such as UASVolumeReservations (UVRs). 36 | The authority assigns this role after out-of-band 37 | vetting TBD. 38 | authority: ANSP 39 | examples: 40 | - "An actor with CONSTRAINT_MANAGER role and can publish airspace constraints such as UASVolumeReservations to the USS Network." 41 | scopes: 42 | - nup_write.constraint 43 | -------------------------------------------------------------------------------- /oper-api/user-to-roles.yaml: -------------------------------------------------------------------------------- 1 | # injected into Operator Service at build time. 2 | - user: 3 | id: johnhop1 4 | secret: 34jid33zj4Mj1byFh1v2g0 5 | roles: 6 | - UTM_OPERATOR 7 | deployment: 8 | - production 9 | - user: 10 | id: federal1 11 | secret: 3jid33zj9Mj1byFh1v2g0 12 | roles: 13 | - UAM_FEDERAL_OPERATOR 14 | - CONSTRAINT_MANAGER 15 | deployment: 16 | - production 17 | 18 | - user: 19 | id: devtest_basic 20 | secret: Mj1byFh1v2g0Mj1byFh1v2g0 21 | roles: 22 | - UTM_OPERATOR 23 | - UAM_OPERATOR 24 | deployment: 25 | - devtest 26 | - user: 27 | id: devtest_ep 28 | secret: xh1v2g0h1v2g0h1v2g0 29 | roles: 30 | - UTM_OPERATOR 31 | - UAM_OPERATOR 32 | - CONSTRAINT_MANAGER 33 | deployment: 34 | - devtest 35 | -------------------------------------------------------------------------------- /public-safety-uss/README.md: -------------------------------------------------------------------------------- 1 | ### Public Saftey - a USS Role 2 | ![alt text](https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/public-safety-uss/images/vehid.png "Logo Title") 3 | -------------------------------------------------------------------------------- /public-safety-uss/images/vehid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/nasa/utm-apis/3e959c2302c5b756e87ea5397d613b3e32247584/public-safety-uss/images/vehid.png -------------------------------------------------------------------------------- /public-safety-uss/swagger.yaml: -------------------------------------------------------------------------------- 1 | swagger: '2.0' 2 | info: 3 | version: 'v4' 4 | title: Public Safety USS 5 | description: A USS with the Public Safety role implements this API in addition to the base USS API. 6 | contact: 7 | name: 'NASA Ames Research Center, Aviation Systems Division' 8 | url: 'https://utm.arc.nasa.gov/' 9 | email: joseph.rios@nasa.gov 10 | license: 11 | name: NASA Open Source Agreement 12 | url: 'https://ti.arc.nasa.gov/opensource/nosa/' 13 | termsOfService: > 14 | 15 | A. No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY 16 | WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, 17 | BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO 18 | SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 19 | PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE 20 | SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF 21 | PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN 22 | ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR 23 | RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR 24 | ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, 25 | GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING 26 | THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES 27 | IT "AS IS." 28 | 29 | B. Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS 30 | AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS 31 | WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT''S USE OF THE SUBJECT SOFTWARE 32 | RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING 33 | FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING 34 | FROM, RECIPIENT''S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY 35 | AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND 36 | SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY 37 | LAW. RECIPIENT''S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, 38 | UNILATERAL TERMINATION OF THIS AGREEMENT. 39 | 40 | host: uss.defined.url 41 | basePath: / 42 | schemes: 43 | - https 44 | 45 | securityDefinitions: 46 | basicAuth: 47 | type: basic 48 | security: 49 | - basicAuth: [] 50 | 51 | paths: 52 | /uas/{uvin}: 53 | get: 54 | description: Returns information on vehicle with the given uvin. 55 | parameters: 56 | - in: path 57 | name: "uvin" 58 | type: "string" 59 | required: true 60 | description: "specifies the vehicle id" 61 | - name: "lat" 62 | in: "query" 63 | description: "Latitude of point for Geographic search. Approximate position of the vehicle." 64 | required: true 65 | maximum: 90.0 66 | minimum: -90.0 67 | type: "number" 68 | format: "double" 69 | - name: "lon" 70 | in: "query" 71 | description: "Longitude of point for Geographic search. Approximate position of the vehicle." 72 | required: true 73 | type: "number" 74 | maximum: 180.0 75 | minimum: -180.0 76 | format: "double" 77 | 78 | responses: 79 | 200: 80 | description: "Successfully returned uvin and its associated operator information" 81 | schema: 82 | $ref: >- 83 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/VehicleOperationData 84 | 401: 85 | description: "Unauthorized" 86 | schema: 87 | $ref: >- 88 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 89 | 403: 90 | description: "Forbidden" 91 | 404: 92 | description: "Not Found" 93 | 94 | 400: 95 | description: "Bad request. Typically validation error. Fix your request\ 96 | \ and retry." 97 | 503: 98 | description: Service Unavailable 99 | schema: 100 | $ref: >- 101 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 102 | /uas: 103 | get: 104 | description: Returns vehicle information when a partial uvin or an faa_number is supplied. Atleast one parameter is required. 105 | parameters: 106 | - name: "partial_uvin" 107 | in: "query" 108 | description: "Part of the uvin uuid." 109 | maximum: 36.0 110 | minimum: 6 111 | type: "string" 112 | - name: "faa_number" 113 | in: "query" 114 | description: "Full faa_number." 115 | maximum: 10.0 116 | minimum: 6 117 | type: "string" 118 | - name: "lat" 119 | in: "query" 120 | description: "Latitude of point for Geographic search. Approximate position of the vehicle." 121 | maximum: 90.0 122 | minimum: -90.0 123 | type: "number" 124 | format: "double" 125 | - name: "lon" 126 | in: "query" 127 | description: "Longitude of point for Geographic search. Approximate position of the vehicle." 128 | type: "number" 129 | maximum: 180.0 130 | minimum: -180.0 131 | format: "double" 132 | responses: 133 | 200: 134 | description: "Successfully returns matched uvins and its associated operator information" 135 | schema: 136 | type: "array" 137 | items: 138 | $ref: >- 139 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/VehicleOperationData 140 | 141 | 401: 142 | description: "Unauthorized" 143 | schema: 144 | $ref: >- 145 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 146 | 403: 147 | description: "Forbidden" 148 | 404: 149 | description: "Not Found" 150 | 151 | 400: 152 | description: "Bad request. Typically validation error. Fix your request\ 153 | \ and retry." 154 | 503: 155 | description: Service Unavailable 156 | schema: 157 | $ref: >- 158 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 159 | 160 | /uas/operations: 161 | get: 162 | description: Returns all operations around the point of reference 163 | parameters: 164 | - name: distance 165 | in: query 166 | description: >- 167 | Distance from reference_point to find operations. Ignored if 168 | reference_point is not provided. Units are feet. Returns all 169 | operations that have any operation_volumes that interesect the 2D 170 | circle defined by distance and reference_point. Default value only 171 | has meaning when reference_point parameter is provided. 172 | type: integer 173 | format: int32 174 | maximum: 60762 175 | minimum: 1 176 | default: 300 177 | required: false 178 | - name: reference_point 179 | in: query 180 | description: >- 181 | A single point used to find all operations within some distance from 182 | that point. Returns all operations that have any operation_volumes 183 | that interesect the 2D circle defined by distance and 184 | reference_point. When distance it excluded and reference_point is 185 | included, use default value (300ft) for distance. 186 | 187 | Described as a GeoJSON position. The value is equivalent to what 188 | would be seen in the "coordinates" field for a GeoJSON Point 189 | object. See https://tools.ietf.org/html/rfc7946#section-3.1.1 for 190 | further reference. Example would be reference_point=[-122.056364, 191 | 37.414371] (URL safe: 192 | reference_point%3D%5B-122.056364%2C%2037.414371%5D). As per GeoJSON 193 | spec, this is long-lat format in the WGS84 reference system. 194 | 195 | MUST NOT include a third coordinate element, strictly 2D. 196 | type: string 197 | format: geojson-position 198 | maxLength: 100 199 | required: false 200 | - name: "time" 201 | in: "query" 202 | required: true 203 | description: "Known operations in this area as of this time" 204 | type: "string" 205 | format: "date-time" 206 | minLength: 20 207 | maxLength: 25 208 | 209 | responses: 210 | 200: 211 | description: "Returns all operations within the specified geography" 212 | schema: 213 | type: "array" 214 | items: 215 | $ref: >- 216 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Operation 217 | 401: 218 | description: "Unauthorized" 219 | schema: 220 | $ref: >- 221 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 222 | 403: 223 | description: "Forbidden" 224 | 404: 225 | description: "Not Found" 226 | 400: 227 | description: "Bad request. Typically validation error. Fix your request\ 228 | and retry." 229 | /restrictions: 230 | get: 231 | description: >- 232 | Get constraint messages. 233 | parameters: 234 | - name: limit 235 | in: query 236 | description: The maximum number or records to return. 237 | required: false 238 | type: integer 239 | default: 10 240 | maximum: 100 241 | exclusiveMaximum: false 242 | minimum: 1 243 | exclusiveMinimum: false 244 | format: int32 245 | - name: offset 246 | in: query 247 | description: The index from which to begin the list of returned records. 248 | required: false 249 | type: integer 250 | default: 0 251 | minimum: 0 252 | exclusiveMinimum: false 253 | format: int32 254 | - name: distance 255 | in: query 256 | description: >- 257 | Distance from reference_point to find restrictions. Ignored if 258 | reference_point is not provided. Units are feet. Returns all 259 | restrictions that have any geography values that interesect the 2D 260 | circle defined by distance and reference_point. Default value only 261 | has meaning when reference_point parameter is provided. 262 | type: integer 263 | format: int32 264 | maximum: 60762 265 | minimum: 1 266 | default: 300 267 | required: false 268 | - name: reference_point 269 | in: query 270 | description: >- 271 | A single point used to find all restrictions within some distance from 272 | that point. Returns all 273 | restrictions that have any geography values that interesect the 2D 274 | circle defined by distance and reference_point. 275 | When distance it excluded and reference_point is 276 | included, use default value (300ft) for distance. 277 | 278 | Described as a GeoJSON position. The value is equivalent to what 279 | would be seen in the "coordinates" field for a GeoJSON Point 280 | object. See https://tools.ietf.org/html/rfc7946#section-3.1.1 for 281 | further reference. Example would be reference_point=[-122.056364, 282 | 37.414371] (URL safe: 283 | reference_point%3D%5B-122.056364%2C%2037.414371%5D). As per GeoJSON 284 | spec, this is long-lat format in the WGS84 reference system. 285 | 286 | MUST NOT include a third coordinate element, strictly 2D. 287 | type: string 288 | format: geojson-position 289 | maxLength: 100 290 | required: false 291 | responses: 292 | '200': 293 | description: Successful request. 294 | schema: 295 | type: array 296 | items: 297 | $ref: >- 298 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UASVolumeReservation 299 | '401': 300 | description: "Unauthorized" 301 | schema: 302 | $ref: >- 303 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 304 | '403': 305 | description: "Forbidden" 306 | '404': 307 | description: "Not Found" 308 | 309 | '400': 310 | description: "Bad request. Typically validation error. Fix your request\ 311 | \ and retry." 312 | /restrictions/{message_id}: 313 | get: 314 | description: >- 315 | Get a specific constraint message. 316 | parameters: 317 | - in: path 318 | name: message_id 319 | required: true 320 | type: string 321 | description: GET by message_id 322 | responses: 323 | '200': 324 | description: Successful request. 325 | schema: 326 | $ref: >- 327 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UASVolumeReservation 328 | '401': 329 | description: "Unauthorized" 330 | schema: 331 | $ref: >- 332 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 333 | '403': 334 | description: "Forbidden" 335 | '404': 336 | description: "Not Found" 337 | 338 | '400': 339 | description: "Bad request. Typically validation error. Fix your request\ 340 | \ and retry." 341 | put: 342 | description: >- 343 | Endpoint to PUT a constraint message that will be sent to LUN members 344 | intersecting the constraint geography. 345 | parameters: 346 | - in: path 347 | name: message_id 348 | required: true 349 | type: string 350 | description: PUT by message_id 351 | - in: body 352 | name: constraint_message 353 | description: The UASVolumeReservation being sent 354 | required: true 355 | schema: 356 | $ref: >- 357 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UASVolumeReservation 358 | responses: 359 | '204': 360 | description: Constraint data received. No content returned. 361 | '400': 362 | description: Bad request. Typically validation error. Fix your request and retry. 363 | schema: 364 | $ref: >- 365 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 366 | '401': 367 | description: Unauthorized. 368 | schema: 369 | $ref: >- 370 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 371 | '403': 372 | description: "Forbidden" 373 | '404': 374 | description: "Not Found" 375 | -------------------------------------------------------------------------------- /urep-api/README.md: -------------------------------------------------------------------------------- 1 | 2 | # UAS Report (UREP) 3 | UREP is similar in function to a Pilot Weather Report (PIREP) or Position Reports (AIREP) 4 | in the National Airspace System (NAS). UREPs are data that are provided to the UAS Traffic Management (UTM) System (see UTM description below) that can be shared with other stakeholders to provide better situational awareness. While a traditional PIREP is typically confined to weather phenomena, a UREP allows for reporting of weather phenomena as well as other observable airspace activity (i.e., other aviation operations that could affect UTM operations). 5 | Since the UTM System is highly automated, the submission and retrieval of UREPs is built to rely on automated processes. 6 | 7 | UREP data can be aggregated as used for forecasts. An example plat 8 | of existing PIREP data can be found on the internet; follows is an example. 9 | 10 | 11 | ![alt text][logo] 12 | 13 | [logo]: https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/urep-api/urep-plot.png "Logo Title Text 2" 14 | 15 | -------------------------------------------------------------------------------- /urep-api/swagger.yaml: -------------------------------------------------------------------------------- 1 | --- 2 | swagger: "2.0" 3 | info: 4 | description: "This service allows an unmanned aircraft system (UAS) Service Supplier\ 5 | \ (USS) to submit a UREP to the greater UAS Traffic Management (UTM) ecosystem.\ 6 | \ This also allows USS to share UREPs amongst eachother, allowing for greater\ 7 | \ operational awareness within the UTM ecosystem." 8 | version: "v1" 9 | title: "UAS Report (UREP) Service" 10 | host: sdsp.defined.url 11 | basePath: "/urep" 12 | tags: 13 | - name: "A. Required Endpoints" 14 | description: "An implementer of this SDSP implements these." 15 | - name: "B. Subscription Points" 16 | description: "Non-REST endpoints for asynchronous communications with UREP." 17 | schemes: 18 | - "https" 19 | 20 | paths: 21 | /ureps: 22 | get: 23 | tags: 24 | - "A. Required Endpoints" 25 | summary: "Get UREPs" 26 | operationId: "getUrepsUsingGET" 27 | consumes: 28 | - "application/json" 29 | produces: 30 | - "application/json" 31 | parameters: 32 | - name: "fields" 33 | in: "query" 34 | description: "A ',' delimited list of field names from the Urep object to\ 35 | \ include within the results. All other fields will be excluded. Fields\ 36 | \ must be valid field names from the Urep object. If not present all fields\ 37 | \ will be returned." 38 | required: false 39 | type: "array" 40 | items: 41 | type: "string" 42 | collectionFormat: "csv" 43 | - name: "sort" 44 | in: "query" 45 | description: "The parameter to sort by. Defaults to the time_measured if not\ 46 | \ present." 47 | required: false 48 | type: "string" 49 | - name: "sort_d" 50 | in: "query" 51 | description: "Direction of the sort, defaults to DESC if not present. Must\ 52 | \ be either ASC or DESC" 53 | required: false 54 | type: "string" 55 | enum: 56 | - "ASC" 57 | - "DESC" 58 | - name: "limit" 59 | in: "query" 60 | description: "Max number of Ureps to return" 61 | required: false 62 | type: "integer" 63 | default: 10 64 | maximum: 100 65 | minimum: 1 66 | format: "int32" 67 | - name: "offset" 68 | in: "query" 69 | description: "Offset number of records to return for pagination." 70 | required: false 71 | type: "integer" 72 | default: 0 73 | minimum: 0 74 | format: "int32" 75 | - name: "lat" 76 | in: "query" 77 | description: "Latitude of point for Geographic search. Must be present if\ 78 | \ lon or radius are present. If none of these fields are present, no geographic\ 79 | \ filtering will be performed." 80 | required: false 81 | type: "number" 82 | maximum: 90.0 83 | minimum: -90.0 84 | format: "double" 85 | - name: "lon" 86 | in: "query" 87 | description: "Longitude of point for Geographic search. Must be present if\ 88 | \ lat or radius are present. If none of these fields are present, no geographic\ 89 | \ filtering will be performed." 90 | required: false 91 | type: "number" 92 | maximum: 180.0 93 | minimum: -180.0 94 | format: "double" 95 | - name: "radius" 96 | in: "query" 97 | description: "Radius for Geographic search in nautical miles. Must be present\ 98 | \ if lat or lon are present. If none of these fields are present, no geographic\ 99 | \ filtering will be performed." 100 | required: false 101 | type: "number" 102 | minimum: 0 103 | format: "double" 104 | - name: "before" 105 | in: "query" 106 | description: "Upper bound for a time based query on time_measured. Defaults\ 107 | \ to the current time if not present." 108 | required: false 109 | type: "string" 110 | format: "date-time" 111 | - name: "after" 112 | in: "query" 113 | description: "Lower bound for a time based query on time_measured. Defaults\ 114 | \ to 24 hours prior to the current time if not present." 115 | required: false 116 | type: "string" 117 | format: "date-time" 118 | responses: 119 | 200: 120 | description: "OK" 121 | schema: 122 | type: "array" 123 | items: 124 | $ref: "#/definitions/Urep" 125 | 401: 126 | description: "Unauthorized" 127 | schema: 128 | $ref: "#/definitions/UTMRestResponse" 129 | 403: 130 | description: "Forbidden" 131 | 404: 132 | description: "Not Found" 133 | post: 134 | tags: 135 | - "A. Required Endpoints" 136 | summary: "Add UREP" 137 | operationId: "addUrepUsingPOST" 138 | security: 139 | - urep_security: 140 | - "utm.nasa.gov_write.message" 141 | consumes: 142 | - "application/json" 143 | produces: 144 | - "application/json" 145 | parameters: 146 | - in: "body" 147 | name: "urep" 148 | description: "The UREP to be submitted. The ID will be minted by the service,\ 149 | \ so should not be provided." 150 | required: true 151 | schema: 152 | $ref: "#/definitions/Urep" 153 | responses: 154 | 201: 155 | description: "Created" 156 | schema: 157 | $ref: "#/definitions/UTMRestResponse" 158 | 401: 159 | description: "Unauthorized" 160 | schema: 161 | $ref: "#/definitions/UTMRestResponse" 162 | 403: 163 | description: "Forbidden" 164 | 404: 165 | description: "Not Found" 166 | security: 167 | - urep_security: 168 | - "utm.nasa.gov_write.sdsp" 169 | /ureps/{id}: 170 | get: 171 | tags: 172 | - "A. Required Endpoints" 173 | summary: "Get UREPs by ID" 174 | operationId: "getUrepsForIDUsingGET" 175 | consumes: 176 | - "application/json" 177 | produces: 178 | - "application/json" 179 | parameters: 180 | - name: "id" 181 | in: "path" 182 | description: "The urep_id for the requested UREP" 183 | required: true 184 | type: "string" 185 | format: "uuid" 186 | - name: "fields" 187 | in: "query" 188 | description: "A ',' delimited list of field names from the Urep object to\ 189 | \ include within the results. All other fields will be excluded. Fields\ 190 | \ must be valid field names from the Urep object. If not present all fields\ 191 | \ will be returned." 192 | required: false 193 | type: "array" 194 | items: 195 | type: "string" 196 | collectionFormat: "csv" 197 | responses: 198 | 200: 199 | description: "OK" 200 | schema: 201 | $ref: "#/definitions/Urep" 202 | 401: 203 | description: "Unauthorized" 204 | schema: 205 | $ref: "#/definitions/UTMRestResponse" 206 | 403: 207 | description: "Forbidden" 208 | 404: 209 | description: "Not Found" 210 | /urepstream: 211 | get: 212 | tags: 213 | - "B. Subscription Points" 214 | summary: "Subscription point for receiving UREP updates" 215 | produces: 216 | - "application/json" 217 | parameters: [] 218 | responses: 219 | 410: 220 | description: "A RESTful call was made to this endpoint but this is not a\ 221 | \ REST endpoint. Do not use this endpoint for REST calls." 222 | securityDefinitions: 223 | urep_security: 224 | type: "oauth2" 225 | tokenUrl: "https://thisserver.com/oauth/token" 226 | flow: "application" 227 | scopes: 228 | utm.nasa.gov_read.sdsp: "read all UREP data" 229 | utm.nasa.gov_write.sdsp: "Subject can read, create, and udpate UREP data." 230 | definitions: 231 | Urep: 232 | type: "object" 233 | required: 234 | - "altitude" 235 | - "location" 236 | - "source" 237 | - "time_measured" 238 | - "time_submitted" 239 | - "user_id" 240 | properties: 241 | air_temperature: 242 | type: "number" 243 | format: "double" 244 | description: "Air temperature in degrees Celcius." 245 | minimum: -273.15 246 | aircraft_sightings: 247 | type: "array" 248 | description: "An aircraft is in the vicinity of the report." 249 | items: 250 | $ref: "#/definitions/PointOut" 251 | altitude: 252 | type: "number" 253 | format: "double" 254 | description: "The altitude as measured via a GPS device on the aircraft. Units\ 255 | \ in international feet using the WGS84 reference system." 256 | minimum: -250.0 257 | gufi: 258 | type: "string" 259 | format: "uuid" 260 | description: "The UUID of the reporting operation, if appropriate. Note that\ 261 | \ this field is not required, but recommended when UREP is related to a\ 262 | \ UTM-participating operation." 263 | minLength: 36 264 | maxLength: 36 265 | icing_intensity: 266 | type: "string" 267 | description: "A qualitative measure of icing intensity. Use 'NEG' when icing\ 268 | \ was expected, but not encountered." 269 | enum: 270 | - "TRACE" 271 | - "TRACE_LGT" 272 | - "LGT" 273 | - "LGT_MOD" 274 | - "MOD" 275 | - "MOD_SEV" 276 | - "SEV" 277 | - "NEG" 278 | icing_type: 279 | type: "string" 280 | description: "The type of icing encountered. Can only be submitted with icing_intensity." 281 | enum: 282 | - "RIME" 283 | - "CLR" 284 | - "MX" 285 | location: 286 | $ref: "#/definitions/Point" 287 | proximity: 288 | type: "string" 289 | description: "Qualifier for any weather value provided. Use this field if\ 290 | \ the observed phenomenon is not at the provided location, but is nearby.\ 291 | \ If included, must be equal to VC." 292 | enum: 293 | - "VC" 294 | remarks: 295 | type: "string" 296 | description: "Any free text that cannot be captured using the standard fields.\ 297 | \ General use not advised." 298 | maxLength: 1000 299 | source: 300 | type: "string" 301 | description: "How the measured/observed activity was measured/observed. In\ 302 | \ the case of “OTHER” comments should be supplied in the “remarks” field." 303 | enum: 304 | - "VEHICLE" 305 | - "OBSERVER" 306 | - "GROUND_SENSOR" 307 | - "AIRBORNE_SENSOR" 308 | - "OTHER" 309 | time_submitted: 310 | type: "string" 311 | format: "date-time" 312 | description: "USS-assigned time for when the UREP was sent to the UTM System.\ 313 | \ Must be later than time_measured." 314 | time_measured: 315 | type: "string" 316 | format: "date-time" 317 | description: "USS-assigned time for when the data were initially measured.\ 318 | \ Must be earlier than time_submitted." 319 | time_received: 320 | type: "string" 321 | format: "date-time" 322 | description: "UREP system assigned time for when the UREP was received. If\ 323 | \ the time according to the UREP system is earlier than either the time_submitted\ 324 | \ or time_measured, the UREP submission will be rejected." 325 | turbulence_intensity: 326 | type: "string" 327 | description: "A qualitative measure of turbulence intensity. Use 'NEG' when\ 328 | \ turbulence was expected, but not encountered." 329 | enum: 330 | - "LGT" 331 | - "MOD" 332 | - "SEV" 333 | - "EXTRM" 334 | - "LGT_MOD" 335 | - "MOD_SEV" 336 | - "SEV_EXTRM" 337 | - "NEG" 338 | urep_id: 339 | type: "string" 340 | format: "uuid" 341 | description: "UREP system assigned identifier for a UREP." 342 | minLength: 36 343 | maxLength: 36 344 | user_id: 345 | type: "string" 346 | description: "Identity of the principal submitting this UREP to the UREP server." 347 | readOnly: true 348 | maxLength: 1000 349 | operator_id: 350 | type: "string" 351 | description: "Identity of the UAS Operator originating this UREP." 352 | readOnly: true 353 | maxLength: 1000 354 | visibility: 355 | type: "number" 356 | format: "double" 357 | description: "Visibility in statute miles, rounded down if necessary. Maximum\ 358 | \ value 99 indicates unrestricted visibility. Only use partial SM less than\ 359 | \ 1 SM (0.5 SM, but not 20.5 SM)." 360 | weather: 361 | type: "string" 362 | description: "Flight visibility and flight weather, follows PIREP/METAR coding." 363 | enum: 364 | - "DRSN" 365 | - "BLSN" 366 | - "DRDU" 367 | - "DRSA" 368 | - "DZ" 369 | - "FZDZ" 370 | - "DU" 371 | - "BLDU" 372 | - "DS" 373 | - "FG" 374 | - "FZFG" 375 | - "FZRA" 376 | - "FC" 377 | - "GR" 378 | - "SHGR" 379 | - "HZ" 380 | - "IC" 381 | - "PL" 382 | - "SHPL" 383 | - "BR" 384 | - "BCFG" 385 | - "PRFG" 386 | - "RA" 387 | - "SHRA" 388 | - "SA" 389 | - "BLSA" 390 | - "SS" 391 | - "MIFG" 392 | - "SHGS" 393 | - "GS" 394 | - "FU" 395 | - "SG" 396 | - "SN" 397 | - "SHSN" 398 | - "PY" 399 | - "SQ" 400 | - "TS" 401 | - "UP" 402 | - "VA" 403 | - "PO" 404 | weather_intensity: 405 | type: "string" 406 | description: "Qualifier for any weather value provided. Without a weather_intensity\ 407 | \ value, MODERATE is assumed." 408 | enum: 409 | - "HEAVY" 410 | - "MODERATE" 411 | - "LIGHT" 412 | wind_direction: 413 | type: "number" 414 | format: "double" 415 | description: "Magnetic wind direction, 0 to 360 (exclusive) degrees. Must\ 416 | \ be submitted when wind_speed is provided in the UREP ." 417 | minimum: 0.0 418 | maximum: 360.0 419 | exclusiveMinimum: false 420 | exclusiveMaximum: true 421 | wind_speed: 422 | type: "integer" 423 | format: "int32" 424 | description: "Wind speed in knots. Must be submitted when wind_direction is\ 425 | \ provided in the UREP." 426 | minimum: 0 427 | exclusiveMinimum: false 428 | PointOut: 429 | type: "object" 430 | required: 431 | - "altitude" 432 | - "bearing" 433 | - "distance" 434 | - "north_ref" 435 | - "point" 436 | - "state" 437 | - "track" 438 | - "vehicle_type" 439 | properties: 440 | altitude: 441 | type: "number" 442 | format: "double" 443 | description: "The altitude of the target. Units in feet using the WGS84 reference\ 444 | \ system. May be estimated." 445 | minimum: -250.0 446 | bearing: 447 | type: "integer" 448 | format: "int32" 449 | description: "Degrees from north (as defined by north_ref) from reporter's\ 450 | \ position to target." 451 | minimum: 0 452 | maximum: 359 453 | distance: 454 | type: "number" 455 | format: "double" 456 | description: "Nautical miles (horizontal only) from reporter's position to\ 457 | \ target." 458 | minimum: 0.0 459 | exclusiveMinimum: false 460 | north_ref: 461 | type: "string" 462 | description: "The reference for 'north' in reporting values" 463 | enum: 464 | - "MAGNETIC" 465 | point: 466 | $ref: "#/definitions/Point" 467 | remarks: 468 | type: "string" 469 | description: "Any free text that cannot be captured using the standard fields." 470 | maxLength: 1000 471 | state: 472 | type: "string" 473 | description: "The current state of the target." 474 | enum: 475 | - "CRUISE" 476 | - "DESCENT" 477 | - "CLIMB" 478 | - "HOVER" 479 | - "LOITER" 480 | - "UNKNOWN" 481 | track: 482 | type: "number" 483 | format: "double" 484 | description: "The track in decimal degrees relative to north_ref." 485 | minimum: 0.0 486 | maximum: 360.0 487 | exclusiveMinimum: false 488 | exclusiveMaximum: true 489 | vehicle_type: 490 | type: "string" 491 | description: "The type of vehicle being pointed out." 492 | enum: 493 | - "SMALL_UAS" 494 | - "LARGE_UAS" 495 | - "HELICOPTER" 496 | - "SMALL_MANNED_FIXED_WING" 497 | - "HANG_GLIDER" 498 | - "BALLOON" 499 | - "LARGE_MANNED_FIXED_WING" 500 | - "OTHER" 501 | UTMRestResponse: 502 | type: "object" 503 | properties: 504 | http_status_code: 505 | type: "integer" 506 | message: 507 | type: "string" 508 | resource: 509 | type: "string" 510 | example: 511 | http_status_code: 201 512 | message: "Resource created." 513 | resource: "/resource/683c0e9e-49dc-44ce-82de-a5723b1f6965" 514 | Point: 515 | type: "object" 516 | properties: 517 | type: 518 | type: "string" 519 | description: "The type of Geometry. In this case, must be 'Point' per GeoJSON\ 520 | \ spec.\n" 521 | enum: 522 | - "Point" 523 | coordinates: 524 | type: "array" 525 | items: 526 | type: "number" 527 | format: "double" 528 | maxItems: 2 529 | minItems: 2 530 | externalDocs: 531 | url: "https://tools.ietf.org/html/rfc7946#section-3.1.2" 532 | description: "GeoJSon Point, limited to 2D." 533 | responses: 534 | WRONG_PROTOCOL: 535 | description: "A RESTful call was made to this endpoint but this is not a REST\ 536 | \ endpoint. Do not use this endpoint for REST calls." 537 | externalDocs: 538 | description: "SwaggerHub Documentation" 539 | url: "https://app.swaggerhub.com/apis/utm/urep/v1" 540 | -------------------------------------------------------------------------------- /uss-api/README.md: -------------------------------------------------------------------------------- 1 | # USS API 2 | 3 | ## Operational States 4 | 5 | ![alt text](../diagrams/tcl4-statemachine.png "Operational States") 6 | 7 | ## Finding validations from swagger spec which are stated in free text with a MUST. 8 | 9 | curl --silent -o commons.yml https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml && grep -n MUST commons.yml 10 | 11 | 12 | ## Rendering OpenAPI 13 | 14 | Swagger offers several open access tools for spec browsing, for example "http://petstore.swagger.io/?url=RAW" where RAW is the raw github file, eg: 15 | 16 | http://petstore.swagger.io/?url=https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/uss-api/swagger.yaml 17 | 18 | Swagger rendering is especially useful to descend into the models from the API. For example to view Operation.submit_time, 19 | render the USS-API from github v4-draft branch, descend GET Operation, then use the "Example Value | Model" 20 | section of the Operation model to descend into "Model". 21 | -------------------------------------------------------------------------------- /uss-api/swagger.yaml: -------------------------------------------------------------------------------- 1 | swagger: '2.0' 2 | info: 3 | description: >- 4 | This API describes the minimum interface that a USS must implement to be 5 | part of the USS Network. This API allows for communication of data between 6 | USS Instances and from FIMS to a USS regarding new USS Instances. 7 | version: v4 8 | title: USS Required API 9 | termsOfService: > 10 | 11 | A. No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY 12 | WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, 13 | BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO 14 | SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 15 | PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE 16 | SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF 17 | PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN 18 | ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR 19 | RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR 20 | ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, 21 | GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING 22 | THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES 23 | IT "AS IS." 24 | 25 | 26 | B. Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS 27 | AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS 28 | WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT''S USE OF THE SUBJECT SOFTWARE 29 | RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING 30 | FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING 31 | FROM, RECIPIENT''S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY 32 | AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND 33 | SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY 34 | LAW. RECIPIENT''S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, 35 | UNILATERAL TERMINATION OF THIS AGREEMENT. 36 | contact: 37 | name: 'NASA Ames Research Center, Aviation Systems Division' 38 | url: 'https://utm.arc.nasa.gov/' 39 | email: joseph.rios@nasa.gov 40 | license: 41 | name: NASA Open Source Agreement 42 | url: 'https://ti.arc.nasa.gov/opensource/nosa/' 43 | 44 | host: uss.defined.url 45 | basePath: / 46 | schemes: 47 | - https 48 | securityDefinitions: 49 | ussapi_security: 50 | type: oauth2 51 | description: A write scope allows reading. 52 | tokenUrl: 'https://utm.defined.host/oauth/token' 53 | flow: application 54 | scopes: 55 | 'utm.nasa.gov_read.operation': Subject can read operational data such as USS Instance data 56 | 'utm.nasa.gov_write.operation': Subject can read, create, and update operational data such as USS Instance data 57 | 'utm.nasa.gov_read.message': Subject can read message data such as UTM Message and Negotiations 58 | 'utm.nasa.gov_write.message': Subject can read, create, and update message data such as UTM Message and Negotiations 59 | 'utm.nasa.gov_read.publicsafety': Subject can read operations that are designated public safety operations. 60 | 'utm.nasa.gov_write.publicsafety': Subject can read, create, and update operations that are designated public safety operations. 61 | 'utm.nasa.gov_read.constraint': Subject can read UTM constraint data 62 | 'utm.nasa.gov_write.constraint': Subject can read, create, and update UTM constraint data. This means that the Subject can define areas that restrict other operations. 63 | 'utm.nasa.gov_read.conflictmanagement': Subject can read conflict management data. 64 | 'utm.nasa.gov_write.conflictmanagement': Subject can read and write conflict management data. 65 | paths: 66 | '/uvrs/{message_id}': 67 | put: 68 | tags: 69 | - A. Required Endpoints 70 | summary: Allow UAS Volume Reservations (UVRs) to be submitted from authorized entities. 71 | description: >- 72 | Allow UAS Volume Reservations (UVRs) to be submitted from authorized entities. 73 | For validation purposes: 74 | {message_id} in path == UASVolumeReservation.message_id of body data 75 | security: 76 | - ussapi_security: 77 | - utm.nasa.gov_write.constraint 78 | consumes: 79 | - application/json 80 | parameters: 81 | - in: path 82 | name: message_id 83 | required: true 84 | type: string 85 | description: PUT by message_id 86 | - in: body 87 | name: constraint_message 88 | description: The UASVolumeReservation being sent 89 | required: true 90 | schema: 91 | $ref: >- 92 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UASVolumeReservation 93 | responses: 94 | '204': 95 | description: UVR data received. No content returned. 96 | '400': 97 | description: Bad request. Typically validation error. Fix your request and retry. 98 | schema: 99 | $ref: >- 100 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 101 | '401': 102 | description: Invalid or missing access_token provided. 103 | schema: 104 | $ref: >- 105 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 106 | '403': 107 | description: Forbidden. Data and or token do not meet security requirements. 108 | schema: 109 | $ref: >- 110 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 111 | '429': 112 | description: Too many recent requests from you. Wait to make further queries. 113 | schema: 114 | $ref: >- 115 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 116 | 117 | 118 | '/utm_messages/{message_id}': 119 | put: 120 | tags: 121 | - A. Required Endpoints 122 | summary: Allow other authorized entities to send a message to this USS. 123 | description: >- 124 | Allows another USS or FIMS to PUT a message to this USS. 125 | For validation purposes: 126 | {message_id} in path == UTMMessage.message_id of body data 127 | security: 128 | - ussapi_security: 129 | - utm.nasa.gov_write.message 130 | consumes: 131 | - application/json 132 | parameters: 133 | - in: path 134 | name: message_id 135 | required: true 136 | type: string 137 | description: PUT by message_id 138 | - in: body 139 | name: utm_message 140 | description: The UTMMessage being sent 141 | required: true 142 | schema: 143 | $ref: >- 144 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMMessage 145 | responses: 146 | '204': 147 | description: UTMMessage received. No content returned. 148 | '400': 149 | description: Bad request. Typically validation error. Fix your request and retry. 150 | schema: 151 | $ref: >- 152 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 153 | '401': 154 | description: Invalid or missing access_token provided. 155 | schema: 156 | $ref: >- 157 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 158 | '403': 159 | description: Forbidden. Data and or token do not meet security requirements. 160 | schema: 161 | $ref: >- 162 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 163 | '429': 164 | description: Too many recent requests from you. Wait to make further queries. 165 | schema: 166 | $ref: >- 167 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 168 | 169 | '/uss/{uss_instance_id}': 170 | put: 171 | tags: 172 | - A. Required Endpoints 173 | summary: Share USS Instance data 174 | description: >- 175 | As per the USS Discovery Service specification, this endpoint is for 176 | receiving messages about the USS Network from the USS Discovery 177 | Service. For example, when a new USS Instance is registered, that 178 | announcement would come to this endpoint. 179 | 180 | For validation purposes: 181 | {uss_instance_id} in path == UssInstance.uss_instance_id of body data 182 | security: 183 | - ussapi_security: 184 | - utm.nasa.gov_write.operation 185 | consumes: 186 | - application/json 187 | parameters: 188 | - in: path 189 | name: uss_instance_id 190 | required: true 191 | type: string 192 | description: PUT by uss_instance_id 193 | - in: body 194 | name: uss_instance 195 | description: The USS Instance information being sent 196 | required: true 197 | schema: 198 | $ref: >- 199 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UssInstance 200 | responses: 201 | '204': 202 | description: USS Instance data received. No content returned. 203 | '400': 204 | description: Bad request. Typically validation error. Fix your request and retry. 205 | schema: 206 | $ref: >- 207 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 208 | '401': 209 | description: Invalid or missing access_token provided. 210 | schema: 211 | $ref: >- 212 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 213 | '403': 214 | description: Forbidden. Do not retry with same access token. Reason not provided, but do you have the right scopes? 215 | schema: 216 | $ref: >- 217 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 218 | '429': 219 | description: Too many recent requests from you. Wait to make further queries. 220 | schema: 221 | $ref: >- 222 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 223 | 224 | '/negotiations/{message_id}': 225 | put: 226 | tags: 227 | - A. Required Endpoints 228 | summary: Allow other USSs to submit a negotiation request 229 | description: >- 230 | A PUT to the negotiations endpoint is interpreted as a request for 231 | alteration in an existing operation managed by the receiving USS. The 232 | requesting USS supplies a GUFI that references the operation that may be 233 | altered if the request is granted by the receiving USS. 234 | 235 | For validation purposes: 236 | {message_id} in path == NegotiationMessage.message_id in body data 237 | security: 238 | - ussapi_security: 239 | - utm.nasa.gov_write.message 240 | consumes: 241 | - application/json 242 | produces: 243 | - application/json 244 | parameters: 245 | - in: path 246 | name: message_id 247 | required: true 248 | type: string 249 | description: PUT by message_id 250 | - in: body 251 | name: negotiation_message 252 | description: The NegotiationMessage data 253 | required: true 254 | schema: 255 | $ref: >- 256 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/NegotiationMessage 257 | responses: 258 | '204': 259 | description: >- 260 | NegotiationMessage received. No content returned. USS receiving this 261 | NegotiationMessage will move to accommodate the new operation. 262 | '400': 263 | description: Bad request. Typically validation error. Fix your request and retry. 264 | schema: 265 | $ref: >- 266 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 267 | '401': 268 | description: Invalid or missing access_token provided. 269 | schema: 270 | $ref: >- 271 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 272 | '403': 273 | description: Forbidden. Data and or token do not meet security requirements. 274 | schema: 275 | $ref: >- 276 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 277 | '409': 278 | description: Conflicting operation will not accommodate new operation. 279 | schema: 280 | $ref: >- 281 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 282 | '429': 283 | description: Too many recent requests from you. Wait to make further queries. 284 | schema: 285 | $ref: >- 286 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 287 | 288 | '/positions/{position_id}': 289 | put: 290 | tags: 291 | - A. Required Endpoints 292 | summary: Share position information. 293 | description: >- 294 | Providing position reports to others may allow other USSs to anticipate 295 | events. The USS managing the operation has created the position ID. 296 | 297 | For validation purposes: 298 | {position_id} in path == Position.enroute_positions_id of body data 299 | security: 300 | - ussapi_security: 301 | - utm.nasa.gov_write.operation 302 | consumes: 303 | - application/json 304 | produces: 305 | - application/json 306 | parameters: 307 | - in: path 308 | name: position_id 309 | required: true 310 | type: string 311 | description: PUT by enroute_positions_id 312 | - in: body 313 | name: position 314 | required: true 315 | schema: 316 | $ref: >- 317 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Position 318 | responses: 319 | '204': 320 | description: Position data recieved. No content returned. 321 | '400': 322 | description: Bad request. Typically validation error. Fix your request and retry. 323 | schema: 324 | $ref: >- 325 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 326 | '401': 327 | description: Invalid or missing access_token provided. 328 | schema: 329 | $ref: >- 330 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 331 | '403': 332 | description: Forbidden. Data and or token do not meet security requirements. 333 | schema: 334 | $ref: >- 335 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 336 | '429': 337 | description: Too many recent requests from you. Wait to make further queries. 338 | schema: 339 | $ref: >- 340 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 341 | /operations: 342 | get: 343 | tags: 344 | - A. Required Endpoints 345 | summary: Request information regarding Operations 346 | description: Allows querying for Operation data. Returns an empty list if the query returns nothing. 347 | security: 348 | - ussapi_security: 349 | - utm.nasa.gov_write.operation 350 | - utm.nasa.gov_read.operation 351 | produces: 352 | - application/json 353 | parameters: 354 | - name: registration_id 355 | in: query 356 | description: >- 357 | Return only results that match the registration_ids provided. Only 358 | operations that have not completed or have completed within the last 359 | 24 hours are required to be returned. If multiple IDs are provided, 360 | they must be unique and separated by commas. 361 | type: array 362 | minItems: 1 363 | maxItems: 5 364 | uniqueItems: true 365 | items: 366 | type: string 367 | format: uuid 368 | minLength: 36 369 | maxLength: 36 370 | collectionFormat: csv 371 | - name: submit_time 372 | in: query 373 | description: >- 374 | A single date-time value that will be used to provide all operations 375 | submitted AFTER that time. 376 | type: string 377 | format: date-time 378 | minLength: 20 379 | maxLength: 25 380 | required: false 381 | - name: state 382 | in: query 383 | description: >- 384 | Return only operations that are in the states provided. Comma 385 | separated list of states. 386 | type: array 387 | minItems: 1 388 | maxItems: 5 389 | uniqueItems: true 390 | items: 391 | type: string 392 | enum: 393 | - ACCEPTED 394 | - ACTIVATED 395 | - CLOSED 396 | - NONCONFORMING 397 | - ROGUE 398 | collectionFormat: csv 399 | required: false 400 | - name: distance 401 | in: query 402 | description: >- 403 | Distance from reference_point to find operations. Ignored if 404 | reference_point is not provided. Units are feet. Returns all 405 | operations that have any operation_volumes whose 2D horizontal 406 | dimensions interesect the 2D circle defined by distance and 407 | reference_point. Default value only has meaning when 408 | reference_point parameter is provided. 409 | type: integer 410 | format: int32 411 | maximum: 60762 412 | minimum: 1 413 | default: 300 414 | required: false 415 | - name: reference_point 416 | in: query 417 | description: >- 418 | A single point used to find all operations within some distance from 419 | that point. Returns all 420 | operations that have any operation_volumes whose 2D horizontal 421 | dimensions interesect the 2D circle defined by distance and 422 | reference_point. When distance is excluded and reference_point is 423 | included, uses default value (300ft) for distance. 424 | Described as a GeoJSON position. The value is equivalent to what 425 | would be seen in the "coordinates" field for a GeoJSON Point 426 | object. See https://tools.ietf.org/html/rfc7946#section-3.1.1 for 427 | further reference. Example would be reference_point=[-122.056364, 428 | 37.414371] (URL safe: 429 | reference_point%3D%5B-122.056364%2C%2037.414371%5D). As per GeoJSON 430 | spec, this is long-lat format in the WGS84 reference system. 431 | MUST NOT include a third coordinate element, strictly 2D. 432 | type: string 433 | format: geojson-position 434 | required: false 435 | - name: sort 436 | in: query 437 | description: >- 438 | Field name(s) to use for sorting records. If multiple fields 439 | are provided, the sorting is based on the ordered priorty of that 440 | list. Note that the enum provided designates the required fields 441 | that a USS must support. A USS may decide to support additional 442 | fields, but how that USS communicates that option is out of scope 443 | for this API document. 444 | required: false 445 | type: array 446 | items: 447 | type: string 448 | enum: 449 | - submit_time 450 | - gufi 451 | - state 452 | collectionFormat: csv 453 | maxItems: 3 454 | minItems: 1 455 | default: submit_time 456 | - name: sort_increasing 457 | in: query 458 | description: >- 459 | For optional use with the 'sort' parameter. If 'sort' is not 460 | provided, then 'sort_increasing' will be ignored. Boolean value. If 461 | multiple fields are provided in the 'sort' parameter, this boolean 462 | value will apply to all of them. 463 | required: false 464 | type: boolean 465 | default: true 466 | - name: limit 467 | in: query 468 | description: The maximum number or records to return. 469 | required: false 470 | type: integer 471 | default: 10 472 | maximum: 100 473 | exclusiveMaximum: false 474 | minimum: 1 475 | exclusiveMinimum: false 476 | format: int32 477 | - name: offset 478 | in: query 479 | description: The index from which to begin the list of returned records. 480 | required: false 481 | type: integer 482 | default: 0 483 | minimum: 0 484 | exclusiveMinimum: false 485 | format: int32 486 | responses: 487 | '200': 488 | description: Successful data request. Response includes requested data. 489 | schema: 490 | type: array 491 | items: 492 | $ref: >- 493 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Operation 494 | '400': 495 | description: Bad request. Typically validation error. Fix your request and retry. 496 | schema: 497 | $ref: >- 498 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 499 | '401': 500 | description: Invalid or missing access_token provided. 501 | schema: 502 | $ref: >- 503 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 504 | '403': 505 | description: Forbidden. Do not retry with same access token. Reason not provided, but do you have the right scopes? 506 | schema: 507 | $ref: >- 508 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 509 | '423': 510 | description: The requested data are in a transition state. Please retry request. 511 | schema: 512 | $ref: >- 513 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 514 | '429': 515 | description: Too many recent requests from you. Wait to make further queries. 516 | schema: 517 | $ref: >- 518 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 519 | 520 | '/operations/{gufi}': 521 | get: 522 | tags: 523 | - A. Required Endpoints 524 | summary: Retrieve an operation by GUFI. 525 | description: Retrieve an operation by GUFI. Returns 404 if gufi is not found. 526 | security: 527 | - ussapi_security: 528 | - utm.nasa.gov_write.operation 529 | - utm.nasa.gov_read.operation 530 | produces: 531 | - application/json 532 | parameters: 533 | - in: path 534 | name: gufi 535 | required: true 536 | type: string 537 | format: uuid 538 | description: >- 539 | GUFI of the operation being requested. 540 | responses: 541 | '200': 542 | description: OK 543 | schema: 544 | $ref: >- 545 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Operation 546 | '400': 547 | description: Bad request. Typically validation error. Fix your request and retry. 548 | schema: 549 | $ref: >- 550 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 551 | '401': 552 | description: Invalid or missing access_token provided. 553 | schema: 554 | $ref: >- 555 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 556 | '403': 557 | description: Forbidden. Do not retry with same access token. Reason not provided, but do you have the right scopes? 558 | schema: 559 | $ref: >- 560 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 561 | '404': 562 | description: Resource not found. 563 | schema: 564 | $ref: >- 565 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 566 | '423': 567 | description: The requested data are in a transition state. Please retry request. 568 | schema: 569 | $ref: >- 570 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 571 | 572 | put: 573 | tags: 574 | - A. Required Endpoints 575 | summary: 'Announce a new, or update an already announced operation.' 576 | description: >- 577 | Announce an Operation to another USS, either initial Operation or an 578 | update to the Operation. The Operation's owner creates the ID. 579 | security: 580 | - ussapi_security: 581 | - utm.nasa.gov_write.operation 582 | consumes: 583 | - application/json 584 | produces: 585 | - application/json 586 | parameters: 587 | - in: path 588 | name: gufi 589 | required: true 590 | type: string 591 | description: PUT operation by gufi 592 | - in: body 593 | name: operation 594 | description: | 595 | Operational plan with the following properties: 596 | 1. Contains a valid uss_operation_id. 597 | 2. time_available_end value that is in the future. 598 | 3. For an update to an Operation, date-time fields that are in the past MUST NOT be modified. 599 | 4. On the first announcement of an Operation, submit_time SHOULD be equal to update_time. 600 | 5. submit_time MUST be less than or equal to update_time. 601 | 5. {gufi} path parameter MUST equal Operation.gufi of the body data 602 | 6. Operation.uss_id == access_token.sub 603 | 7. Operation.priority_elements.status MUST NOT be PUBLIC_SAFETY. 604 | 8. Other rules for a USS Operation PUT are satisfied. 605 | 606 | required: true 607 | schema: 608 | $ref: >- 609 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Operation 610 | responses: 611 | '204': 612 | description: Operation data received. No content returned. 613 | '400': 614 | description: Bad request. Typically validation error. Fix your request and retry. 615 | schema: 616 | $ref: >- 617 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 618 | '401': 619 | description: Invalid or missing access_token provided. 620 | schema: 621 | $ref: >- 622 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 623 | '403': 624 | description: Forbidden. Data and or token do not meet security requirements. 625 | schema: 626 | $ref: >- 627 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 628 | '409': 629 | description: >- 630 | Conflict. This USS has an Operation that intersects. 631 | 'messages' field in UTMRestResponse will contain list of GUFIs of length 632 | at least 1 indicating the conflicting Operation(s). 633 | schema: 634 | $ref: >- 635 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 636 | '429': 637 | description: Too many recent requests from you. Wait to make further queries. 638 | schema: 639 | $ref: >- 640 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 641 | 642 | '/enhanced/operations/{gufi}': 643 | get: 644 | tags: 645 | - A. Required Endpoints 646 | summary: Retrieve an operation by GUFI, including details relevant to safety and security. 647 | description: >- 648 | Retrieve an operation by GUFI. Returns 404 if gufi is not found. 649 | Similar to '/operations/{gufi}' except 650 | all data tagged x-utm-data-accessibility <= SAFETY is returned. 651 | 652 | Note that there is currently no GET on '/enhanced/operations/' without 653 | specifying a GUFI. If general seraching for operations is required, then 654 | a GET on '/operations' may be performed, followed by individual GETs to 655 | this endpoint for enhanced data access. 656 | 657 | security: 658 | - ussapi_security: 659 | - utm.nasa.gov_read.publicsafety 660 | - utm.nasa.gov_write.publicsafety 661 | produces: 662 | - application/json 663 | parameters: 664 | - in: path 665 | name: gufi 666 | required: true 667 | type: string 668 | format: uuid 669 | description: >- 670 | GUFI of the operation being requested. 671 | responses: 672 | '200': 673 | description: OK 674 | schema: 675 | $ref: >- 676 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Operation 677 | '400': 678 | description: Bad request. Typically validation error. Fix your request and retry. 679 | schema: 680 | $ref: >- 681 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 682 | '401': 683 | description: Invalid or missing access_token provided. 684 | schema: 685 | $ref: >- 686 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 687 | '403': 688 | description: Forbidden. Do not retry with same access token. Reason not provided, but do you have the right scopes? 689 | schema: 690 | $ref: >- 691 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 692 | '404': 693 | description: Resource not found. 694 | schema: 695 | $ref: >- 696 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 697 | '423': 698 | description: The requested data are in a transition state. Please retry request. 699 | schema: 700 | $ref: >- 701 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 702 | put: 703 | tags: 704 | - A. Required Endpoints 705 | summary: 'Announce a new, or update an already announced ENHANCED operation.' 706 | description: >- 707 | Announce an Operation to another USS, either initial Operation or an 708 | update to the Operation. The Operation's owner creates the ID. 709 | 710 | This is the ENHANCED version of the nominal /operations/{gufi} endpoint. 711 | A USS receiving an operation on this endpoint MUST validate that PriorityElements.status == PUBLIC_SAFETY with an appropriate severity. 712 | 713 | In the future there may be several use cases for the this endpoint. 714 | Currently a single use case is required to be supported by USSs. 715 | 716 | ## Writing a public safety operation 717 | 718 | Public safety operations can only be operated by authorized agencies. The 719 | identitiy management of those agencies and individuals within them will 720 | have more requirements than are levied on nominal USSs. Thus the ability 721 | to manage those operations is limited to USSs that undergo additional 722 | checkout processes. Successful completion of those processes allows for 723 | a USS to earn an additional Role (USS_PUBLIC_SAFETY) within UTM managing 724 | public safety ops. 725 | 726 | This role provides access to additional scopes, including utm.nasa.gov_write.publicsafety 727 | which is required to write to this endpoint. 728 | 729 | A public safety operation that ceases to be a public safety operation 730 | should CLOSE the operation as announced on this endpoint after creating 731 | a non-public safety operation on the nominal endpoint. Note this means 732 | that the operation would be already be in the air when becoming a "new" 733 | nominal operation. In addition, there will be a period of time during 734 | which this operation will have 2 GUFIs and 2 plans. The USS should aid 735 | the operator in minimizing this period of time (ideally to less than, say, 736 | 10 seconds). This approach ensures that all operations announced on this 737 | PUT endpoint have the same PriorityElement requirements. 738 | 739 | A nominal operation that becomes a public safety operation should 740 | follow a similar procedure as above. CLOSE the nominal operation after 741 | announcing a new public safety operation on this endpoint. 742 | 743 | security: 744 | - ussapi_security: 745 | - utm.nasa.gov_write.publicsafety 746 | consumes: 747 | - application/json 748 | produces: 749 | - application/json 750 | parameters: 751 | - in: path 752 | name: gufi 753 | required: true 754 | type: string 755 | description: PUT operation by gufi 756 | - in: body 757 | name: operation 758 | description: | 759 | Operational plan with the following properties: 760 | 1. All requirements for the non-enhanced PUT Operation endpoint, as stated in this spec. 761 | 2. Operation.priority_elements.status == PUBLIC_SAFETY and its corresponding severity. 762 | required: true 763 | schema: 764 | $ref: >- 765 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Operation 766 | responses: 767 | '204': 768 | description: Operation data received. No content returned. 769 | '400': 770 | description: Bad request. Typically validation error. Fix your request and retry. 771 | schema: 772 | $ref: >- 773 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 774 | '401': 775 | description: Invalid or missing access_token provided. 776 | schema: 777 | $ref: >- 778 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 779 | '403': 780 | description: Forbidden. Data and or token do not meet security requirements. 781 | schema: 782 | $ref: >- 783 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 784 | '409': 785 | description: >- 786 | Conflict. This USS Instance has an Operation that intersects. 787 | 'Resource' field in UTMRestResponse will contain list of GUFIs of length 788 | at least 1 indicating the conflicting Operation(s). 789 | schema: 790 | $ref: >- 791 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 792 | '429': 793 | description: Too many recent requests from you. Wait to make further queries. 794 | schema: 795 | $ref: >- 796 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 797 | -------------------------------------------------------------------------------- /uss-discovery-api/README.md: -------------------------------------------------------------------------------- 1 | # USS Discovery 2 | 3 | -------------------------------------------------------------------------------- /uss-discovery-api/swagger.yaml: -------------------------------------------------------------------------------- 1 | swagger: '2.0' 2 | info: 3 | description: >- 4 | This API describes the RESTful interface to the USS discovery service within 5 | the UTM System. This service allows for authenticated USS operators to 6 | submit information about their USS and for all stakeholders to query for a 7 | USS Instances matching certain parameters. 8 | version: v4 9 | title: UTM USS Service Discovery 10 | termsOfService: > 11 | 12 | A. No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY 13 | WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, 14 | BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO 15 | SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 16 | PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE 17 | SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF 18 | PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN 19 | ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR 20 | RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR 21 | ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, 22 | GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING 23 | THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES 24 | IT "AS IS." 25 | 26 | 27 | B. Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS 28 | AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS 29 | WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT''S USE OF THE SUBJECT SOFTWARE 30 | RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING 31 | FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING 32 | FROM, RECIPIENT''S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY 33 | AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND 34 | SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY 35 | LAW. RECIPIENT''S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, 36 | UNILATERAL TERMINATION OF THIS AGREEMENT. 37 | contact: 38 | name: 'NASA Ames Research Center, Aviation Systems Division' 39 | url: 'https://utm.arc.nasa.gov/' 40 | email: joseph.rios@nasa.gov 41 | license: 42 | name: NASA Open Source Agreement 43 | url: 'https://ti.arc.nasa.gov/opensource/nosa/' 44 | host: utm.defined.url 45 | basePath: /ussdisc 46 | schemes: 47 | - https 48 | 49 | tags: 50 | - name: A. Required Endpoints 51 | description: The primary RESTful endpoints for sharing USS Instance data. 52 | securityDefinitions: 53 | uss_discovery_security: 54 | type: oauth2 55 | tokenUrl: 'https://utm.defined.host/oauth/token' 56 | flow: application 57 | scopes: 58 | 'utm.nasa.gov_write.conflictmanagement': Subject can read and write conflict management data. 59 | 60 | paths: 61 | /uss: 62 | get: 63 | tags: 64 | - A. Required Endpoints 65 | summary: Request information regarding USS instances 66 | description: Allows for querying for USS instances. 67 | consumes: 68 | - application/json 69 | produces: 70 | - application/json 71 | parameters: 72 | - name: "fields" 73 | in: "query" 74 | description: "The specific subset of fields to return. Comma separated list. \ 75 | (If list is empty, no fields are returned.) 76 | \ Default will be all fields (i.e. when fields parameter is not included in the query). " 77 | required: false 78 | type: "array" 79 | items: 80 | type: "string" 81 | - name: uss_name 82 | in: query 83 | required: false 84 | description: Returns uss_instances with a particular uss_name. 85 | type: string 86 | maxLength: 100 87 | - name: before 88 | in: query 89 | required: false 90 | description: >- 91 | Returns uss_instances active during and before the given time i.e., 92 | time_available_begin < before. Example: 2017-08-20T14:11:56.118Z 93 | type: string 94 | format: date-time 95 | minLength: 20 96 | maxLength: 25 97 | - name: after 98 | in: query 99 | required: false 100 | description: >- 101 | Returns uss_instances active during and after the given time i.e., 102 | time_available_end > before. Example:2017-08-20T14:11:56.118Z 103 | type: string 104 | format: date-time 105 | minLength: 20 106 | maxLength: 25 107 | - name: contains_point 108 | in: query 109 | required: false 110 | description: >- 111 | Returns uss_instances containing the given Point. The coordinates 112 | are comma delimited. Example: -121.2204,36.6684 113 | type: array 114 | maxItems: 2 115 | minItems: 2 116 | items: 117 | type: number 118 | format: double 119 | - name: contains_bbox 120 | in: query 121 | required: false 122 | description: >- 123 | Returns uss_instances containing the given Bbox. The coordinates are 124 | comma delimited (lon_min,lat_min,lon_max,lat_max). Example: -121.3193,36.6089,-121.2204,36.6684 125 | type: array 126 | maxItems: 4 127 | minItems: 4 128 | items: 129 | type: number 130 | format: double 131 | - name: intersects_bbox 132 | in: query 133 | required: false 134 | description: >- 135 | Returns uss_instances intersecting the given Bbox. The coordinates 136 | are comma delimited (lon_min,lat_min,lon_max,lat_max). Example: -121.1133,36.5317,-121.0941,36.6530 137 | type: array 138 | maxItems: 4 139 | minItems: 4 140 | items: 141 | type: number 142 | format: double 143 | - name: reference_point 144 | in: query 145 | required: false 146 | description: >- 147 | Returns uss_instances around the given point within the 'distance'. 148 | It requires parameter 'distance' to be provided. 149 | 150 | Described as a GeoJSON position. The value is equivalent to what 151 | would be seen in the "coordinates" field for a GeoJSON Point 152 | object. See https://tools.ietf.org/html/rfc7946#section-3.1.1 for 153 | further reference. Example would be reference_point=[-122.056364, 154 | 37.414371] (URL safe: 155 | reference_point%3D%5B-122.056364%2C%2037.414371%5D). As per GeoJSON 156 | spec, this is long-lat format in the WGS84 reference system. 157 | 158 | MUST NOT include a third coordinate element, strictly 2D. 159 | type: array 160 | maxItems: 2 161 | minItems: 2 162 | items: 163 | type: number 164 | format: double 165 | - name: distance 166 | in: query 167 | required: false 168 | description: >- 169 | Distance (in feet) around the 'reference_point'. 170 | It requires parameter 'reference_point' to be provided. 171 | type: number 172 | format: double 173 | minimum: 0 174 | - name: sort 175 | in: query 176 | description: >- 177 | A valid field name to use for sorting records. If multiple fields 178 | are provided, the sorting is based on the ordered priorty of that 179 | list. 180 | required: false 181 | type: string 182 | default: time_submitted 183 | - name: sort_increasing 184 | in: query 185 | description: >- 186 | For optional use with the 'sort' parameter. If 'sort' is not 187 | provided, then 'sort_increasing' will be ignored. Boolean value. If 188 | multiple fields are provided in the 'sort' paramenter, this boolean 189 | value will apply to all of them. 190 | required: false 191 | type: boolean 192 | default: true 193 | - name: limit 194 | in: query 195 | description: >- 196 | The maximum number or records to return. Default 1000. 197 | 198 | Please note that if there are more than 1000 instances, the caller 199 | might not know there are more. It is recommended to call again 200 | with offset = 1000, if your first call returns exactly 1000 records. 201 | 202 | Also note if we are returning 1000 records, there is probably 203 | something very wrong with overall design. Limit added now for 204 | testing purposes as concept is further developed. 205 | required: false 206 | type: integer 207 | default: 1000 208 | minimum: 1 209 | maximum: 1000 210 | format: int32 211 | - name: offset 212 | in: query 213 | description: The index from which to begin the list of returned records. Default 0. 214 | required: false 215 | type: integer 216 | default: 0 217 | format: int32 218 | responses: 219 | '200': 220 | description: Successful data request. Response includes requested data. 221 | schema: 222 | type: array 223 | items: 224 | $ref: >- 225 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UssInstance 226 | '400': 227 | description: Bad request. Typically validation error. Fix your request and retry. 228 | schema: 229 | $ref: >- 230 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 231 | '401': 232 | description: Invalid or missing access_token provided. 233 | schema: 234 | $ref: >- 235 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 236 | '429': 237 | description: Too many recent requests from you. Wait to make further queries. 238 | schema: 239 | $ref: >- 240 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 241 | '/uss/{id}': 242 | get: 243 | tags: 244 | - A. Required Endpoints 245 | summary: Request information regarding a single USS Instance 246 | description: Allows for querying for USS Instances. 247 | produces: 248 | - application/json 249 | parameters: 250 | - name: id 251 | in: path 252 | description: id 253 | required: true 254 | type: string 255 | responses: 256 | '200': 257 | description: Successful data request. Response includes requested data. 258 | schema: 259 | $ref: >- 260 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UssInstance 261 | '400': 262 | description: Bad request. Typically validation error. Fix your request and retry. 263 | schema: 264 | $ref: >- 265 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 266 | '401': 267 | description: Invalid or missing access_token provided. 268 | schema: 269 | $ref: >- 270 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 271 | '429': 272 | description: Too many recent requests from you. Wait to make further queries. 273 | put: 274 | tags: 275 | - A. Required Endpoints 276 | summary: Submit USS Instance and USS Instance updates 277 | description: >- 278 | Allows for USS operators to submit a new USS Instance or update a 279 | previous USS Instance submission. 280 | consumes: 281 | - application/json 282 | produces: 283 | - application/json 284 | security: 285 | - uss_discovery_security: 286 | - utm.nasa.gov_write.conflictmanagement 287 | parameters: 288 | - name: id 289 | in: path 290 | description: id 291 | required: true 292 | type: string 293 | - in: body 294 | name: uss_instance 295 | description: | 296 | USS Instance with the following properties: 297 | 1. Contains a valid uss_instance_id. 298 | 2. Instance has time_available_end value that is in the future. 299 | 3. No date-time fields that are in the past are modified. 300 | 4. Other rules for a USS Instance POST are satisfied. 301 | required: true 302 | schema: 303 | $ref: >- 304 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UssInstance 305 | responses: 306 | '204': 307 | description: USS Instance received. No content returned. 308 | '400': 309 | description: Bad request. Typically validation error. Fix your request and retry. 310 | schema: 311 | $ref: >- 312 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 313 | '401': 314 | description: Invalid or missing access_token provided. 315 | schema: 316 | $ref: >- 317 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 318 | '429': 319 | description: Too many recent requests from you. Wait to make further queries. 320 | schema: 321 | $ref: >- 322 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 323 | -------------------------------------------------------------------------------- /utm-domains/utm-domain-geojson.yaml: -------------------------------------------------------------------------------- 1 | ### https://gist.github.com/bubbobne/fe5f2db65acf039be6a9fd92fc9c7233 2 | 3 | #MIT License 4 | # 5 | #Copyright (c) 2017 Daniele Andreis 6 | #Permission is hereby granted, free of charge, to any person obtaining a copy 7 | #of this software and associated documentation files (the "Software"), to deal 8 | #in the Software without restriction, including without limitation the rights 9 | #to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 10 | #copies of the Software, and to permit persons to whom the Software is 11 | #furnished to do so, subject to the following conditions: 12 | # 13 | # 14 | #The above copyright notice and this permission notice shall be included in all 15 | #copies or substantial portions of the Software. 16 | # 17 | #THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | #IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | #FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | #AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | #LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | #OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 | #SOFTWARE. 24 | 25 | info: 26 | description: "UTM geogrpahy model (swagger domain)" 27 | version: 'v4' 28 | title: UTM Geography Model 29 | 30 | # 31 | #Edits by joseph.rios@nasa.gov: 32 | # 33 | #Converted into a domain versus an API. 34 | #Fixed "Point2d" syntax errors 35 | #Removed responses section. 36 | #Removed non-geojson definitions 37 | #Commented out unsupported elements in UTM (multi*, GeometryCollection) 38 | #Updated externalDocs links to point to RFC 39 | #Improved "description" fields. 40 | 41 | #jlrios: "Point2d" rendering, renamed as "Position" to align with GeoJSON spec. 42 | #jlrios: flattened by removing Geometry to improve codegen, simplify schema 43 | #issmith: debug integrations 44 | #jlrios: added required fileds for Polygon and LineString 45 | 46 | definitions: 47 | 48 | Point: 49 | type: object 50 | description: GeoJSon Point, limited to 2D. 51 | externalDocs: 52 | url: https://tools.ietf.org/html/rfc7946#section-3.1.2 53 | properties: 54 | type: 55 | description: | 56 | The type of Geometry. In this case, must be 'Point' per GeoJSON spec. 57 | type: string 58 | enum: 59 | - Point 60 | coordinates: 61 | type: array 62 | maxItems: 2 63 | minItems: 2 64 | items: 65 | type: number 66 | format: double 67 | example: [0.0, 0.0] 68 | 69 | LineString: 70 | type: object 71 | required: 72 | - type 73 | - coordinates 74 | description: GeoJSon LineString. Positions all 2D. 75 | externalDocs: 76 | url: https://tools.ietf.org/html/rfc7946#section-3.1.4 77 | properties: 78 | type: 79 | description: | 80 | The type of Geometry. In this case, must be 'LineString' per GeoJSON spec. LineString can have 4 to 30 points. 81 | type: string 82 | enum: 83 | - LineString 84 | coordinates: 85 | type: array 86 | maxItems: 30 87 | minItems: 4 88 | items: 89 | type: array 90 | maxItems: 2 91 | minItems: 2 92 | items: 93 | type: number 94 | format: double 95 | 96 | Polygon: 97 | type: object 98 | required: 99 | - type 100 | - coordinates 101 | description: GeoJSon Polygon. Positions all 2D. 102 | externalDocs: 103 | url: https://tools.ietf.org/html/rfc7946#section-3.1.6 104 | properties: 105 | type: 106 | description: | 107 | The type of Geometry. In this case, must be 'Polygon' per GeoJSON 108 | spec. Note that the "coordinates" member is validated to be be an 109 | array of size one. This implies there are no interior rings allowed 110 | currently. 111 | type: string 112 | enum: 113 | - Polygon 114 | coordinates: 115 | type: array 116 | description: >- 117 | The number of polygons allowed. Currently 1, implying no interior 118 | rings. If this number is changes, the maxItems should be considered. 119 | 120 | From RFC7946: 121 | o For type "Polygon", the "coordinates" member MUST be an array of 122 | linear ring coordinate arrays. 123 | 124 | o For Polygons with more than one of these rings, the first MUST be 125 | the exterior ring, and any others MUST be interior rings. The 126 | exterior ring bounds the surface, and the interior rings (if 127 | present) bound holes within the surface. 128 | 129 | Again, note we only allow a single set of coordinates, implying no 130 | interior rings. 131 | minItems: 1 132 | maxItems: 1 133 | items: 134 | type: array 135 | description: >- 136 | The number of vertices in this polygon. From RFC7946: 137 | o A linear ring is a closed LineString with four or more positions. 138 | 139 | o The first and last positions are equivalent, and they MUST contain 140 | identical values; their representation SHOULD also be identical. 141 | 142 | o A linear ring is the boundary of a surface or the boundary of a 143 | hole in a surface. 144 | 145 | o A linear ring MUST follow the right-hand rule with respect to the 146 | area it bounds, i.e., exterior rings are counterclockwise, and 147 | holes are clockwise. (also in the spec: parsers SHOULD NOT reject 148 | Polygons that do not follow the right-hand rule.) 149 | 150 | https://tools.ietf.org/html/rfc7946#section-3.1.6 151 | 152 | minItems: 4 153 | maxItems: 100 154 | items: 155 | type: array 156 | description: >- 157 | The actual coordinates for a vertex of the linear ring. Note that 158 | UTM does not allow additional elements other than long and lat in 159 | this array. 160 | maxItems: 2 161 | minItems: 2 162 | items: 163 | type: number 164 | format: double 165 | -------------------------------------------------------------------------------- /utm-domains/utm-domain-metadata.yaml: -------------------------------------------------------------------------------- 1 | info: 2 | description: "UTM metadata model used for events for NASA MOPS data collection." 3 | version: 'v3' 4 | title: UTM Metadata 5 | 6 | definitions: 7 | EventMetadata: 8 | type: object 9 | required: 10 | - data_collection 11 | - scenario 12 | - test_card 13 | - call_sign 14 | - test_type 15 | - source 16 | - event_id 17 | - location 18 | - setting 19 | - test_run 20 | properties: 21 | data_collection: 22 | description: >- 23 | If true these data are intended for Data Collection. Essentially 24 | stating if particular data should be ignored during analysis. This 25 | may be modified after submission in the case that there was an issue 26 | during execution of the test/experiment that would invalidate the 27 | data that were collected. 28 | type: boolean 29 | event_id: 30 | type: string 31 | description: >- 32 | A string tag indicating which event this operation is associated. 33 | Will be used to select a set of rules for validation. 34 | minLength: 1 35 | maxLength: 100 36 | scenario: 37 | description: >- 38 | Proper formatting for SOW scenarios is "SCENARIO_n" where n is 1-5. 39 | 40 | For other scenarios, the appropriate value should be provided by the 41 | POC for that activity. 42 | type: string 43 | minLength: 1 44 | maxLength: 100 45 | test_card: 46 | description: >- 47 | The name or number of the test card. In many cases, a scenario will 48 | have only one test_card, but it is possible that there are multiple 49 | test_cards for a given scenario. 50 | minLength: 1 51 | maxLength: 100 52 | type: string 53 | test_run: 54 | description: >- 55 | An identifier for a specific run of a test_card. In many cases, a 56 | test_card may be only run once. However, it is possible that a 57 | test_card is run multiple times. 58 | minLength: 1 59 | maxLength: 100 60 | type: string 61 | call_sign: 62 | type: string 63 | minLength: 1 64 | maxLength: 100 65 | description: >- 66 | Expected values: a call sign, test card role, or flight ID that links 67 | this operation to a particular test card flight. As an example, in our 68 | TCL2 demo, "GCS3" could have been used here. For multiple flights 69 | emanating from one location on a test card, this data element could 70 | include further information to link the operation to the test card 71 | flight, such as GCS1A. 72 | 73 | Every operation requires a call_sign that is pre-determined in the 74 | full test card description. 75 | test_type: 76 | type: string 77 | description: >- 78 | Test type. Note a GROUND test may use a physical vehicle and a FLIGHT 79 | test may use a simulated vehicle. This is the reason for separating 80 | test_type from source. 81 | enum: 82 | - GROUND 83 | - FLIGHT 84 | source: 85 | type: string 86 | description: >- 87 | Hardware-in-the-loop (HWITL) flights refer to ground or airborne 88 | flights. Software-in-the loop (SWITL) flights would be used to tag 89 | flights do not use a physical vehicle, whether or not there is a 90 | full-featured simulation involved. 91 | enum: 92 | - HWITL 93 | - SWITL 94 | location: 95 | type: string 96 | description: >- 97 | Name of the testing location, such as NV, Moffett, Crows 98 | Landing, etc. The supplier of the metadata should use a constant 99 | value for this field when the same location is used mulitple times 100 | across data submissions. E.g. "AMES" should always be "AMES" and not 101 | "ames" or "Ames" or "NASA Ames" at other various times. 102 | minLength: 1 103 | maxLength: 100 104 | setting: 105 | type: string 106 | description: >- 107 | Test setting. Note that a LAB setting may involve HWITL source and 108 | FIELD settings may involve SWITL sources. LAB settings may have 109 | GROUND or FLIGHT tests, same with FIELD settings. 110 | enum: 111 | - LAB 112 | - FIELD 113 | free_text: 114 | type: string 115 | description: >- 116 | Free text may be included with the original submission and/or added 117 | by a data_quality_engineer. In the latter case, all previous 118 | free_text should be preserved, i.e. the data_quality_engineer should 119 | only append to the free_text field. 120 | maxLength: 3000 121 | data_quality_engineer: 122 | type: string 123 | format: email_address 124 | description: >- 125 | Email address of author handling data quality issue. If multiple 126 | individuals modify this metadata, this field will only hold the 127 | last such individual. In that case, the engineer should make an 128 | effort to document as much as possible in the free_text field. 129 | 130 | SHOULD NOT be included wth an operation. This element is populated 131 | by NASA as needed. 132 | maxLength: 150 133 | modified: 134 | type: boolean 135 | description: >- 136 | This metadata was modified from its original submission by a 137 | data_quality_engineer. 138 | 139 | SHOULD NOT be included wth an operation. This element is populated 140 | by NASA as needed. 141 | default: false 142 | 143 | 144 | example: 145 | data_collection: true 146 | event_id: TCL3_FD 147 | test_card: TC3 148 | test_identifiers: ["CNS1", "DAT3", "CON5" ] 149 | call_sign: GCS1 150 | test_type: FLIGHT 151 | source: HWITL 152 | location: AK 153 | setting: FIELD 154 | free_text: "shakedown with Larry" 155 | data_quality_engineer: data_quality@test-site.com 156 | modfied: false 157 | -------------------------------------------------------------------------------- /utm-domains/utm-domain-performance-auth.yaml: -------------------------------------------------------------------------------- 1 | swagger: '2.0' 2 | info: 3 | title: Performance Authorization 4 | description: | 5 | The following definition is from: 6 | 7 | FAA NextGen UTM Concept of Operations v1.0 8 | 9 | https://utm.arc.nasa.gov/docs/2018-UTM-ConOps-v1.0.pdf 10 | 11 | NOTE: THIS IS A CONCEPTUAL DEFINITION. IT IS NOT CURRENT POLICY NOR A CURRENT RULE. 12 | 13 | 'All BVLOS Operators are required to obtain a Performance Authorization from the FAA prior to 14 | conducting a UTM operation. A Performance Authorization is a FAA regulatory approval for BVLOS 15 | Operators to perform a specific type of operation in a specified geographical area. The FAA grants a 16 | Performance Authorization when a UAS Operator’s proposed ground and air assets are sufficient to 17 | meet an established level of performance in the airspace in which they intend to operate.' 18 | 19 | version: 'v1' 20 | contact: 21 | name: 'NASA Ames Research Center, Aviation Systems Division' 22 | url: 'https://utm.arc.nasa.gov/' 23 | email: joseph.rios@nasa.gov 24 | license: 25 | name: NASA Open Source Agreement 26 | url: 'https://ti.arc.nasa.gov/opensource/nosa/' 27 | 28 | paths: 29 | '/no-paths': 30 | put: 31 | responses: 32 | '410': 33 | description: >- 34 | Gone. Not implemented. Will not be implemented. Path included for 35 | proper use by automated tooling. Tools sometimes do not like 36 | when there are no paths, but domains do not contain paths. 37 | 38 | definitions: 39 | PerformanceAuthorization: 40 | type: object 41 | required: 42 | - performance_authorization_id 43 | - state 44 | - contacts 45 | properties: 46 | performance_authorization_id: 47 | description: >- 48 | A universally unique identifier for this performance authorization. 49 | $ref: '#/definitions/PerformanceAuthorizationUUID' 50 | state: 51 | description: | 52 | The current state of this Performance Authorization. 53 | 54 | | State | Description | 55 | |------------- |--------------------------------------------------- | 56 | | DEVELOPMENT | PA in development. Internal to the applicant. | 57 | | APPLICATION | PA is ready for submission. | 58 | | REVIEW | PA is in review status with the ANSP. | 59 | | APPROVED | PA is approved, ready for use per data within PA. | 60 | | REJECTED | PA is rejected. | 61 | 62 | type: string 63 | enum: 64 | - DEVELOPMENT 65 | - APPLICATION 66 | - REVIEW 67 | - APPROVED 68 | - REJECTED 69 | organization: 70 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/PersonOrOrganization' 71 | contacts: 72 | description: >- 73 | List of individual(s) at the applying serving as primary contacts for 74 | this performance authorization. 75 | type: array 76 | minItems: 1 77 | maxItems: 5 78 | items: 79 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/PersonOrOrganization' 80 | date_of_validity: 81 | description: >- 82 | Date (inclusive) that any operations under this Performance Authorization 83 | would be authorized. 84 | 85 | date_of_validity <= date_of_expiration MUST be true. 86 | 87 | $ref: '#/definitions/PerformanceAuthorizationDate' 88 | date_of_expiration: 89 | description: | 90 | Date (inclusive) after which any operations under this Performance Authorization 91 | would be unauthorized. 92 | 93 | `date_of_validity <= date_of_expiration` MUST be true. 94 | 95 | $ref: '#/definitions/PerformanceAuthorizationDate' 96 | operation_types: 97 | description: >- 98 | An array of OperationType objects. Each OperationType contains a 99 | formal specification of the types of operations allowed including 100 | elements related to the geogrpahical location, the vehicle 101 | capabilities, the mission characteristics, and other elements. 102 | 103 | Since this is an array, multiple OperationTypes are allowed to account 104 | for variations in any of the elements under a single Performance 105 | Authorization. 106 | type: array 107 | items: 108 | $ref: '#/definitions/OperationType' 109 | 110 | OperationType: 111 | type: object 112 | required: 113 | - base_operating_rule 114 | - operation_type_label 115 | - equipment_specification_reference 116 | - mission_characteristics_reference 117 | - area_of_operation_references 118 | - standard_provisions_reference 119 | - special_provisions_reference 120 | 121 | properties: 122 | base_operating_rule: 123 | description: | 124 | 125 | Flight rule providing base operating rules. 126 | 127 | type: string 128 | enum: 129 | - 107 130 | - 107X 131 | operation_type_label: 132 | description: >- 133 | A label to indicate this operation type within this performance 134 | authorization. Must be distinct from all other operation type 135 | labels within this performance authorization. 136 | $ref: '#/definitions/PerformanceAuthorizationLabel' 137 | equipment_specification_reference: 138 | description: >- 139 | A reference to the equipment specification to be associated with this 140 | operation type. 141 | $ref: '#/definitions/PerformanceAuthorizationLabel' 142 | mission_characteristics_reference: 143 | description: >- 144 | A reference to the mission characteristics to be associated with this 145 | operation type. 146 | $ref: '#/definitions/PerformanceAuthorizationLabel' 147 | area_of_operation_references: 148 | description: >- 149 | A reference to the area of operations to be associated with this 150 | operation type. 151 | type: array 152 | minItems: 1 153 | maxItems: 100 154 | items: 155 | $ref: '#/definitions/PerformanceAuthorizationLabel' 156 | standard_provisions_reference: 157 | description: >- 158 | A reference to the standard provisions to be associated with this 159 | operation type. 160 | $ref: '#/definitions/PerformanceAuthorizationLabel' 161 | special_provisions_reference: 162 | description: >- 163 | A reference to the special provisions to be associated with this 164 | operation type. 165 | $ref: '#/definitions/PerformanceAuthorizationLabel' 166 | 167 | EquipmentSpecification: 168 | type: object 169 | required: 170 | - equipment_specifiation_label 171 | - flight_crew_comm_freq 172 | - v2v_equipped 173 | properties: 174 | equipment_specifiation_label: 175 | $ref: '#/definitions/PerformanceAuthorizationLabel' 176 | flight_crew_comm_freq: 177 | description: >- 178 | add descp. MHz? Fix bounds. 179 | type: number 180 | format: double 181 | minimum: 0.0 182 | maximum: 30000.0 183 | example: 5800.0 184 | v2v_equipped: 185 | description: >- 186 | This property asks: Must the vehicle be equipped to meet the 187 | accepted V2V standard? 188 | 189 | This could be an enumeration of choices or a generic string depending 190 | on the level of detail desired in this property. 191 | type: boolean 192 | example: true 193 | 194 | MissionCharacteristics: 195 | description: >- 196 | Mission Characteristics. 197 | type: object 198 | required: 199 | - minimum_operation_altitude 200 | - maximum_operation_altitude 201 | - minimum_aircraft_weight_lbs 202 | - maximum_aircraft_weight_lbs 203 | - minimum_aircraft_endurance_minutes 204 | - maximum_mission_duration_minutes 205 | properties: 206 | mission_type: 207 | type: string 208 | enum: 209 | - AGRICULTURE 210 | - INSPECTION 211 | - PUBLIC_SAFETY 212 | - JOURNALISM 213 | - REMOTE_SENSING 214 | - OTHER 215 | minimum_operation_altitude: 216 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Altitude' 217 | maximum_operation_altitude: 218 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Altitude' 219 | minimum_aircraft_weight_lbs: 220 | type: number 221 | format: float 222 | minimum: 0.0 223 | exclusiveMinimum: false 224 | maximum_aircraft_weight_lbs: 225 | type: number 226 | format: float 227 | minimum: 0.0 228 | exclusiveMinimum: true 229 | minimum_operation_speed_kts: 230 | type: number 231 | format: float 232 | minimum: 0.0 233 | exclusiveMinimum: true 234 | maximum_operation_speed_kts: 235 | type: number 236 | format: float 237 | minimum: 0.0 238 | exclusiveMinimum: false 239 | minimum_aircraft_endurance_minutes: 240 | type: integer 241 | format: int32 242 | minimum: 0 243 | exclusiveMinimum: false 244 | maximum_mission_duration_minutes: 245 | type: integer 246 | format: int32 247 | minimum: 0 248 | exclusiveMinimum: true 249 | contingency_plans: 250 | description: >- 251 | This is just a placeholder. Details needed for schema dev. 252 | 253 | This is probably not going to be a string. Likely an array of some 254 | currently undefined model. May leverage UTM Operation Plan models. 255 | type: string 256 | maxLength: 200 257 | 258 | AreaOfOperation: 259 | description: >- 260 | A 4D volume describing where operations are allowed. Multiple 261 | AreaOfOperations are allowed in each OperationType. 262 | type: object 263 | required: 264 | - area_of_operation_label 265 | - effective_date_begin 266 | - effective_date_end 267 | - min_altitude 268 | - max_altitude 269 | - operation_geography 270 | properties: 271 | area_of_operation_label: 272 | description: >- 273 | A label to indicate this area of operation object within this performance 274 | authorization. Must be distinct from all other area of operation 275 | labels within this performance authorization. 276 | $ref: '#/definitions/PerformanceAuthorizationLabel' 277 | effective_date_begin: 278 | description: >- 279 | Earliest date (inclusive) that operations under this Performance Authorization 280 | would be allowed within the geographical boundaries of this 281 | AreaOfOperation object. 282 | 283 | effective_date_begin <= effective_date_end MUST be true. 284 | 285 | $ref: '#/definitions/PerformanceAuthorizationDate' 286 | effective_date_end: 287 | description: >- 288 | Latest date (inclusive) that operations under this Performance Authorization 289 | would be allowed within the geographical boundaries of this 290 | AreaOfOperation object. 291 | 292 | effective_date_begin <= effective_date_end MUST be true. 293 | 294 | $ref: '#/definitions/PerformanceAuthorizationDate' 295 | min_altitude: 296 | description: >- 297 | The minimum altitude for this operation in this operation volume. 298 | The following MUST hold: min_altitude.altitude_value < max_altitude.altitude_value 299 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Altitude' 300 | max_altitude: 301 | description: >- 302 | The maximum altitude for this operation in this operation volume. 303 | The following MUST hold: min_altitude.altitude_value < max_altitude.altitude_value 304 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/Altitude' 305 | operation_geography: 306 | description: 307 | The polygon encompassing the operational area. 308 | $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Polygon' 309 | 310 | StandardProvisions: 311 | description: >- 312 | Standard provisions for an OperationType. 313 | type: object 314 | required: 315 | - standard_provisions_label 316 | properties: 317 | standard_provisions_label: 318 | description: >- 319 | A label to indicate this set of standard provisions within this performance 320 | authorization. Must be distinct from all other standard provisions 321 | labels within this performance authorization. 322 | $ref: '#/definitions/PerformanceAuthorizationLabel' 323 | airworthiness_certificate_designation_number: 324 | type: string 325 | minLength: 3 326 | maxLength: 70 327 | maximum_uas_per_rpic: 328 | type: integer 329 | format: int32 330 | minimum: 1 331 | example: 2 332 | minimum_gcs_per_uas: 333 | type: integer 334 | format: int32 335 | minimum: 0 336 | example: 1 337 | maximum_gcs_per_uas: 338 | type: integer 339 | format: int32 340 | minimum: 0 341 | example: 1 342 | maximum_concurrent_rpic_per_uas: 343 | type: integer 344 | format: int32 345 | minimum: 0 346 | example: 1 347 | 348 | 349 | SpecialProvisions: 350 | description: >- 351 | Special provisions for an OperationType. 352 | type: object 353 | required: 354 | - special_provisions_label 355 | properties: 356 | special_provisions_label: 357 | description: >- 358 | A label to indicate this set of special provisions within this performance 359 | authorization. Must be distinct from all other special provisions 360 | labels within this performance authorization. 361 | $ref: '#/definitions/PerformanceAuthorizationLabel' 362 | allow_moving_gcs_operations: 363 | type: boolean 364 | default: false 365 | allow_night_operations: 366 | type: boolean 367 | default: false 368 | allow_bvlos_operations: 369 | type: boolean 370 | default: false 371 | allow_ops_over_people: 372 | type: boolean 373 | default: false 374 | allow_operations_near_aircraft: 375 | type: boolean 376 | default: false 377 | allow_multi_uas_operations: 378 | type: boolean 379 | default: false 380 | allow_tactical_observers: 381 | type: boolean 382 | default: false 383 | allow_expanding_operating_limits: 384 | type: boolean 385 | default: false 386 | 387 | PerformanceAuthorizationLabel: 388 | description: >- 389 | A reusable field describing a label with a performance authorization. Used 390 | by the various components of the performance authorization to efficiently 391 | reference each other as needed. 392 | type: string 393 | minLength: 1 394 | maxLength: 30 395 | 396 | PerformanceAuthorizationUUID: 397 | description: >- 398 | A valid version 4 Universally Unique Identifier as described within 399 | RFC4122: 400 | 401 | https://tools.ietf.org/html/rfc4122 402 | type: string 403 | format: uuid 404 | pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' 405 | example: 'd7126818-d280-475f-aaee-c16e9c6f04e0' 406 | maxLength: 36 407 | minLength: 36 408 | 409 | PerformanceAuthorizationDate: 410 | description: >- 411 | This is a 'full-date' as described within RFC3339: 412 | https://tools.ietf.org/html/rfc3339#section-5.6 413 | type: string 414 | format: date 415 | minLength: 10 416 | maxLength: 10 417 | pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])$" 418 | example: '2015-08-20' 419 | -------------------------------------------------------------------------------- /vehicle/swagger.yaml: -------------------------------------------------------------------------------- 1 | swagger: '2.0' 2 | info: 3 | version: 'v4' 4 | title: Vehicle Registration 5 | description: Validates that the vehicle ID was properly registered for a NASA event. 6 | contact: 7 | name: 'NASA Ames Research Center, Aviation Systems Division' 8 | url: 'https://utm.arc.nasa.gov/' 9 | email: joseph.rios@nasa.gov 10 | license: 11 | name: NASA Open Source Agreement 12 | url: 'https://ti.arc.nasa.gov/opensource/nosa/' 13 | termsOfService: > 14 | 15 | A. No Warranty: THE SUBJECT SOFTWARE IS PROVIDED "AS IS" WITHOUT ANY 16 | WARRANTY OF ANY KIND, EITHER EXPRESSED, IMPLIED, OR STATUTORY, INCLUDING, 17 | BUT NOT LIMITED TO, ANY WARRANTY THAT THE SUBJECT SOFTWARE WILL CONFORM TO 18 | SPECIFICATIONS, ANY IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 19 | PARTICULAR PURPOSE, OR FREEDOM FROM INFRINGEMENT, ANY WARRANTY THAT THE 20 | SUBJECT SOFTWARE WILL BE ERROR FREE, OR ANY WARRANTY THAT DOCUMENTATION, IF 21 | PROVIDED, WILL CONFORM TO THE SUBJECT SOFTWARE. THIS AGREEMENT DOES NOT, IN 22 | ANY MANNER, CONSTITUTE AN ENDORSEMENT BY GOVERNMENT AGENCY OR ANY PRIOR 23 | RECIPIENT OF ANY RESULTS, RESULTING DESIGNS, HARDWARE, SOFTWARE PRODUCTS OR 24 | ANY OTHER APPLICATIONS RESULTING FROM USE OF THE SUBJECT SOFTWARE. FURTHER, 25 | GOVERNMENT AGENCY DISCLAIMS ALL WARRANTIES AND LIABILITIES REGARDING 26 | THIRD-PARTY SOFTWARE, IF PRESENT IN THE ORIGINAL SOFTWARE, AND DISTRIBUTES 27 | IT "AS IS." 28 | 29 | 30 | B. Waiver and Indemnity: RECIPIENT AGREES TO WAIVE ANY AND ALL CLAIMS 31 | AGAINST THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND SUBCONTRACTORS, AS 32 | WELL AS ANY PRIOR RECIPIENT. IF RECIPIENT''S USE OF THE SUBJECT SOFTWARE 33 | RESULTS IN ANY LIABILITIES, DEMANDS, DAMAGES, EXPENSES OR LOSSES ARISING 34 | FROM SUCH USE, INCLUDING ANY DAMAGES FROM PRODUCTS BASED ON, OR RESULTING 35 | FROM, RECIPIENT''S USE OF THE SUBJECT SOFTWARE, RECIPIENT SHALL INDEMNIFY 36 | AND HOLD HARMLESS THE UNITED STATES GOVERNMENT, ITS CONTRACTORS AND 37 | SUBCONTRACTORS, AS WELL AS ANY PRIOR RECIPIENT, TO THE EXTENT PERMITTED BY 38 | LAW. RECIPIENT''S SOLE REMEDY FOR ANY SUCH MATTER SHALL BE THE IMMEDIATE, 39 | UNILATERAL TERMINATION OF THIS AGREEMENT. 40 | 41 | host: utmregistry.arc.nasa.gov 42 | basePath: /api 43 | schemes: 44 | - https 45 | securityDefinitions: 46 | vehicle_oauth: 47 | type: oauth2 48 | authorizationUrl: 'https://utm.defined.host/oauth/token' 49 | flow: implicit 50 | scopes: 51 | 'utm.nasa.gov_read.publicsafety': "retrieve public safety data, for example, a Public Safety USS retrieves data." 52 | 'utm.nasa.gov_read.uvin': "retrieve uvin registration data, for example, a USS checks that a vehicle is registered." 53 | 'utm.nasa.gov_write.uvin': "Write uvin data, for example, a Vehicle Authority enters new data." 54 | 55 | paths: 56 | /uvins/{uvin}: 57 | get: 58 | description: > 59 | Returns information on vehicle with the given uvin. If it is a valid request 60 | and the uvin exists in the database, a VehicleReg model object is returned 61 | with an 200 HTTP code. If it is a valid request and the uvin does not exist in 62 | the database, an empty array is returned also with a 200 HTTP code. 63 | security: 64 | - vehicle_oauth: 65 | - utm.nasa.gov_read.publicsafety 66 | - utm.nasa.gov_read.uvin 67 | parameters: 68 | - in: path 69 | name: "uvin" 70 | type: "string" 71 | required: true 72 | description: "Specifies the vehicle id" 73 | - in: header 74 | name: "Accept" 75 | type: "string" 76 | required: true 77 | description: "Must be 'application/json'" 78 | - in: query 79 | name: "org-code" 80 | type: "string" 81 | description: "Organization authenticity code." 82 | responses: 83 | 200: 84 | description: "Successful" 85 | schema: 86 | $ref: '#/definitions/VehicleReg' 87 | 401: 88 | description: "Unauthorized" 89 | schema: 90 | $ref: >- 91 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 92 | 403: 93 | description: "Forbidden" 94 | 404: 95 | description: "Not Found" 96 | 97 | 400: 98 | description: "Bad request. Typically validation error. Fix your request\ 99 | \ and retry." 100 | 503: 101 | description: Service Unavailable 102 | schema: 103 | $ref: >- 104 | https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-commons.yaml#/definitions/UTMRestResponse 105 | /uvins/: 106 | post: 107 | consumes: 108 | - application/x-www-form-urlencoded 109 | description: USS registers a vehicele on behalf of a vehicle owner 110 | security: 111 | - vehicle_oauth: 112 | - 'utm.nasa.gov_write.uvin' 113 | 114 | parameters: 115 | - in: header 116 | name: "Accept" 117 | type: "string" 118 | required: true 119 | description: "Must be 'application/json'" 120 | - in: formData 121 | name: vehicle-type-id 122 | type: string 123 | required: true 124 | description: Vehicle type id of vehicle to be registered 125 | - in: formData 126 | name: org-uuid 127 | type: string 128 | required: true 129 | description: Organization uuid 130 | - in: formData 131 | name: org-code 132 | required: true 133 | type: string 134 | description: "Organization authenticity code." 135 | - in: formData 136 | name: vehicle-name 137 | required: true 138 | type: string 139 | description: Name of vehicle instance 140 | - in: formData 141 | name: event-id 142 | type: number 143 | required: true 144 | description: Event identifier; Enter X for TCLX 145 | - in: formData 146 | name: n-number 147 | type: string 148 | description: N-number of aircraft 149 | - in: formData 150 | name: faa-number 151 | type: string 152 | description: FAA number of aircraft 153 | produces: 154 | - application/json 155 | responses: 156 | 201: 157 | description: "Successful" 158 | schema: 159 | $ref: '#/definitions/VehiclePost' 160 | /orgs/{uvin}: 161 | get: 162 | description: > 163 | Returns information on vehicle owner, for example, a Public Safety 164 | USS gets vehicle owner's contact data. 165 | security: 166 | - vehicle_oauth: 167 | - 'utm.nasa.gov_read.publicsafety' 168 | parameters: 169 | - in: path 170 | name: "uvin" 171 | type: "string" 172 | required: true 173 | description: "Specifies the vehicle id" 174 | - in: header 175 | name: "Accept" 176 | type: "string" 177 | required: true 178 | description: "Must be 'application/json'" 179 | responses: 180 | 200: 181 | description: "Successful" 182 | schema: 183 | $ref: '#/definitions/OrgData' 184 | definitions: 185 | OrgData: 186 | type: object 187 | properties: 188 | orgName: 189 | type: string 190 | example: "Beer Buzz, LLC" 191 | POC: 192 | type: object 193 | properties: 194 | name: 195 | type: string 196 | tel: 197 | type: string 198 | email: 199 | type: string 200 | VehiclePost: 201 | type: object 202 | properties: 203 | uvin: 204 | type: string 205 | format: uuid 206 | maxLength: 36 207 | minLength: 36 208 | example: "00000000-0000-0000-0000-000000000000" 209 | vehicleTypeId: 210 | type: string 211 | format: uuid 212 | maxLength: 36 213 | minLength: 36 214 | example: "00000000-0000-0000-0000-000000000000" 215 | createdTS: 216 | type: string 217 | example: "2018-01-14 02:33:01.73454" 218 | nNumber: 219 | type: string 220 | example: "N98765" 221 | faaNumber: 222 | type: string 223 | example: "FA1231232132131" 224 | vehicleName: 225 | type: string 226 | description: A vehicle name identifier that has been given to the vehicle instance 227 | example: "FlyingV" 228 | VehicleReg: 229 | type: object 230 | properties: 231 | uvin: 232 | type: string 233 | format: uuid 234 | maxLength: 36 235 | minLength: 36 236 | example: "00000000-0000-0000-0000-000000000000" 237 | date: 238 | type: string 239 | example: "2018-01-14 02:33:01.73454" 240 | registeredBy: 241 | type: string 242 | example: "registeredBy" 243 | nNumber: 244 | type: string 245 | example: "N98765" 246 | faaNumber: 247 | type: string 248 | example: "FA1231232132131" 249 | vehicleName: 250 | type: string 251 | description: A vehicle name identifier that has been given to the vehicle instance 252 | example: "FlyingV" 253 | manufacturer: 254 | type: string 255 | description: Name of the manufacturer 256 | example: "Lockheed Martin" 257 | model: 258 | type: string 259 | description: Model name 260 | example: "Indago" 261 | class: 262 | type: string 263 | description: Vehicle class 264 | example: "Multi-Rotor" 265 | accessType: 266 | type: string 267 | description: Designates whether or not the vehicle type is publically available. If private it can only be viewed by the manufacturer 268 | example: "public" 269 | vehicleTypeId: 270 | type: string 271 | format: uuid 272 | maxLength: 36 273 | minLength: 36 274 | example: "00000000-0000-0000-0000-000000000000" 275 | org-uuid: 276 | type: string 277 | format: uuid 278 | maxLength: 36 279 | minLength: 36 280 | example: "00000000-0000-0000-0000-000000000000" 281 | --------------------------------------------------------------------------------