info: description: >- This file contains the core UTM models as OpenAPI 2.0 compliant definitions. Some key caveats when using/referencing this API: 1. The API on its own is insufficeint to develop a USS or other UTM component. For example, the USS Specification is needed to understand how and when to use the various endpoints and provides more details on security features that cannot be captured in the API docs. 2. There is not a unified time synchronization approach in UTM currently. As such, times provided from one server MUST NOT be validated against each other. For example, if a sending server states that a data element was sent at 10:00:23, but the receiving server thinks it is currently 10:00:22, the receiving server must not reject the data submission. As we develop and roll out the time synchronization scheme for the USS Network, we will add appropriate validation requirements to the API documentation. 3. On the contrary, times must be validated for consistency within a given data submission. For example, if a server states that it sends a data instance at 10:00:23 and one of the other data elements states that a measurement was performed at 10:00:24, then the receiving server must reject that data submission. Some of these checks are explictly stated in the descriptions below. If you recognize any such checks that are not documented, please submit an issue report on github. 4. These token SUBJECT validations are required for security. For PUT Operation to modify an existing operation, the token SUBJECT claim upon modification MUST equal the token SUBJECT claim for the initial Operation. For PUT Message associated with an Operation gufi, the token SUBJECT claim used for PUT Message MUST equal the token SUBJECT claim for the initial operation. This check is performed if the initial operation exists, so as to not preclude receiving emergency messages. For PUT Position associated with an Operation gufi, the token SUBJECT claim used for PUT Position MUST equal the token SUBJECT claim for the initial operation. This check is performed only if the initial operation exists, so as to not preclude receiving emergency position reports. version: v4 title: UTM models swagger: "2.0" paths: '/no-paths': put: responses: '410': description: >- Gone. Not implemented. Will not be implemented. Path included for proper use by automated tooling. definitions: timestamp: description: >- Timestamps MUST follow the guidance set forth in RFC3339. This RFC defines a profile for ISO8601 forcused on interoperability of Internet based systems. This profile makes certain design decisions based on reducing rarely used options, elimination of redundant information, and overall simplicity. From these goals and insight from building interoperable systems, RFC3339 provides a grammar for timestamps. Please see https://tools.ietf.org/html/rfc3339#section-5.6 for that grammer and the sections preceding that grammar for more detailed discussion. For UTM, we have attempted to reduce the grammar to a regular expression, but this does not take into account all rules. For example, a valid timestamp should not allow 30 days in February, but this is not in the regular expression. Likewise, leap years are not captured in the regular expression. Thus it is possible for a timestamp to satisfy this RE, but still not be valid and, thus, be rejected by some components of UTM. Note that this UTM format specifies millisecond precision for all time stamps. This is why the min and max length are fixed at 24. Note that this UTM format specifies UTC time indicated by a trailing 'Z'. Note taht this UTM format specifies date and time separation with a 'T'. type: "string" format: "iso8601" minLength: 24 maxLength: 24 pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: "2015-08-20T14:11:56.118Z" uuid: description: >- Currently, this is a UUID version 4. These UUIDs have a well-defined regular expression. However, beyond meeting the regular expression, there is an expectation that the numbers are generated appropriately in terms of the approach to psuedo-random number generation. More details in the USS Specification document in this regard. UUIDs are used in several models and serve as primary keys in many cases. In all cases, unless otherwised specified, UUIDs are generated by a USS (or FIMS) prior to sending to another USS (or FIMS). Thus one entity does not add data elements (like a UUID primary key) to data originating from another entity. If ordering or sorting is required, the sort order is lexicographic as defined in RFC4122: UUIDs, as defined in this document, can also be ordered lexicographically. For a pair of UUIDs, the first one follows the second if the most significant field in which the UUIDs differ is greater for the first UUID. The second precedes the first if the most significant field in which the UUIDs differ is greater for the second UUID. type: "string" format: "uuidv4" minLength: 36 maxLength: 36 pattern: >- "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" data_accessibility: description: >- Each data member of each model will be tagged with a value representing its accessibility level. This enum provides the potential values. Each value of the enum implies AT LEAST the accessibility of the previous value. With the ordering: PUBLIC <= OPERATIONAL <= SAFETY <= SPECIAL The most restrictive value possible will be chosen for each data member while still meeting overall objectives of the system. Finding the correct values will likely be an on-going process. The values will be a first cut in the research platform version of UTM. The server receiving a request for data will need to filter the results based on the authorization presented by the requesting server. Further details to be developed later. type: string enum: - PUBLIC - OPERATIONAL - SAFETY - SPECIAL severity: description: >- The severity level of a UTMMessage. This severity labeling may be used by other components within UTM as well. The labels are ordered such that they may be given priority handling by software systems and human users. **EMERGENCY > ALERT > CRITICAL > WARNING > NOTICE > INFORMATIONAL** In relation to a UTMMessage, the severities may be interpreted as follows. 1. **EMERGENCY** There is an *immediate* impact to the safety of other air operations, the safety of people, or the safety of structures on the ground. Actions to mitigate required by other operations. 2. **ALERT** There may be an impact to the safety of other air operations, the safety of people, or the safety of structures on the ground. Actions to mitigate required by other operations. 3. **CRITICAL** Without mitigations by the affected operation, the situation may rise to an emergency in the near future. 4. **WARNING** There is a contained issue that may result in the loss of aircraft. No immediate or likely effect to other operations, people on the ground, or structures. 5. **NOTICE** This issue is provided for situational awareness. Planning by operators and USSs may be affected. 6. **INFORMATIONAL** This issue is provided for situational awareness. Note that this approach leverages RFC 5424: "The Syslog Protocol." By taking this approach, there is the possibility of formalizing UTMMessaging with more elements of the RFC to allow for compatibility with other logging systems. https://tools.ietf.org/html/rfc5424 type: string enum: - EMERGENCY - ALERT - CRITICAL - WARNING - NOTICE - INFORMATIONAL PersonOrOrganization: description: >- From FIXM 4.1: "An identifiable, responsible entity that can be either a natural person or an organization." type: object xml: name: PersonOrOrganizationType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: false externalDocs: description: See FIXM 4.1.0 for further information. url: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/Organization_xsd.html#PersonOrOrganizationType required: - name - email_addresses - phone_numbers properties: name: description: >- The full official name of the Person, State, Organisation, Authority, aircraft operating agency, handling agency etc. [FIXM] type: string minLength: 1 maxLength: 60 externalDocs: description: See FIXM 4.1.0 for further information. url: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/Types_xsd.html#TextNameType xml: name: TextNameType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: true email_addresses: description: >- An array of email addresses. To establish best practices, the order of the email addresses in the array should indicate the order that they should be used. Note that we do not include a regular expression for email addresses. Such a RE is quite unweildy if it attempts to be complete. The responsibility is on the USS providing the email address to ensure it is valid and operational. Several sources on the Internet can be found discussing email REs. Limiting email length to 254 per well-supported discussion here: https://stackoverflow.com/questions/386294/what-is-the-maximum-length-of-a-valid-email-address type: array minItems: 1 maxItems: 5 items: type: string format: email maxLength: 254 externalDocs: description: See FIXM 4.1.0 for further information. url: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/Address_xsd.html#OnlineContactType xml: name: OnlineContactType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: true phone_numbers: description: >- An array of phone numbers. To establish best practices, the order of the phone numbers in the array should indicate the order that they should be used. type: array minItems: 1 maxItems: 5 items: type: string format: phone-number minLength: 1 maxLength: 500 pattern: (\+)?[0-9\s\-\(\)]+ externalDocs: description: See FIXM 4.1.0 for further information. url: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/Address_xsd.html#TextPhoneType xml: name: TextPhoneType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: true comments: description: >- Any additional coments related to contact information. Optional. May not have a clean FIXM equivalent, but may be useful in some UTM contexts. type: string maxLength: 1000 minLength: 1 Altitude: type: object required: - altitude_value - vertical_reference - units_of_measure properties: altitude_value: description: >- The numeric value of the altitude. Note that min and max values are added as a sanity check. As use cases evolve and more options are made available in terms of units of measure or reference systems, these bounds should be re-evaluated. type: number format: double minimum: -8000.0 exclusiveMinimum: false maximum: 100000.0 exclusiveMaximum: false vertical_reference: description: >- A code indicating the reference for a vertical distance. See AIXM 5.1 and FIXM 4.1.0. Currently, UTM only allows WGS84 with no immediate plans to allow other options. FIXM and AIXM allow for 'SFC' which is equivalent to AGL. externalDocs: description: See FIXM 4.1.0 for further information. url: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/Measures_xsd.html#VerticalReferenceType xml: name: VerticalReferenceType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: false type: string enum: - W84 units_of_measure: description: >- The reference quantities used to express the value of altitude. See FIXM 4.1. Currently, UTM only allows feet with no immediate plans to allow other options. FIXM allows for feet or meters. externalDocs: description: See FIXM 4.1.0 for further information. url: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/UnitsOfMeasure_xsd.html#UomHeightType xml: name: UomHeightType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: false type: string enum: - FT source: description: >- Experimental field for testing and discussion to determine applicability. type: string enum: - ONBOARD_SENSOR - OTHER Operation: type: object required: - gufi - uas_registrations - uss_name - faa_rule - state - contact - controller_location - operation_volumes - contingency_plans - submit_time - update_time - metadata properties: gufi: type: string format: uuid maxLength: 36 minLength: 36 x-utm-data-accessibility: PUBLIC pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" uss_name: description: >- Identity of the USS. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string maxLength: 250 minLength: 4 x-utm-data-accessibility: PUBLIC example: utmbeta.arc.nasa.gov discovery_reference: description: >- An identifier that supplies information about the USS from the discovery perspecitve. This field is currently vague due to research on the appropriate discovery approach. It will be tightened when an operational system decides on the approach to discovery. For Gridded USS Discovery, this should be an x,y,z string where x and y are the coords of the grid and z is the zoom level. For example: "110,117,10" For FIMS Discovery, this should be the uss_instance_id which is a UUID. type: string minLength: 5 maxLength: 36 example: "110,117,10" x-utm-data-accessibility: PUBLIC submit_time: description: >- Time that this Operation was first announced to the USS Network in any way. For GUD, this means when you first write to the grid. For traditional discovery, this means the first time you announce to your LUN. The submit_time value MUST remain constant for each recipient of the announcement since this value is potentially part of a signature of the Operation plan in some cases. So, when data (or references to the data) are written to the grid, the same data are to be sent, as required, to other stakeholders (e.g. other USSs). This means that if there is a 500ms difference in the time that you send and get confirmation from the grid, you DO NOT update the submit_time when sending to the USSs after that. When the operation is announced for the first time, update_time MUST be equal to submit_time. When an operation is modified (updated), update_time MUST be greater than submit_time. Similarly, for traditional discovery, if there is a delay in sending the data to one LUN member versus another, this field is NOT updated in between as we want each stakeholder to ultimately receive the same data and (potentially) the same signature of the data. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' update_time: description: >- A timestamp set by the USS any time the state of the operation is updated within the USS Network. An update may be minor or major, but if/when te Operation is shared in the USS Network as a PUT to its LUN, update_time must reflect the time that update was provided. When the operation is announced for the first time, update_time MUST be equal to submit_time. When an operation is modified (updated), update_time MUST be greater than submit_time. THe update_time value MUST be constant for each update data exchange. This means that all stakeholder systems have the same value for update_time even if, for example, one USS receives the update later than others due to HTTP retrys or is provided as a GET for this Operation. This field is set and maintained by the USS managing the Operation and is communicated to other USSs. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' aircraft_comments: description: >- Informative text about the aircraft. Not used by the UTM System. Only for human stakeholders. type: string default: NOT PROVIDED x-utm-data-accessibility: SAFETY maxLength: 1000 flight_comments: description: >- Informative text about the operation. Not used by the UTM System. Only for human stakeholders. type: string default: NOT PROVIDED x-utm-data-accessibility: SAFETY maxLength: 1000 volumes_description: description: >- Informative text about the operational volumes. Not used by the UTM System. Only for human stakeholders. type: string default: NOT PROVIDED x-utm-data-accessibility: SAFETY maxLength: 1000 uas_registrations: description: >- The registration data for the vehicle(s) to be used in this Operation. Note that this is an array to allow for future operations involving multiple vehicles (e.g. 'swarms' or tandem inspections). The uas_registrations array MUST NOT be used as a list of potential vehicles for this Operation. If the vehicle data changes prior to an Operation, an update to the plan may be submitted with the updated vehicle information. Providing multiple uas_registrations in this manner implies that all vehicles will conform to the provided operation volumes. type: array maxItems: 1000 minItems: 1 items: $ref: '#/definitions/UasRegistration' x-utm-data-accessibility: SAFETY airspace_authorization: type: string format: uuid maxLength: 36 minLength: 36 x-utm-data-accessibility: SAFETY pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" flight_number: description: Optional. For use by USS for identification purposes. type: string maxLength: 100 x-utm-data-accessibility: OPERATIONAL contact: description: >- Contact information for this Operation. $ref: '#/definitions/PersonOrOrganization' x-utm-data-accessibility: SAFETY state: description: >- The current state of the operation. Must be maintained by the USS. Some additional details in the USS Specification. 0. PROPOSED This operation is not yet ACCEPTED. It may be awaiting information from the operator, it may be in conflict with another ACCEPTED or ACTIVATED operation and undergoing a negotiation process, or for some other reason it is not yet able to be declared ACCEPTED. 1. ACCEPTED This operation has been deemed ACCEPTED by the supporting USS. This implies that the operation meets the requirements for operating in the airspace based on the type of operation submitted. 2. ACTIVATED This operation is active. The transition from ACCEPTED to ACTIVATED is not an announced transition. The transition is implied based on the submitted start time of the operation (i.e. the effective_time_begin of the first OperationVolume). Note that an ACTIVATED operation is not necessarily airborne, but is assumed to be "using" the OperationVolumes that it has announced. 3. CLOSED This operation is closed. It is not airborne and will not become airborne again. If the UAS and the crew will fly again, it would need to be as a new operation. A USS may announce the closure of any operation, but is not required to announce unless the operation was ROGUE or NONCONFORMING. 4. NONCONFORMING See USS Specification for requirements to transition to this state. 5. ROGUE See USS Specification for requirements to transition to this state. If ordering of states is required for any purpose, they shall be ordered as follows: PROPOSED < ACCEPTED < ACTIVATED < CLOSED < NONCONFORMING < ROGUE type: string enum: - PROPOSED - ACCEPTED - ACTIVATED - CLOSED - NONCONFORMING - ROGUE x-utm-data-accessibility: OPERATIONAL controller_location: $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Point' x-utm-data-accessibility: SAFETY gcs_location: $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Point' x-utm-data-accessibility: SAFETY contingency_plans: description: >- An array of ContingencyPlans wherein this operation may land if needed/required during operation. Aids in planning and communication during the execution of a contingency. An Operation MUST have least one Contingency Plan (CP) per Operation Volume, therefore the CP list size must be greater than or equal to the OpVol list size. type: array maxItems: 250 minItems: 1 items: $ref: '#/definitions/ContingencyPlan' x-utm-data-accessibility: OPERATIONAL negotiation_agreements: description: >- An array of NegotiationAgreements to which the USS supporting this operation (in conjunction with the operator) has agreed. type: array maxItems: 250 minItems: 1 items: $ref: '#/definitions/NegotiationAgreement' x-utm-data-accessibility: OPERATIONAL faa_rule: description: |- 1. PART_107 The operation follows FAA rule 107. Submission of such operations is mandatory 2. PART_107X In general, operations are 107X if they are doing something that would require a waiver under current 107 rules. Submission of such operations is mandatory. 3. PART_101E Submission of 101E would be required if operation is within 5 statute miles of an airport. Optional otherwise. 4. OTHER Placeholder for other types of operations. type: string enum: - PART_107 - PART_107X - PART_101E - OTHER x-utm-data-accessibility: OPERATIONAL priority_elements: $ref: '#/definitions/PriorityElements' x-utm-data-accessibility: OPERATIONAL operation_volumes: description: >- The actual geographical information for the operation. A note on "intersection": Note 2: All of the terms "crosses", "within", "touches" imply intersection. I can track down a source for this definition (probably OGC), but for now, you can see it illustrated in the description for PostGIS intersection: https://postgis.net/docs/ST_Intersects.html Validation of the array must include the following checks: 1. The array of operation volumes MUST have minimum length of 1. 2. The array of operation volumes MUST have maximum length of 250. 3. Each operation volume MUST have non-zero 4D volume (i.e. each of the 4 dimensions much be > 0 in magnitude). 4. Volume intersection must pass the following checks: a. When ordered by ordinal values, a succeeding operation volume must have a 2D or 3D intersection in 3D space with its immediately preceding operation volume. Note that a 2D intersection in 3D space implies two volumes that "touch" and the intersection has 2D area. Sharing just an edge would not qualify. 3D volumes that don't touch at all would not qualify, even if they would intersect when projected into 2D space (e.g. if "looking down" on the two volumes). b. When ordered by ordinal values, a succeeding operation volume must have a non-negative temporal intersection with its immediately preceding operation volume (Note we'd calculate this by t1-t2 where t1 is the preceding operation volume end time and t2 is the succeeding operation volume start time.). c. When ordered by ordinal values, a succeeding operation volume must have either a non-zero volume (3D) intersection OR a positive temporal intersection. (Note this is a logical "OR" so it may have both intersection types... i.e. it is not an "exclusive OR"). 5. Each spatial dimension of an op vol's bounding box must have length less than 6000ft (should discuss with partners this value). This is a sanity check against excessively large volumes. Need to be careful here as there may be legitimate use cases wherein large volumes are required/allowed, but we want to encourage efficient planning and protect against misuse of the shared airspace. 6. The planned duration of an op vol must be less than 120 minutes. Again, need to be careful to not damage legitimate use cases, but need to protect against misuse/poor planning. For long duration missions, it may be reasonable to have them replan or to have volumes with the same geog and long time values that slightly intersect. 7. The start time of an operation volume other than the first in the array must be greater than or equal to the start time of its immediately preceding operation volume. (note this probalby should be #4 or so, bumping the others down, but I didn't want to cause confusion in case implementers are referencing these checks somewhere by number.) type: array maxItems: 250 minItems: 1 items: $ref: '#/definitions/OperationVolume' x-utm-data-accessibility: OPERATIONAL metadata: $ref: >- https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-metadata.yaml#/definitions/EventMetadata x-utm-data-accessibility: OPERATIONAL PriorityElements: description: >- Data elements used to describe the status of priority operation. Nominal operations need not include these data. 'priority_status' of PUBLIC_SAFETY or INFLIGHT_EMERGENCY accepts 'priority_level' values EMERGENCY, ALERT and CRITICAL only. 'priority_status' of NONE accepts 'priority_level' values WARNING, NOTICE and INFORMATIONAL only. The 'priority_level' values EMERGENCY, ALERT and CRITICAL should be used based on impact to other operations and safety of people and property on the ground. type: object required: - priority_level - priority_status properties: priority_level: $ref: '#/definitions/severity' x-utm-data-accessibility: OPERATIONAL priority_status: type: string description: >- If a PUBLIC_SAFETY operation is PUT to any endpoint, the correct scope will be required. Any USS may PUT an EMERGENCY_* with non-priority scopes. EMERGENCY_AIRBORNE_IMPACT should be used when there is significant risk to other aircraft, but little risk to any people or property on the ground. EMERGENCY_GROUND_IMPACT should be used when there is significant risk to people and/or property on the ground, but little risk of airborne collision. EMERGENCY_AIR_AND_GROUND_IMPACT should be used when there is significant risk to aircraft AND people/property on the ground. NONE should only be used to indicate that an operation that previously had a priority status now has no priority status. enum: - NONE - PUBLIC_SAFETY - EMERGENCY_AIRBORNE_IMPACT - EMERGENCY_GROUND_IMPACT - EMERGENCY_AIR_AND_GROUND_IMPACT x-utm-data-accessibility: OPERATIONAL OperationVolume: type: object required: - ordinal - volume_type - effective_time_begin - effective_time_end - min_altitude - max_altitude - operation_geography - beyond_visual_line_of_sight properties: ordinal: description: >- This integer represents the ordering of the operation volume within the set of operation volumes. Need not be consecutive integers. Note that the max and min are larger than the allowed number of op vols. This is by design to allow implementers to use this field in a flexible manner. For example, in replanning, it may be useful to have a larger set of integers available and to space them by large offsets. type: integer minimum: -1000 exclusiveMinimum: false maximum: 99999 exclusiveMaximum: false x-utm-data-accessibility: OPERATIONAL volume_type: description: >- More description later. type: string enum: - TBOV - ABOV default: ABOV x-utm-data-accessibility: OPERATIONAL near_structure: description: Is this operation volume within 400' of a structure? type: boolean default: false x-utm-data-accessibility: SAFETY effective_time_begin: description: >- Earliest time the operation will use the operation volume. It must be less than effective_time_end. effective_time_begin < effective_time_end MUST be true. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' effective_time_end: description: >- Latest time the operation will done with the operation volume. It must be greater than effective_time_begin. effective_time_begin < effective_time_end MUST be true. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' actual_time_end: description: >- Time that the operational volume was freed for use by other operations. Should be populated and stored by the USS. actual_time_end MUST satisfy: actual_time_end > effective_time_begin whenever actual_time_end is not null. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' min_altitude: description: >- The minimum altitude for this operation in this operation volume. The following MUST hold: min_altitude.altitude_value < max_altitude.altitude_value $ref: '#/definitions/Altitude' x-utm-data-accessibility: OPERATIONAL max_altitude: description: >- The maximum altitude for this operation in this operation volume. The following MUST hold: min_altitude.altitude_value < max_altitude.altitude_value $ref: '#/definitions/Altitude' x-utm-data-accessibility: OPERATIONAL operation_geography: $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Polygon' x-utm-data-accessibility: OPERATIONAL beyond_visual_line_of_sight: description: >- Describes whether any portion of the operation volume is beyond the visual line of sight of the RPIC. type: boolean x-utm-data-accessibility: OPERATIONAL ContingencyPlan: type: object required: - contingency_id - contingency_polygon - contingency_location_description - contingency_cause - contingency_response - valid_time_begin - valid_time_end properties: contingency_id: description: >- A positive integer unique amongst the set of Contingencies for this operation. The integers may be ordered by some scheme, but this is not required. type: integer format: int32 minimum: 1 exclusiveMinimum: false maximum: 1000 exclusiveMaximum: false example: 1 x-utm-data-accessibility: OPERATIONAL contingency_cause: type: array items: description: >- A cause that necessitates a contingency response. In planning an operation, this array of values represents the various causes that may necessitate the provided contingency response. 1. LOST_C2_UPLINK The operation has lost command or control uplink to the vehicle. 2. LOST_C2_DOWNLINK The operation has lost downlinks from the vehicle. 3. LOST_NAV The vehicle no longer has sufficient navigation sources. 4. LOST_SAA The vehicle's sense and avoid solution is no longer reliable. 5. LOW_FUEL The vehicle does not have enough power to complete its mission. Still enough fuel to safely land or potentially return to base. 6. NO_FUEL The vehicle is either completely without fuel or has only enough fuel to land immediately. 7. MECHANICAL_PROBLEM The vehicle is experiencing a mechanical problem necessitating initiation of a contingency response. 8. SOFTWARE_PROBLEM The vehicle or some component of the required platform ground equipment is experiencing a software problem. 9. ENVIRONMENTAL There are conditions in the environment necessitating initiation of a contingency response. Generally these will be weather-related phenomena. 10. SECURITY There is a security incident interrupting this operation. 11. TRAFFIC The density or type of air traffic near the vehicle necessitated a contingency response. 12. LOST_USS The operation has lost at least some portion of expected USS services. 13. OTHER Some cause not captured in any other category. 14. ANY This category should only be used within an operation plan when a particular contingency response is appropriate for any contingency cause. type: string enum: - LOST_C2_UPLINK - LOST_C2_DOWNLINK - LOST_NAV - LOST_SAA - LOW_FUEL - NO_FUEL - MECHANICAL_PROBLEM - SOFTWARE_PROBLEM - ENVIRONMENTAL - SECURITY - TRAFFIC - LOST_USS - OTHER - ANY example: "LOW_FUEL" x-utm-data-accessibility: OPERATIONAL contingency_response: description: >- The type of contingency response. 1. LANDING The operation will be landing by targeting the contingency_polygon. 2. LOITERING The operation will loiter at the contingency_polygon at the specified loiter_altitude. 3. RETURN_TO_BASE The operation will return to base as specified by the contingency_polygon. The USS may issue an update to the operation plan to support this maneuver. 4. OTHER Additional details should be provided in free_text. If this gets used often for similar events, API will be updated with new enum value. type: string enum: - LANDING - LOITERING - RETURN_TO_BASE - OTHER example: "LANDING" x-utm-data-accessibility: OPERATIONAL contingency_polygon: description: >- If LANDING or RETURN_TO_BASE contingency_repsonse, then this is the area on the ground that the UA will be targeting for a landing. The polygon should be large enough to provide high confidence (for some TBD value of "high") that the vehicle will land within it, but hopefully be no larger (for some TBD value of hopefully). If LOITERING, this is the polygon the UA will stay within at the loiter_altitude. $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Polygon' x-utm-data-accessibility: OPERATIONAL loiter_altitude: description: >- The altitude for this contingency. Relevant and required for the LOITERING contingency_type, ignored for all other types. Note: may need to split this into a min_loiter_altitude and a max_loiter_altitide in the future to provide a full 4D loiter volume. $ref: '#/definitions/Altitude' x-utm-data-accessibility: OPERATIONAL relative_preference: description: >- Optional numerical value that can be used in ranking the preference of this Contingency versus any other within the set of Contingency for this operation. This may be thought of as a ranking of the potential landing sites with all other factors being held equal, though dynamic conditions will likely play a role in adjusting this ranking in real time by the USS or Operator. For example, one Contingency may be significantly further from the operation at a given time and, thus, would be less preferred than it might be otherwise. Further interpretation of this field is left to the operator and USS. type: number format: double minimum: 0 example: 2 x-utm-data-accessibility: OPERATIONAL contingency_location_description: description: >- Description of the contingency location. PREPROGRAMMED: location that is determined prior to launch and programmed onto the UA OPERATOR_UPDATED: location that is (or will be) updated during operation by operator (e.g., sent to UA) UA_IDENTIFIED: location that is identified to be safe to land by the UA itself OTHER: location does not fit any of the defined categories type: string enum: - PREPROGRAMMED - OPERATOR_UPDATED - UA_IDENTIFIED - OTHER example: "PREPROGRAMMED" x-utm-data-accessibility: SAFETY relevant_operation_volumes: description: >- In the planning stage of an operation, this array may be populated with ordinals that correspond to the ordinal values supplied with each OperationVolume. This is an indicator that this particular ContingencyPlan is valid for use when the operation is active in any of the particular noted OperationVolumes. For example, you may define 1 operation volume and 3 different contingency plans specifying the causes that would transition the operation into LANDING, LOITERING or RETURN_TO_BASE. See also ContingencyPlan.relevant_preference and Operation.contingency_plans. type: array items: type: integer format: int32 x-utm-data-accessibility: OPERATIONAL valid_time_begin: description: >- Time that this location is expected to be first available. For example, if an operation begins at 1100, but this location is not available until 1105 at the earliest, then this field could indicate that fact. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' valid_time_end: description: >- Time that this location is expected to become unavailable. For example, if an operation begins at 1100, but this location becomes closed for some reason at 1105, then this field could indicate that fact. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' free_text: description: >- To be used for additional comments as needed. For human use, not for automating any process. type: string minLength: 0 maxLength: 1000 x-utm-data-accessibility: OPERATIONAL Position: type: object required: - enroute_positions_id - altitude_gps - altitude_num_gps_satellites - gufi - hdop_gps - location - time_measured - time_sent - track_bearing - track_bearing_reference - track_bearing_uom - track_ground_speed - track_ground_speed_units - uss_name - vdop_gps properties: altitude_gps: description: >- The altitude as measured via a GPS device on the aircraft. $ref: '#/definitions/Altitude' x-utm-data-accessibility: OPERATIONAL altitude_num_gps_satellites: type: integer format: int32 description: Number of satellites used in calculating the altitude. minimum: 0 exclusiveMinimum: false x-utm-data-accessibility: SAFETY comments: type: string minLength: 0 maxLength: 1000 x-utm-data-accessibility: OPERATIONAL enroute_positions_id: description: >- Each position will be assigned a UUIDv4 by the USS managing the referenced operation. Any system recieving this position object MUST NOT modify this identifier. type: string format: uuid maxLength: 36 minLength: 36 x-utm-data-accessibility: PUBLIC pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" gufi: description: >- Each operation has an GUFI assigned upon submission. Required upon PUTting a new position. It is a JSON string, but conforms to the UUID version 4 specification type: string format: uuid maxLength: 36 minLength: 36 x-utm-data-accessibility: PUBLIC pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" hdop_gps: type: number format: double description: The horizontal dilution of precision as provided by the onboard GPS. minimum: 0 x-utm-data-accessibility: SAFETY location: $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Point' x-utm-data-accessibility: PUBLIC time_measured: description: >- The time the position was measured. Likely the time provided with the GPS position reading. Position time_measured < time_sent MUST be true. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: PUBLIC pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' time_sent: description: >- The time the position was sent by the USS as measured by that USS's system time. Position time_measured <= time_sent MUST be true. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' track_bearing: type: number format: double description: >- The direction of travel relative to track_bearing_reference in degrees. Position track_bearing value MUST be >= 0.0 and < 360.0. Note that FIXM allows for the value of 360.0, while UTM does not. The reason is for clarity by not allowing two numbers (0.0 and 360.0) to represent the same measurement. minimum: 0 exclusiveMinimum: false maximum: 360 exclusiveMaximum: true x-utm-fixm-reference: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/Measures_xsd.html#BearingType xml: name: BearingType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: false x-utm-data-accessibility: OPERATIONAL track_bearing_reference: type: string enum: - TRUE_NORTH - MAGNETIC_NORTH default: TRUE_NORTH description: >- A code indicating the direction of the zero bearing. TRUE_NORTH This value indicates that the direction is relative to True North. MAGNETIC_NORTH This value indicates that the direction is relative to Magnetic North. This field is equivalent to x-utm-fixm-reference: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/Measures_xsd.html#BearingType xml: name: ZeroBearingTypeType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: true x-utm-data-accessibility: OPERATIONAL track_bearing_uom: type: string enum: - DEG description: >- The reference quantities used to express the value of angles. [ISO 19103, chapter 6.5.7.10] As in FIXM, only a single option is provided (degrees). Including this field allows for clarity in the data provided and allows for the potential of other units of measure in the future. x-utm-fixm-reference: https://www.fixm.aero/releases/FIXM-4.1.0/doc/schema_documentation_core/UnitsOfMeasure_xsd.html#UomAngleType xml: name: UomAngleType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: true x-utm-data-accessibility: OPERATIONAL track_ground_speed: type: number format: double description: >- Ground speed int the direction of travel, in units as specifed by track_ground_speed_units. Position track_ground_speed MUST be >= 0.0. minimum: 0 exclusiveMinimum: false x-utm-data-accessibility: OPERATIONAL track_ground_speed_units: type: string enum: - KT description: >- The reference quantities used to express the value of ground speed as provided in track_ground_speed. KT: Knots. FIXM allows KT (knots) and KM_H (kilometers per hour) but we only allow the KT choice. x-utm-fixm-reference: https://www.fixm.aero/releases/US_Ext-4.2.0/doc/schema_documentation_us_extension/UnitsOfMeasure_xsd.html#UomGroundSpeedType xml: name: UomGroundSpeedType namespace: https://www.fixm.aero/nas/4.1 prefix: fb attribute: true x-utm-data-accessibility: OPERATIONAL uss_name: description: >- The name of the entity providing UAS Support Services. Populated by the service discovery system based on credential information provided by the USS. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string minLength: 4 maxLength: 250 x-utm-data-accessibility: OPERATIONAL discovery_reference: description: >- An identifier that supplies information about the USS from the discovery perspecitve. This field is currently vague due to research on the appropriate discovery approach. It will be tightened when an operational system decides on the approach to discovery. For Gridded USS Discovery, this should be an x,y,z string where x and y are the coords of the grid and z is the zoom level. For example: "110,117,10" For FIMS Discovery, this should be the uss_instance_id which is a UUID. type: string minLength: 5 maxLength: 36 example: "110,117,10" x-utm-data-accessibility: OPERATIONAL vdop_gps: type: number format: double description: The vertical dilution of precision as provided by the onboard GPS. minimum: 0 x-utm-data-accessibility: SAFETY example: altitude_gps: altitude_value: 1239.77 vertical_reference: "W84" units_of_measure: "FT" source: "ONBOARD_SENSOR" altitude_num_gps_satellites: 22 enroute_positions_id: "d10cd900-086f-43c7-9d6c-BAADCAFEF00D" gufi: "00000000-0000-4444-8888-000000000000" hdop_gps: 1.117 time_measured: "2016-10-04T09:15:40.727Z" time_sent: "2016-10-04T09:15:40.727Z" track_bearing: 33.44 track_bearing_reference: "MAGNETIC_NORTH" track_bearing_uom: "DEG" track_ground_speed: 33.33 track_ground_speed_units: "KT" uss_name: "uss.provider321.net" vdop_gps: 0.932 location: type: Point coordinates: - -122.05635935068132 - 37.41436490284069 UTMMessage: required: - message_id - uss_name - time_sent - severity - message_type - callback type: object description: >- A UTM message. Used to make other stakeholders aware about an issue. The noted required fields are required for all UTMMessages, however there are fields that are contextually required depending on the type of message. Please see the descriptions provided with each field. properties: message_id: type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" uss_name: description: >- A name identifying the originator of this message. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string minLength: 4 exclusiveMinimum: false maxLength: 250 exclusiveMaximum: false discovery_reference: description: >- An identifier that supplies information about the USS from the discovery perspecitve. This field is currently vague due to research on the appropriate discovery approach. It will be tightened when an operational system decides on the approach to discovery. For Gridded USS Discovery, this should be an x,y,z string where x and y are the coords of the grid and z is the zoom level. For example: "110,117,10" For FIMS Discovery, this should be the uss_instance_id which is a UUID. type: string minLength: 5 maxLength: 36 example: "110,117,10" gufi: description: The GUFI for the operation referenced in this message. UUIDv4. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" time_sent: description: >- Time the message was generated by the origin. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' severity: $ref: '#/definitions/severity' message_type: description: >- The type of message. THe 'gufi' field is required for all message_types except OTHER_SEE_FREE_TEXT. 1. UNPLANNED_LANDING This operation had to land earlier than expected and/or at a location other than was originally planned. UNPLANNED_LANDING MUST have severity ALERT if any damage or potential damage or injury other than to the UAS itself. CRITICAL otherwise. 2. UNCONTROLLED_LANDING This operation had an uncontrolled landing either at the originally planned landing location or another location. UNCONTROLLED_LANDING MUST be sent with severity ALERT if any damage or potential damage or injury other than to the UAS itselft. CRITICAL otherwise. 3. OPERATION_NONCONFORMING This operation has entered the NONCONFORMING state. Must be sent to LUN anytime operation transitions to this state. OPERATION_NONCONFORMING MUST be sent with severity ALERT if the operation is expected to intersect another operation plan or unauthorized airspace. OPERATION_NONCONFORMING MUST be sent with severity EMERGENCY if already intersecting another operation or if already entered unauthorized airspace. Otherwise CRITICAL. 4. OPERATION_ROGUE This operation has entered the ROGUE state. OPERATION_ROGUE MUST be sent anytime operation transitions to ROGUE state. OPERATION_ROGUE MUST be sent with severity ALERT if no current or immediate intersection with another operation or unauthorized airspace. EMERGENCY otherwise. 5. OPERATION_CONFORMING This operation was previously in the NONCONFORMING state and has transitioned back to the ACTIVE state. 'gufi' field is required with this message_type. 6. OPERATION_CLOSED OPERATION_CLOSED MUST be sent when and operation has entered the terminal CLOSED state. The operation will not again be active or in flight. OPERATION_CLOSED MUST be sent with severity NOTICE if transitioning from ACCEPTED to CLOSED. OPERATION_CLOSED MUST be sent with severity CRITICAL if transitioning from NONCONFORMING or ROGUE. 7. CONTINGENCY_PLAN_INITIATED A USS MUST send this message type to its LUN when a Contingency Plan begins. 8. CONTINGENCY_PLAN_CANCELLED A USS MUST send this message type to its LUN when a Contingency Plan ends or changes. 9. PERIODIC_POSITION_REPORTS_START The requestor wants position reports provided for the operation referenced in the 'gufi' field of this request. Reports must be provided as per the USS Specification. PERIODIC_POSITION_REPORTS_START MUST be sent with severity NOTICE. 10. PERIODIC_POSITION_REPORTS_END The requestor wants previously requested position reports to end. If this message is received without a corresponding PERIODIC_POSITION_REPORTS_START, the message response is TBD (200, 400, 401, 404, etc.). PERIODIC_POSITION_REPORTS_END MUST be sent with severity NOTICE. 11. UNAUTHORIZED_AIRSPACE_PROXIMITY An operation is within 3038 feet (almost 0.5nmi) from the boundary of unauthorized airspace (e.g., UVR/TFR, controlled airspace, airspace constraint). UNAUTHORIZED_AIRSPACE_PROXIMITY MUST be sent with severity WARNING. 12. UNAUTHORIZED_AIRSPACE_ENTRY An operation has breached the boundary and entered into unauthorized airspace (e.g., UVR/TFR, controlled airspace, airspace constraint). UNAUTHORIZED_AIRSPACE_ENTRY MUST be sent with severity CRITICAL. 13. OTHER_SEE_FREE_TEXT Messages that do not fit any of the otherwise defined categories. Should be used sparingly or with additional out-of-band description. OTHER_SEE_FREE_TEXT severity MUST be INFORMATIONAL or ALERT. Only use ALERT if there is some risk of injury or damage that would not be captured with any of the other enums. The following table summarizes the appropriate message_type-severity combinations. If a combination is not in the table, then it is not an allowable combination and must not be used within the USS Network. | message_type | severity | when | |--------------------------------- |--------------- |----------------------------------------------------------------------------- | | UNPLANNED_LANDING | ALERT | Damage to people or property (other than the UAS). | | UNPLANNED_LANDING | CRITICAL | If not ALERT. | | UNCONTROLLED_LANDING | ALERT | Damage to people or property (other than the UAS). | | UNCONTROLLED_LANDING | CRITICAL | If not ALERT. | | OPERATION_NONCONFORMING | EMERGENCY | Operation intersecting another op plan or unauthz'ed airspace. | | OPERATION_NONCONFORMING | ALERT | Operation expected to intersect another op plan or unauthz'ed airspace. | | OPERATION_NONCONFORMING | CRITICAL | If not EMERGENCY nor ALERT. | | OPERATION_ROGUE | EMERGENCY | Current/impending intersection with another op plan or unauthz'ed airspace. | | OPERATION_ROGUE | ALERT | If not EMERGENCY. | | OPERATION_CONFORMING | NOTICE | Always. | | OPERATION_CLOSED | CRITICAL | If operation was ROGUE or NONCONFORMING at any time. | | OPERATION_CLOSED | NOTICE | If not CRITICAL. | | CONTINGENCY_PLAN_INITIATED | ALERT | If operation expected to intersect another op plan or unauthz'ed airspace. | | CONTINGENCY_PLAN_INITIATED | CRITICAL | If not ALERT. | | CONTINGENCY_PLAN_CANCELLED | CRITICAL | Always. | | PERIODIC_POSITION_REPORTS_START | NOTICE | Always. | | PERIODIC_POSITION_REPORTS_END | NOTICE | Always. | | UNAUTHORIZED_AIRSPACE_PROXIMITY | WARNING | Always. | | UNAUTHORIZED_AIRSPACE_ENTRY | CRITICAL | Always. | | OTHER_SEE_FREE_TEXT | ALERT | Potential risk of damage to people or property other than this UAS. | | OTHER_SEE_FREE_TEXT | INFORMATIONAL | If not ALERT. | type: string enum: - UNPLANNED_LANDING - UNCONTROLLED_LANDING - OPERATION_NONCONFORMING - OPERATION_ROGUE - OPERATION_CONFORMING - OPERATION_CLOSED - CONTINGENCY_PLAN_INITIATED - CONTINGENCY_PLAN_CANCELLED - PERIODIC_POSITION_REPORTS_START - PERIODIC_POSITION_REPORTS_END - UNAUTHORIZED_AIRSPACE_PROXIMITY - UNAUTHORIZED_AIRSPACE_ENTRY - OTHER_SEE_FREE_TEXT last_known_position: $ref: '#/definitions/Position' contingency: $ref: '#/definitions/ContingencyPlan' prev_message_id: description: >- A message_id of a previously sent message that has relevance or context for this message. Example might be "CONTINGENCY_PLAN_CANCELLED" referencing the previous "CONTINGENCY_PLAN_INITIATED" message. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" free_text: description: >- Any additional information. Note that this is for human consumption. All time critical elements should be captured in the other data fields for easier consumption by other automated systems. type: string maxLength: 1000 callback: description: >- A base URL that the receiver would need to conduct further USS-USS communications in relation to the data provided in this message. Sample of use cases: 1. PERIODIC_POSITION_REPORTS_START: need to know where to send positions. 2. OPERATION_ROGUE: need to know where to request op and pos data. 3. CONTINGENCY_PLAN_INITIATED: need to know where to request op data. Since these use cases may require hitting different endpoints, only the base url is required in the callback field. The receiver would be responsible for determining which endpoint to use for follow up data exchanges. Note that "base URL" here implies the full path with protocol (only HTTPS allowed) upto where trailing USS-API endpoints would be applied. See example. type: string format: url example: "https://superutm.uss/nuss/uss" example: message_id: "00000000-0000-4444-8888-CAFEBEEFF00D" uss_name: "uss.provider321.net" time_sent: "2015-08-20T14:11:57.345Z" severity: "NOTICE" message_type: "OPERATION_CLOSED" gufi: "00000000-0000-4444-8888-FEEDDEADBEEF" free_text: "Cool flight, bro" callback: "https://uss.provider321.net/uss" UASVolumeReservation: description: >- An element defined by spatial and temporal bounds that affects UAS operations by limiting access to that 4D bounded volume. Formerly "ConstraintMessage". required: - message_id - uss_name - type - cause - geography - min_altitude - max_altitude - effective_time_begin - effective_time_end - permitted_uas properties: message_id: type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" uss_name: description: >- A name identifying the originator of this message. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string minLength: 4 exclusiveMinimum: false maxLength: 250 exclusiveMaximum: false type: description: >- The type of UVR. It is expected this list will grow as use cases are identified and cataloged. Currently there is only a differentiation between a dynamic restriction and a static advisory. There is no official guidance on the difference as of today. Roughly, the assumption is that static advisories would have a longer lead time and/or longer duration than a dynamic restriction. type: string enum: - DYNAMIC_RESTRICTION - STATIC_ADVISORY permitted_uas: description: >- The types of UAS operations that are permitted within the bound of the UVR. When used in conjunction with permitted_gufis, the filters are an 'OR' relationship. Any operation that matches either filter is allowed within the bounds of the UVR. This list of permitted_uas types is not to be considered a final version. It is provided to initiate discussion of how the filter should be defined. Duplicate strings not allowed in this array. If NOT_SET is included, then no other strings allowed in the array. type: array items: type: string enum: - NOT_SET - PUBLIC_SAFETY - SECURITY - NEWS_GATHERING - VLOS - SUPPORT_LEVEL - PART_107 - PART_101E - PART_107X - RADIO_LINE_OF_SIGHT minItems: 1 maxItems: 8 required_support: description: >- If the permitted_uas array contains "SUPPORT_LEVEL" this required_support field is required. This field describes the support required by an operation to continue to operate within or to enter the UVR. By remaining within or entering a UVR with the listed required support, the operator is attesting that it is using all elements listed in the required support array. To restate: the array of values in this field is an AND relationship, thus all elements must be utilized by each operation within such a UVR. If an operator does not have every support elements listed, then its operation must exit or avoid entry to the UVR. type: array items: type: string enum: - V2V - DAA - ADSB_OUT - ADSB_IN - CONSPICUITY - ENHANCED_NAVIGATION - ENHANCED_SAFE_LANDING permitted_gufis: description: >- The specific UAS operations that are permitted within the bounds of the UVR. When used in conjunction with permitted_uas, the filters are an 'OR' relationship. Any operation that matches either filter is allowed within the bounds of the UVR. The protocol for adding the appropriate GUFIs to this array needs to be discussed. This may be a chicken/egg problem that will have to be worked through. type: array items: type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" minItems: 0 maxItems: 100 example: - '00000000-0000-4444-8888-FEEDDEADFFFF' cause: description: >- The cause for the UVR. type: string enum: - WEATHER - ATC - SECURITY - SAFETY - MUNICIPALITY - OTHER geography: $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Polygon' effective_time_begin: description: >- The time that the UVR will begin to be in effect. UASVolumeReservation MUST satisfy effective_time_begin < effective_time_end. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' effective_time_end: description: >- The time that the UVR will cease to be in effect. UASVolumeReservation MUST satisfy effective_time_begin < effective_time_end. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' actual_time_end: description: >- Time that the constaint actually ceased being in effect. This value is likely used when a UVR ends early, but is not required. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' min_altitude: description: >- The minimum altitude of the UVR. UVR MUST satisfy min_altitude.altitude_value < max_altitude.altitude_value. $ref: '#/definitions/Altitude' max_altitude: description: >- The maximum altitude of the UVR. UVR MUST satisfy min_altitude.altitude_value < max_altitude.altitude_value. $ref: '#/definitions/Altitude' reason: description: The reason for the UVR. Meant for human consumption. type: string maxLength: 1000 example: message_id: '00000000-0000-4444-8888-600DCAFEF00D' uss_name: "uss.provider321.com" type: DYNAMIC_RESTRICTION cause: SAFETY geography: type: Polygon coordinates: - - - -122.062176579 - 37.40968041145 - - -122.05187056889 - 37.41786527236 - - -122.03732647634 - 37.41786440108 - - -122.062176579 - 37.40968041145 effective_time_begin: '2016-11-29T01:16:41.727Z' effective_time_end: '2016-11-30T01:16:41.727Z' permitted_uas: - NOT_SET permitted_gufis: - '00000000-0000-4444-8888-FEEDDEADFFFF' actual_time_end: '2016-11-30T01:15:41.727Z' min_altitude: altitude_value: 2300 vertical_reference: "W84" units_of_measure: "FT" max_altitude: altitude_value: 2700 vertical_reference: "W84" units_of_measure: "FT" reason: A UA leaving defined volume NegotiationAgreement: required: - message_id - negotiation_id - uss_name_of_originator - uss_name_of_receiver - gufi_originator - gufi_receiver - type properties: message_id: description: >- An identifier unique to this particular message. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" negotiation_id: description: >- An identifier held constant across multiple message_ids. This value represents a single negotiation between two USSs for two specific operations. Will be same value as used in NegotiationMessage for this particular negotiation between these operations. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" uss_name: description: >- A name identifying the originator of this message. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. NegotiationAgreement uss_name MUST be a duplicate of either uss_name_of_originator or uss_name_of_receiver. This field is required for security and data quality purposes. type: string minLength: 4 exclusiveMinimum: false maxLength: 250 exclusiveMaximum: false uss_name_of_originator: description: >- Name of the USS originating the negotation. NegotiationAgreement uss_name_of_originator MUST be the uss_name as known by FIMS authorization server. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string minLength: 4 maxLength: 250 uss_name_of_receiver: description: >- Name of the USS receiving the original negotiation request. NegotiationAgreement uss_name_of_receiver MUST be the uss_name as known by FIMS authorization server. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string minLength: 4 maxLength: 250 gufi_originator: description: >- The GUFI of the relevant operation of the originating USS. Note that the origin and receiver roles are strictly dependent on which USS is generating this message. May be empty in the case of ATC communication to USS via FIMS. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" gufi_receiver: description: > The GUFI of the relevant operation of the receiving USS. Note that the origin and receiver roles are strictly dependent on which USS is generating this message. May be empty in the case of ATC communication to USS via FIMS. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" free_text: type: string maxLength: 1000 discovery_reference: description: >- An identifier that supplies information about the USS from the discovery perspecitve. This field is currently vague due to research on the appropriate discovery approach. It will be tightened when an operational system decides on the approach to discovery. For Gridded USS Discovery, this should be an x,y,z string where x and y are the coords of the grid and z is the zoom level. For example: "110,117,10" For FIMS Discovery, this should be the uss_instance_id which is a UUID and represents the instance id tied to the USS identified by the uss_name field's instance in this negotiation. type: string minLength: 5 maxLength: 36 example: "110,117,10" type: description: >- The type of negotation result. INTERSECTION: both USSs agreed to intersect their operation plans. REPLAN: both USSs agreed on replan of receiving operation. In this case there would be no planned intersection of these operations. type: string enum: - INTERSECTION - REPLAN example: "INTERSECTION" NegotiationMessage: required: - message_id - negotiation_id - uss_name_of_originator - type - gufi_of_originator - gufi_of_receiver properties: message_id: type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" negotiation_id: description: >- An identifier held constant across multiple message_ids. This value represents a single negotiation between two USSs for two specific operations. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" uss_name_of_originator: description: >- A name identifying the originator of this message. NegotiationMessage uss_name_of_originator MUST be the uss_name as known by the authorization server. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string minLength: 4 maxLength: 250 type: description: >- The type of negotiation message. Currently just requesting another USS replan an operation, or request that a USS allow an intersection of operations. In addition, add ability to cancel previous agreed negotiation. type: string enum: - REPLAN_REQUESTED - REPLAN_CANCELLED - INTERSECTION_REQUESTED - INTERSECTION_CANCELLED replan_suggestion: description: >- When 'type' is REPLAN_REQUESTED, the originating USS may supply a suggestion as to how the receiving USS might alter the plan under its management to minimize the conflict. This field is optional in all cases. It should not be sent with any message that does not contain type = REPLAN_REQUESTED. The suggestion is truly a suggestion. The receiving USS may solve (or not solve) a conflict in any manner it deems appropriate. type: string enum: - ALTITUDE_CHANGE - DEPART_LATER - LAND_EARLIER - HORIZONTAL_CHANGE v2v_for_originator: description: >- A boolean field indicating whether the vehicle supported by the originating USS will be using the approved vehicle-to-vehicle communication approach. Required when the negotiation results in any intersection of operation plans between the two operations in the negotiation. This assumes that there is only one approved V2V approach in the future operational system. If this is not the case, this field could need to be more explicit to ensure certainty that the two vehicles will be able to communicate while in flight. type: boolean default: false v2v_for_receiver: description: >- A boolean field indicating whether the vehicle supported by the receiving USS will be using the approved vehicle-to-vehicle communication approach. Required when the negotiation results in any intersection of operation plans between the two operations in the negotiation. This assumes that there is only one approved V2V approach in the future operational system. If this is not the case, this field could need to be more explicit to ensure certainty that the two vehicles will be able to communicate while in flight. type: boolean default: false gufi_of_originator: description: >- The GUFI of the relevant operation of the originating USS. Note that the origin and receiver roles are strictly dependent on which USS is generating this message. May be empty in the case of ATC communication to USS via FIMS. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" gufi_of_receiver: description: >- The GUFI of the relevant operation of the receiving USS. Note that the origin and receiver roles are strictly dependent on which USS is generating this message. May be empty in the case of ATC communication to USS via FIMS. The receiving USS MUST return 400 if it does not own this GUFI. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" discovery_reference: description: >- An identifier that supplies information about the USS from the discovery perspective. This field is currently vague due to research on the appropriate discovery approach. It will be tightened when an operational system decides on the approach to discovery. For Gridded USS Discovery, this should be an x,y,z string where x and y are the coords of the grid and z is the zoom level. For example: "110,117,10" For FIMS Discovery, this should be the uss_instance_id which is a UUID. type: string minLength: 5 maxLength: 36 example: "110,117,10" free_text: type: string maxLength: 1000 UasRegistration: type: object description: >- A set of data describing the registration of the UAS that is to be used in an Operation. required: - registration_id - registration_location properties: registration_id: description: >- A unique registration identifier, minted by the registration authority as a UUIDv4. type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" registration_location: type: string format: url description: >- An Internet-reachable URL for the registration authority. More details to come, however, it is thought that this should be an endpoint allowing an unauthenticated GET to obtain metadata about the registrar. UssInstance: type: object description: >- A contiguous area within which a USS has committed to providing services for UAS operations. The specific level of services provided may be contained within the data provided from here in combination with data provided directly from the USS. In the future, the information provided by this object may include more specific information about the services provided by the USS or the types of UAS operations that are supported by this USS Instance. required: - uss_instance_id - time_available_begin - time_available_end - coverage_area - uss_base_callback_url properties: uss_instance_id: type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" uss_name: description: >- The name of the entity providing UAS Support Services. Populated by the service discovery system based on credential information provided by the USS. UssInstance uss_name MUST be the uss_name as known by the authorization server. The maximum and minimum character length is based on a usable domain name, and considering the maximum in RFC-1035. type: string minLength: 4 maxLength: 250 time_submitted: description: >- The time at which the submission of this USS Instance was received at this discovery service. Only modifiable by discovery service. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' time_available_begin: description: >- The time at which the USS will begin providing services for active UAS operations for this USS Instance. Note that the USS may provide planning services prior to the time_available_begin depending on the policies of the USS. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' time_available_end: description: >- The time at which the USS will cease providing services for active UAS operations for this USS Instance. This means that there will not be any UAS operations airborne after this time that would be supported by this USS Instance. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' coverage_area: $ref: 'https://raw.githubusercontent.com/nasa/utm-apis/v4-draft/utm-domains/utm-domain-geojson.yaml#/definitions/Polygon' time_last_modified: description: >- The last time there was an update to the data regarding this USS Instance. Only modifiable by discovery service. type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: OPERATIONAL pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' contact: $ref: '#/definitions/PersonOrOrganization' x-utm-data-accessibility: OPERATIONAL uss_base_callback_url: type: string format: url description: >- A base URL used by the USS Discovery Service and other USS Instances to callback to the USS Instance. USS Discovery will append "/uss" to the base URL in order to PUT a new uss_instance to the USS Instance. It will also do the same to test the URL when it first receives a uss_instance. USS Instances and other clients/services will append "/operations" to the base URL in order to share operations. Similarly with "/utm_messages", "/negotiations", etc. The base URL will also be used in obtaining the websocket for position sharing. This URL may be unique to the USS Instance or may be shared by other USS Instances created by the same USS. URLs that are common to multiple USS Instances will receive only one callback. uss_informational_url: type: string format: url description: An optional website URL for the USS for human use. uss_openapi_url: type: string format: url description: >- An optional URL for the USS to supply an OpenAPI specification of its UAS Operator interface. uss_registration_url: type: string format: url description: >- An optional URL for UAS operators to register with this USS for services. notes: type: string description: >- Any additional free text that would aid consumers of the service discovery API in understanding this USS Instance. example: uss_instance_id: 00000000-0000-4444-8888-FEEDDEADBEEF uss_name: NUSS time_submitted: '2016-08-03T00:15:40.931Z' time_available_begin: '2016-10-04T09:15:40.231Z' time_available_end: '2016-11-04T13:20:42.356Z' time_last_modified: '2016-08-04T17:31:01.253Z' coverage_area: type: Polygon coordinates: - - - -122.06382530000002 - 37.4090697 - - -122.05094253233 - 37.4193006277 - - -122.03276206976 - 37.41929920176 - - -122.06382530000002 - 37.4090697 - - - -122.062176579 - 37.40968041145 - - -122.05187056889 - 37.41786527236 - - -122.03732647634 - 37.41786440108 - - -122.062176579 - 37.40968041145 notes: >- NUSS will only provide services for fixed-wing aircraft within this USS Instance volume. uss_base_callback_url: 'https://utm.arc.nasa.gov/nuss/uss' uss_informational_url: 'https://utm.arc.nasa.gov' uss_openapi_url: 'https://nuss.arc.nasa.gov/api' uss_registration_url: 'https://nuss.arc.nasa.gov/signup' VehicleOperationData: type: object properties: registration_id: type: string vehicle_type: type: string owner_name: type: string owner_contact: type: string format: phone maxLength: 100 n_number: type: string maxLength: 100 faa_registration-number: type: string maxLength: 100 uss_name: type: string maxLength: 250 minLength: 4 example: "utmbeta.arc.nasa.gov" uss_instance_id: type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" gufi: type: string format: uuid maxLength: 36 minLength: 36 pattern: "^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$" example: "00000000-0000-4444-8888-FEEDDEADBEEF" operation_state: type: string example: "ROGUE" additional_details: type: string example: "Extra details" Version: type: object properties: title: type: string description: Title of the API version: type: string description: Version number for the API build_time: description: Time of the latest build type: string format: date-time minLength: 24 maxLength: 24 x-utm-data-accessibility: PUBLIC pattern: "^([0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]{3})Z$" example: '2015-08-20T14:11:56.118Z' api_docs: type: array items: type: string description: URL(s) for API Documentation UTMRestResponse: type: object required: - http_status_code - message properties: http_status_code: type: integer minimum: 100 exclusiveMinimum: false maximum: 599 exclusiveMaximum: false message: type: string maxLength: 500 example: http_status_code: 400 message: Bad Request. Invalid JSON? parameters: fieldsParam: name: fields in: query description: >- The specific subset of fields to return. Comma separated list. Default will be all fields when this parameter is not provided in the query. Duplicate field names not allowed and server may reject query if duplicates are provided. If field names are provided that are not part of the request model, the server may either reject the query or ignore the improper fields. Maximum 20 field values supported. If more than 20 fields are required, then this parameter should not be used so that all fields are returned. required: false type: array items: type: string collectionFormat: csv maxItems: 20 minItems: 1 uniqueItems: true sortParam: name: sort in: query description: >- A valid field name to use for sorting records. If multiple fields are provided, the sorting is based on the ordered priority of that list. required: false default: time_submitted type: string sortIncreasingParam: name: sort_increasing in: query description: >- For optional use with the 'sort' parameter. If 'sort' is not provided, then 'sort_increasing' will be ignored. Boolean value. If multiple fields are provided in the 'sort' parameter, this boolean value will apply to all of them. required: false default: true type: boolean limitParam: name: limit in: query description: The maximum number or records to return. required: false type: integer default: 10 format: int32 maximum: 100 minimum: 1 offsetParam: name: offset in: query description: The index from which to begin the list of returned records. required: false type: integer default: 0 format: int32