[TO DO] Repositório
Apresentação Workshop
DSS: https://github.com/dp-icea/dss
Monitoring: https://github.com/dp-icea/utm_monitoring
SCD-Provider Example: ???
YML:
Swagger:
Inter Operability
openapi: 3.0.2
info:
title: UTM API (USS->DSS and USS->USS)
version: 1.0.0
description: >-
Interface definitions for communication between a UAS Service Supplier (USS)
and a Discovery and Synchronization Service (DSS), as well as for
communication between two USSs.
DSS functionality includes identification of peer UTM USS instances
(managing flight operational intents and constraints). USS functionality
includes sharing details of flight operational intents and constraints.
Note: Unless otherwise specified, fields specified in a message but not
declared in the API must be ignored.
Whenever a object-type field may be omitted, it may also be set to null for
the same effect.
servers:
- url: http://localhost:8082
security:
- bearerAuth: []
tags:
- name: Operational intent references
description: >-
Endpoints exposed by the DSS for interaction with references to
operational intents.
- name: Operational intent details
description: >-
Endpoints exposed by USSs for interaction with details of operational
intents.
- name: Constraint references
description: >-
Endpoints exposed by the DSS for interaction with references to
constraints.
- name: Constraint details
description: >-
Endpoints exposed by USSs for interaction with details of constraints.
- name: Subscriptions
description: >-
Endpoints exposed by the DSS for interaction with subscription entities.
- name: Reports
description: Endpoints exposed by the DSS for reporting peer DSS issues.
- name: Availability
description: Endpoints exposed by the DSS for declaring USS availability.
- name: Logging
description: >-
Pseudo-endpoints not intended to be implemented literally, but rather to
illustrate logging data formats
- name: dss
description: Endpoints exposed by the DSS server.
- name: p2p_utm
description: Endpoints exposed by UTM USSs for peer-peer communication.
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
FlightType:
description: >-
String for flight type. Accepted values are "VLOS", "EVLOS" or "BVLOS"
maxLength: 5
minLength: 4
type: string
enum:
- VLOS
- EVLOS
- BVLOS
UUIDv4Format:
description: >-
String whose format matches a version-4 UUID according to RFC 4122.
maxLength: 36
minLength: 36
type: string
format: uuid
pattern: >-
^[0-9a-fA-F]{8}\\-[0-9a-fA-F]{4}\\-4[0-9a-fA-F]{3}\\-[8-b][0-9a-fA-F]{3}\\-[0-9a-fA-F]{12}$
example: 03e5572a-f733-49af-bc14-8a18bd53ee39
EntityID:
description: >-
Identifier for an Entity communicated through the DSS. Formatted as a
UUIDv4.
anyOf:
- $ref: '#/components/schemas/UUIDv4Format'
example: 2f8343be-6482-4d1b-a474-16847e01af1e
EntityOVN:
title: EntityOVN
description: >-
A token associated with a particular UTM Entity+version created by the
DSS upon creation or modification of an Entity reference and provided to
the client creating or modifying the Entity reference. The EntityOVN is
stored privately by the DSS and then compared against entries in a Key
provided to mutate the airspace. The EntityOVN is also provided by the
client whenever that client transmits the full information of the Entity
(either via GET, or via a subscription notification).
type: string
minLength: 16
maxLength: 128
example: 9d158f59-80b7-4c11-9c0c-8a2b4d936b2d
SubscriptionID:
description: >-
Identifier for a subscription communicated through the DSS. Formatted
as a UUIDv4.
anyOf:
- $ref: '#/components/schemas/UUIDv4Format'
example: 78ea3fe8-71c2-4f5c-9b44-9c02f5563c6f
Key:
description: >-
Proof that a client has obtained the latest airspace content, used to
ensure that write operations to the DSS occur only when the latest
content is known (i.e. has been read). The client is required to pass a
current Key constructed from information obtained with previous read
operations and subsequent requests for full information, and optionally,
subscription updates for deconflicted write operations to the DSS. The
contents of this data structure are generated by the client.
type: array
items:
$ref: '#/components/schemas/EntityOVN'
default: [ ]
Time:
required:
- value
- format
type: object
properties:
value:
type: string
description: >-
RFC3339-formatted time/date string. The time zone must be 'Z'.
format: date-time
example: '1985-04-12T23:20:50.52Z'
format:
type: string
enum:
- RFC3339
Radius:
required:
- value
- units
type: object
properties:
value:
format: float
description: >-
Distance from the centerpoint of a circular area, along the WGS84
ellipsoid.
type: number
minimum: 0
exclusiveMinimum: true
example: 300.183
units:
type: string
description: >-
FIXM-compatible units. Only meters ("M") are acceptable for UTM.
enum:
- M
Altitude:
type: object
required:
- value
- reference
- units
properties:
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 may be re-evaluated.
type: number
format: double
minimum: -8000
exclusiveMinimum: false
maximum: 100000
exclusiveMaximum: false
reference:
description: >-
A code indicating the reference for a vertical distance. See AIXM
5.1 and FIXM 4.2.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.
type: string
enum:
- W84
units:
description: >-
The reference quantities used to express the value of altitude. See
FIXM 4.2. Currently, UTM only allows meters with no immediate plans
to allow other options.
type: string
enum:
- M
Latitude:
description: >-
Degrees of latitude north of the equator, with reference to the WGS84
ellipsoid.
maximum: 90
exclusiveMaximum: false
minimum: -90
exclusiveMinimum: false
type: number
format: double
example: 34.123
Longitude:
description: >-
Degrees of longitude east of the Prime Meridian, with reference to the
WGS84 ellipsoid.
minimum: -180
exclusiveMaximum: false
maximum: 180
exclusiveMinimum: false
type: number
format: double
example: -118.456
Polygon:
description: >-
An enclosed area on the earth. The bounding edges of this polygon are
defined to be the shortest paths between connected vertices. This
means, for instance, that the edge between two points both defined at a
particular latitude is not generally contained at that latitude. The
winding order must be interpreted as the order which produces the
smaller area. The path between two vertices is defined to be the
shortest possible path between those vertices. Edges may not cross.
Vertices may not be duplicated. In particular, the final polygon vertex
must not be identical to the first vertex.
required:
- vertices
type: object
properties:
vertices:
minItems: 3
type: array
items:
$ref: '#/components/schemas/LatLngPoint'
LatLngPoint:
description: Point on the earth's surface.
required:
- lat
- lng
type: object
properties:
lng:
$ref: '#/components/schemas/Longitude'
lat:
$ref: '#/components/schemas/Latitude'
Circle:
description: A circular area on the surface of the earth.
type: object
properties:
center:
$ref: '#/components/schemas/LatLngPoint'
radius:
$ref: '#/components/schemas/Radius'
Volume3D:
description: >-
A three-dimensional geographic volume consisting of a
vertically-extruded shape. Exactly one outline must be specified.
type: object
properties:
outline_circle:
anyOf:
- $ref: '#/components/schemas/Circle'
description: A circular geographic shape on the surface of the earth.
outline_polygon:
anyOf:
- $ref: '#/components/schemas/Polygon'
description: >-
A polygonal geographic shape on the surface of the earth.
altitude_lower:
description: >-
Minimum bounding altitude of this volume. Must be less than
altitude_upper, if specified.
anyOf:
- $ref: '#/components/schemas/Altitude'
altitude_upper:
description: >-
Maximum bounding altitude of this volume. Must be greater than
altitude_lower, if specified.
anyOf:
- $ref: '#/components/schemas/Altitude'
Volume4D:
description: Contiguous block of geographic spacetime.
required:
- volume
type: object
properties:
volume:
$ref: '#/components/schemas/Volume3D'
time_start:
description: Beginning time of this volume. Must be before time_end.
anyOf:
- $ref: '#/components/schemas/Time'
time_end:
description: End time of this volume. Must be after time_start.
anyOf:
- $ref: '#/components/schemas/Time'
ErrorResponse:
description: >-
Human-readable string returned when an error occurs as a result of a USS
- DSS transaction.
type: object
properties:
message:
description: >-
Human-readable message indicating what error occurred and/or why.
type: string
example: The error occurred because [...]
SubscriptionState:
description: >-
State of subscription which is causing a notification to be sent.
required:
- subscription_id
- notification_index
type: object
properties:
subscription_id:
$ref: '#/components/schemas/SubscriptionID'
notification_index:
$ref: '#/components/schemas/SubscriptionNotificationIndex'
SubscriberToNotify:
description: >-
Subscriber to notify of a change in the airspace. This is provided by
the DSS to a client changing the airspace, and it is the responsibility
of that client to send a notification to the specified USS according to
the change made to the airspace.
required:
- subscriptions
- uss_base_url
type: object
properties:
subscriptions:
description: Subscription(s) prompting this notification.
type: array
items:
$ref: '#/components/schemas/SubscriptionState'
minItems: 1
uss_base_url:
$ref: '#/components/schemas/SubscriptionUssBaseURL'
Subscription:
description: >-
Specification of a geographic area that a client is interested in on an
ongoing basis (e.g., "planning area").
required:
- id
- version
- notification_index
- uss_base_url
type: object
properties:
id:
$ref: '#/components/schemas/SubscriptionID'
version:
description: >-
Version of the subscription that the DSS changes every time a USS
changes the subscription. The DSS incrementing the
notification_index does not constitute a change that triggers a new
version. A USS must specify this version when modifying an existing
subscription to ensure consistency in read-modify-write operations
and distributed systems.
type: string
notification_index:
$ref: '#/components/schemas/SubscriptionNotificationIndex'
time_start:
description: >-
If set, this subscription will not receive notifications involving
airspace changes entirely before this time.
anyOf:
- $ref: '#/components/schemas/Time'
time_end:
description: >-
If set, this subscription will not receive notifications involving
airspace changes entirely after this time.
anyOf:
- $ref: '#/components/schemas/Time'
uss_base_url:
$ref: '#/components/schemas/SubscriptionUssBaseURL'
notify_for_operational_intents:
description: >-
If true, trigger notifications when operational intents are created,
updated, or deleted. Otherwise, changes in operational intents
should not trigger notifications. The scope
utm.strategic_coordination is required to set this flag true.
type: boolean
default: false
notify_for_constraints:
description: >-
If true, trigger notifications when constraints are created,
updated, or deleted. Otherwise, changes in constraints should not
trigger notifications. The scope utm.constraint_processing is
required to set this flag true.
type: boolean
default: false
implicit_subscription:
description: >-
True if this subscription was implicitly created by the DSS via the
creation of an operational intent, and should therefore be deleted
by the DSS when that operational intent is deleted.
type: boolean
default: false
dependent_operational_intents:
description: >-
List of IDs for operational intents that are dependent on this
subscription.
type: array
items:
$ref: '#/components/schemas/EntityID'
default: [ ]
SubscriptionNotificationIndex:
format: int32
description: >-
Tracks the notifications sent for a subscription so the subscriber can
detect missed notifications more easily.
type: integer
minimum: 0
exclusiveMinimum: false
default: 0
QuerySubscriptionParameters:
description: >-
Parameters for a request to find subscriptions matching the provided
criteria.
type: object
properties:
area_of_interest:
$ref: '#/components/schemas/Volume4D'
QuerySubscriptionsResponse:
description: >-
Response to DSS query for subscriptions in a particular geographic area.
required:
- subscriptions
type: object
properties:
subscriptions:
description: >-
Subscriptions that overlap the specified geographic area.
type: array
items:
$ref: '#/components/schemas/Subscription'
default: [ ]
GetSubscriptionResponse:
description: >-
Response to DSS request for the subscription with the given id.
required:
- subscription
type: object
properties:
subscription:
$ref: '#/components/schemas/Subscription'
PutSubscriptionParameters:
description: >-
Parameters for a request to create/update a subscription in the DSS. At
least one form of notifications must be requested.
required:
- extents
- uss_base_url
type: object
properties:
extents:
description: >-
Spacetime extents of the volume to subscribe to.
This subscription will automatically be deleted after its end time
if it has not been refreshed by then. If end time is not specified,
the value will be chosen automatically by the DSS. If start time is
not specified, it will default to the time the request is processed.
The end time may not be in the past.
Note that some Entities triggering notifications may lie entirely
outside the requested area.
anyOf:
- $ref: '#/components/schemas/Volume4D'
uss_base_url:
$ref: '#/components/schemas/SubscriptionUssBaseURL'
notify_for_operational_intents:
description: >-
If true, trigger notifications when operational intents are created,
updated, or deleted. Otherwise, changes in operational intents
should not trigger notifications. The scope
utm.strategic_coordination is required to set this flag true.
type: boolean
default: false
notify_for_constraints:
description: >-
If true, trigger notifications when constraints are created,
updated, or deleted. Otherwise, changes in constraints should not
trigger notifications. The scope utm.constraint_processing is
required to set this flag true.
type: boolean
default: false
SubscriptionUssBaseURL:
description: >-
The base URL of a USS implementation of the parts of the USS-USS API
necessary for receiving the notifications requested by this
subscription.
anyOf:
- $ref: '#/components/schemas/UssBaseURL'
PutSubscriptionResponse:
description: Response for a request to create or update a subscription.
required:
- subscription
type: object
properties:
subscription:
$ref: '#/components/schemas/Subscription'
operational_intent_references:
description: >-
Operational intents in or near the subscription area at the time of
creation/update, if `notify_for_operational_intents` is true.
type: array
items:
$ref: '#/components/schemas/OperationalIntentReference'
default: [ ]
constraint_references:
description: >-
Constraints in or near the subscription area at the time of
creation/update, if `notify_for_constraints` is true.
type: array
items:
$ref: '#/components/schemas/ConstraintReference'
default: [ ]
DeleteSubscriptionResponse:
description: Response for a successful request to delete a subscription.
required:
- subscription
type: object
properties:
subscription:
$ref: '#/components/schemas/Subscription'
UssBaseURL:
description: >-
The base URL of a USS implementation of part or all of the USS-USS API.
Per the USS-USS API, the full URL of a particular resource can be
constructed by appending, e.g., `/uss/v1/{resource}/{id}` to this base
URL. Accordingly, this URL may not have a trailing '/' character.
type: string
example: https://uss.example.com/utm
OperationalIntentState:
description: >-
State of an operational intent.
'Accepted': Operational intent is created and shared, but not yet in
use; see standard text for more details.
The create or update request for this operational intent reference must
include a Key containing all OVNs for all relevant Entities.
'Activated': Operational intent is in active use; see standard text for
more details.
The create or update request for this operational intent reference must
include a Key containing all OVNs for all relevant Entities.
'Nonconforming': UA is temporarily outside its volumes, but the
situation is expected to be recoverable; see standard text for more
details.
In this state, the `/uss/v1/operational_intents/{entityid}/telemetry`
USS-USS endpoint should respond, if available, to queries from USS
peers. The create or update request for this operational intent may
omit a Key in this case because the operational intent is being adjusted
as flown and cannot necessarily deconflict.
'Contingent': UA is considered unrecoverably unable to conform with its
coordinate operational intent; see standard text for more details.
This state must transition to Ended. In this state, the
`/uss/v1/operational_intents/{entityid}/telemetry` USS-USS endpoint
should respond, if available, to queries from USS peers. The create or
update request for this operational intent may omit a Key in this case
because the operational intent is being adjusted as flown and cannot
necessarily deconflict.
type: string
enum:
- Accepted
- Activated
- Nonconforming
- Contingent
OperationalIntentReference:
description: >-
The high-level information of a planned or active operational intent
with the URL of a USS to query for details. Note: 'ovn' is returned
ONLY to the USS that created the operational intent but NEVER to other
USS instances.
required:
- id
- manager
- uss_availability
- version
- state
- time_start
- time_end
- uss_base_url
- subscription_id
type: object
properties:
id:
$ref: '#/components/schemas/EntityID'
manager:
type: string
example: uss1
description: >-
Created by the DSS based on creating client's ID (via access
token). Used internal to the DSS for restricting mutation and
deletion operations to manager. Used by USSs to reject operational
intent update notifications originating from a USS that does not
manage the operational intent.
uss_availability:
$ref: '#/components/schemas/UssAvailabilityState'
version:
type: integer
format: int32
example: 1
description: >-
Numeric version of this operational intent which increments upon
each change in the operational intent, regardless of whether any
field of the operational intent reference changes. A USS with the
details of this operational intent when it was at a particular
version does not need to retrieve the details again until the
version changes.
state:
$ref: '#/components/schemas/OperationalIntentState'
ovn:
description: >-
Opaque version number of this operational intent. Populated only
when the OperationalIntentReference is managed by the USS retrieving
or providing it. Not populated when the OperationalIntentReference
is not managed by the USS retrieving or providing it (instead, the
USS must obtain the OVN from the details retrieved from the managing
USS).
anyOf:
- $ref: '#/components/schemas/EntityOVN'
time_start:
description: Beginning time of operational intent.
anyOf:
- $ref: '#/components/schemas/Time'
time_end:
description: End time of operational intent.
anyOf:
- $ref: '#/components/schemas/Time'
uss_base_url:
$ref: '#/components/schemas/OperationalIntentUssBaseURL'
subscription_id:
description: >-
The ID of the subscription that is ensuring the operational intent
manager receives relevant airspace updates.
anyOf:
- $ref: '#/components/schemas/SubscriptionID'
OperationalIntentFlightType:
description: Flight Type
anyOf:
- $ref: '#/components/schemas/FlightType'
OperationalIntentUssBaseURL:
description: >-
The base URL of a USS implementation that implements the parts of the
USS-USS API necessary for providing the details of this operational
intent, and telemetry during non-conformance or contingency, if
applicable.
anyOf:
- $ref: '#/components/schemas/UssBaseURL'
PutOperationalIntentReferenceParameters:
description: >-
Parameters for a request to create an OperationalIntentReference in the
DSS. A subscription to changes overlapping this volume may be implicitly
created, but this can be overridden by providing the (optional)
'subscription_id' to use. Note: The implicit subscription is managed by
the DSS, not the USS.
required:
- extents
- state
- uss_base_url
- flight_type
type: object
properties:
flight_type:
$ref: '#/components/schemas/OperationalIntentFlightType'
extents:
description: >-
Spacetime extents that bound this operational intent.
Start and end times, as well as lower and upper altitudes, are
required for each volume. The end time may not be in the past. All
volumes, both nominal and off-nominal, must be encompassed in these
extents. However, these extents do not need to match the precise
volumes of the operational intent; a single bounding extent may be
provided instead, for instance.
type: array
items:
$ref: '#/components/schemas/Volume4D'
minItems: 1
key:
description: >-
Proof that the USS creating or mutating this operational intent was
aware of the current state of the airspace, with the expectation
that this operational intent is therefore deconflicted from all
relevant features in the airspace. This field is not required when
declaring an operational intent Nonconforming or Contingent, or when
there are no relevant Entities in the airspace, but is otherwise
required. OVNs for constraints are required if and only if the USS
managing this operational intent is performing the constraint
processing role, which is indicated by whether the subscription
associated with this operational intent triggers notifications for
constraints. The key does not need to contain the OVN for the
operational intent being updated.
anyOf:
- $ref: '#/components/schemas/Key'
state:
$ref: '#/components/schemas/OperationalIntentState'
uss_base_url:
$ref: '#/components/schemas/OperationalIntentUssBaseURL'
subscription_id:
description: >-
The ID of an existing subscription that the USS will use to keep the
operator informed about updates to relevant airspace information. If
this field is not provided when the operational intent is in the
Activated, Nonconforming, or Contingent state, then the
`new_subscription` field must be provided in order to provide
notification capability for the operational intent. The
subscription specified by this ID must cover at least the area over
which this operational intent is conducted, and it must provide
notifications for operational intents.
anyOf:
- $ref: '#/components/schemas/EntityID'
new_subscription:
description: >-
If an existing subscription is not specified in `subscription_id`,
and the operational intent is in the Activated, Nonconforming, or
Contingent state, then this field must be populated. When this
field is populated, an implicit subscription will be created and
associated with this operational intent, and will generally be
deleted automatically upon the deletion of this operational intent.
anyOf:
- $ref: '#/components/schemas/ImplicitSubscriptionParameters'
ImplicitSubscriptionParameters:
description: >-
Information necessary to create a subscription to serve a single
operational intent's notification needs.
type: object
required:
- uss_base_url
properties:
uss_base_url:
description: >-
The base URL of a USS implementation of the parts of the USS-USS API
necessary for receiving the notifications that the operational
intent must be aware of. This includes, at least, notifications for
relevant changes in operational intents.
anyOf:
- $ref: '#/components/schemas/SubscriptionUssBaseURL'
notify_for_constraints:
description: >-
True if this operational intent's subscription should trigger
notifications when constraints change. Otherwise, changes in
constraints should not trigger notifications. The scope
utm.constraint_processing is required to set this flag true, and a
USS performing the constraint processing role should set this flag
true.
type: boolean
default: false
GetOperationalIntentReferenceResponse:
description: >-
Response to DSS request for the OperationalIntentReference with the
given ID.
required:
- operational_intent_reference
type: object
properties:
operational_intent_reference:
$ref: '#/components/schemas/OperationalIntentReference'
ChangeOperationalIntentReferenceResponse:
description: >-
Response to a request to create, update, or delete an
OperationalIntentReference in the DSS.
required:
- subscribers
- operational_intent_reference
type: object
properties:
subscribers:
description: >-
DSS subscribers that this client now has the obligation to notify of
the operational intent changes just made. This client must call
POST for each provided URL according to the USS-USS
`/uss/v1/operational_intents` path API. The client's own
subscriptions will also be included in this list.
type: array
items:
$ref: '#/components/schemas/SubscriberToNotify'
default: [ ]
operational_intent_reference:
$ref: '#/components/schemas/OperationalIntentReference'
QueryOperationalIntentReferenceParameters:
description: >-
Parameters for a request to find OperationalIntentReferences matching
the provided criteria.
type: object
properties:
area_of_interest:
$ref: '#/components/schemas/Volume4D'
QueryOperationalIntentReferenceResponse:
description: >-
Response to DSS query for OperationalIntentReferences in an area of
interest.
required:
- operational_intent_references
type: object
properties:
operational_intent_references:
description: OperationalIntentReferences in the area of interest.
type: array
items:
$ref: '#/components/schemas/OperationalIntentReference'
default: [ ]
ConstraintReference:
description: >-
A ConstraintReference (area in which a constraint is present, along with
other high-level information, but no details). The DSS reports only
these references and clients must exchange details and additional
information peer-to-peer.
required:
- id
- manager
- uss_availability
- version
- time_start
- time_end
- uss_base_url
type: object
properties:
id:
$ref: '#/components/schemas/EntityID'
manager:
type: string
example: uss1
description: >-
Created by the DSS based on creating client's ID (via access
token). Used internal to the DSS for restricting mutation and
deletion operations to manager. Used by USSs to reject constraint
update notifications originating from a USS that does not manage the
constraint.
uss_availability:
$ref: '#/components/schemas/UssAvailabilityState'
version:
type: integer
format: int32
example: 1
description: >-
Numeric version of this constraint which increments upon each change
in the constraint, regardless of whether any field of the constraint
reference changes. A USS with the details of this constraint when
it was at a particular version does not need to retrieve the details
again until the version changes.
ovn:
description: >-
Opaque version number of this constraint. Populated only when the
ConstraintReference is managed by the USS retrieving or providing
it. Not populated when the ConstraintReference is not managed by
the USS retrieving or providing it (instead, the USS must obtain the
OVN from the details retrieved from the managing USS).
anyOf:
- $ref: '#/components/schemas/EntityOVN'
time_start:
$ref: '#/components/schemas/Time'
time_end:
$ref: '#/components/schemas/Time'
uss_base_url:
$ref: '#/components/schemas/ConstraintUssBaseURL'
ConstraintUssBaseURL:
description: >-
The base URL of a USS implementation that implements the parts of the
USS-USS API necessary for providing the details of this constraint.
anyOf:
- $ref: '#/components/schemas/UssBaseURL'
PutConstraintReferenceParameters:
description: >-
Parameters for a request to create/update a ConstraintReference in the
DSS.
required:
- extents
- uss_base_url
type: object
properties:
extents:
description: >-
Spacetime extents that bound this constraint.
The end time may not be in the past.
All volumes of the constraint must be encompassed in these extents.
However, these extents do not need to match the precise volumes of
the constraint; a single bounding extent may be provided instead,
for instance.
type: array
items:
$ref: '#/components/schemas/Volume4D'
minItems: 1
uss_base_url:
$ref: '#/components/schemas/ConstraintUssBaseURL'
GetConstraintReferenceResponse:
description: >-
Response to DSS request for the ConstraintReference with the given ID.
required:
- constraint_reference
type: object
properties:
constraint_reference:
$ref: '#/components/schemas/ConstraintReference'
ChangeConstraintReferenceResponse:
description: >-
Response to a request to create, update, or delete a
ConstraintReference. in the DSS.
required:
- subscribers
- constraint_reference
type: object
properties:
subscribers:
description: >-
DSS subscribers that this client now has the obligation to notify of
the constraint changes just made. This client must call POST for
each provided URL according to the USS-USS `/uss/v1/constraints`
path API. The client's own subscriptions will also be included in
this list.
type: array
items:
$ref: '#/components/schemas/SubscriberToNotify'
default: [ ]
constraint_reference:
$ref: '#/components/schemas/ConstraintReference'
QueryConstraintReferenceParameters:
description: >-
Parameters for a request to find ConstraintReferences matching the
provided criteria.
type: object
properties:
area_of_interest:
$ref: '#/components/schemas/Volume4D'
QueryConstraintReferencesResponse:
description: >-
Response to DSS query for ConstraintReferences in an area of interest.
required:
- constraint_references
type: object
properties:
constraint_references:
description: ConstraintReferences in the area of interest.
type: array
items:
$ref: '#/components/schemas/ConstraintReference'
default: [ ]
AirspaceConflictResponse:
description: Data provided when an airspace conflict was encountered.
type: object
properties:
message:
description: >-
Human-readable message indicating what error occurred and/or why.
type: string
missing_operational_intents:
description: >-
List of operational intent references for which current proof of
knowledge was not provided. If this field is present and contains
elements, the calling USS should query the details URLs for these
operational intents to obtain their details and correct OVNs. The
OVNs can be used to update the key, at which point the USS may retry
this call.
type: array
items:
$ref: '#/components/schemas/OperationalIntentReference'
default: [ ]
missing_constraints:
description: >-
List of constraint references for which current proof of knowledge
was not provided. If this field is present and contains elements,
the calling USS should query the details URLs for these constraints
to obtain their details and correct OVNs. The OVNs can be used to
update the key, at which point the USS may retry this call.
type: array
items:
$ref: '#/components/schemas/ConstraintReference'
default: [ ]
#
# USS-USS schema components
#
OperationalIntentDetails:
description: >-
Details of a UTM operational intent. Note that this data is not stored
in the DSS; only with the clients.
type: object
properties:
volumes:
description: >-
Volumes that wholly contain the operational intent while being as
small as practical.
Start and end times, as well as lower and upper altitudes, are
required for each volume. The end time may not be in the past.
Required with at least one item when the operational intent is
Accepted, Activated, or Nonconforming.
May not contain any items when the operational intent is Contingent.
type: array
items:
$ref: '#/components/schemas/Volume4D'
default: [ ]
off_nominal_volumes:
description: >-
Volumes that contain the anticipated area of non-conformance while
the aircraft is in the Nonconforming or Contingent states.
Start and end times, as well as lower and upper altitudes, are
required for each volume. The end time may not be in the past.
Required with at least one item when the operational intent is
Nonconforming or Contingent.
May not contain any items when the operational intent is Accepted or
Activated.
type: array
items:
$ref: '#/components/schemas/Volume4D'
default: [ ]
priority:
$ref: '#/components/schemas/Priority'
Priority:
description: >-
Ordinal priority of the operational intent, as defined by the
regulator. Operational intents with lesser values are lower priority
than all operational intents with greater values. A lower-priority
operational intent may not create a conflict with a higher-priority
operational intent. A higher-priority operational intent may create a
conflict with a lower-priority operational intent. The regulator
specifies whether an operational intent may create a conflict with other
operational intents of the same priority.
type: integer
default: 0
OperationalIntent:
description: Full description of a UTM operational intent.
required:
- reference
- details
type: object
properties:
reference:
$ref: '#/components/schemas/OperationalIntentReference'
details:
$ref: '#/components/schemas/OperationalIntentDetails'
PutOperationalIntentDetailsParameters:
description: >-
Parameters of a message informing of detailed information for a peer
operational intent. Pushed (by a client, not the DSS) directly to
clients with subscriptions when another client makes a change to
airspace within a cell with a subscription.
required:
- operational_intent_id
- subscriptions
type: object
properties:
operational_intent_id:
description: ID of operational intent that has changed.
anyOf:
- $ref: '#/components/schemas/EntityID'
operational_intent:
description: >-
Full information about the operational intent that has changed. If
this field is omitted, the operational intent was deleted. The
`ovn` field in the nested `reference` must be populated.
anyOf:
- $ref: '#/components/schemas/OperationalIntent'
subscriptions:
type: array
description: Subscription(s) prompting this notification.
items:
$ref: '#/components/schemas/SubscriptionState'
minItems: 1
GetOperationalIntentDetailsResponse:
description: >-
Response to peer request for the details of operational intent with the
given ID.
required:
- operational_intent
type: object
properties:
operational_intent:
$ref: '#/components/schemas/OperationalIntent'
ConstraintDetails:
description: >-
Details of a UTM constraint. Note that this data is not stored in the
DSS; only with the clients.
required:
- volumes
type: object
properties:
volumes:
description: >-
Volumes that wholly contain the constraint while being as small as
practical.
The end time may not be in the past.
minItems: 1
type: array
items:
$ref: '#/components/schemas/Volume4D'
type:
description: Type of airspace feature this constraint represents.
type: string
example: com.example.non_utm_aircraft_operations
geozone:
description: >-
If this constraint is an ED-269 compliant geo zone, the details
about that geo zone.
anyOf:
- $ref: '#/components/schemas/GeoZone'
Constraint:
description: Full specification of a UTM constraint.
required:
- reference
- details
type: object
properties:
reference:
$ref: '#/components/schemas/ConstraintReference'
details:
$ref: '#/components/schemas/ConstraintDetails'
PutConstraintDetailsParameters:
description: >-
Parameters of a message informing of new full information for a
constraint. Pushed (by a client, not the DSS) directly to clients with
subscriptions when another client makes a change to airspace within a
cell with a subscription.
required:
- constraint_id
- subscriptions
type: object
properties:
constraint_id:
description: ID of constraint that has changed.
anyOf:
- $ref: '#/components/schemas/EntityID'
constraint:
description: >-
Full information about the constraint that has changed. If this
field is omitted, the constraint was deleted. The `ovn` field in
the nested `reference` must be populated.
anyOf:
- $ref: '#/components/schemas/Constraint'
subscriptions:
description: Subscription(s) prompting this notification.
type: array
items:
$ref: '#/components/schemas/SubscriptionState'
minItems: 1
GetConstraintDetailsResponse:
description: >-
Response to peer request for the details of operational intent with the
given ID.
required:
- constraint
type: object
properties:
constraint:
$ref: '#/components/schemas/Constraint'
GetOperationalIntentTelemetryResponse:
description: >-
Response to a peer request for telemetry of an off-nominal operational
intent.
required:
- operational_intent_id
type: object
properties:
operational_intent_id:
description: >-
ID of the operational intent which the vehicle reporting telemetry
is flying.
anyOf:
- $ref: '#/components/schemas/EntityID'
telemetry:
$ref: '#/components/schemas/VehicleTelemetry'
next_telemetry_opportunity:
description: >-
The next telemetry similar to this telemetry is not expected to be
available until at or after this time, so the polling USS should
generally not poll the endpoint providing this response data again
until at or after that time. If this field is omitted, then there
is no current expectation of new telemetry becoming available.
anyOf:
- $ref: '#/components/schemas/Time'
VehicleTelemetry:
description: Vehicle position, altitude, and velocity.
required:
- time_measured
type: object
properties:
time_measured:
$ref: '#/components/schemas/Time'
position:
$ref: '#/components/schemas/Position'
velocity:
$ref: '#/components/schemas/Velocity'
PositionAccuracyVertical:
description: >-
Vertical error that is likely to be present in this reported position.
This is the GVA enumeration from ADS-B, plus some finer values for UAS.
type: string
enum:
- VAUnknown
- VA150mPlus
- VA150m
- VA45m
- VA25m
- VA10m
- VA3m
- VA1m
PositionAccuracyHorizontal:
description: >-
Horizontal error that is likely to be present in this reported position.
This is the NACp enumeration from ADS-B, plus 1m for a more complete
range for UAS.
type: string
enum:
- HAUnknown
- HA10NMPlus
- HA10NM
- HA4NM
- HA2NM
- HA1NM
- HA05NM
- HA03NM
- HA01NM
- HA005NM
- HA30m
- HA10m
- HA3m
- HA1m
Position:
description: >-
Location of the vehicle (UAS) as reported for UTM. Note: 'accuracy'
values are required when extrapolated field is true.
type: object
properties:
longitude:
$ref: '#/components/schemas/Longitude'
latitude:
$ref: '#/components/schemas/Latitude'
accuracy_h:
$ref: '#/components/schemas/PositionAccuracyHorizontal'
accuracy_v:
$ref: '#/components/schemas/PositionAccuracyVertical'
extrapolated:
description: >-
True if this position was generated primarily by computation rather
than primarily from a direct instrument measurement.
type: boolean
default: false
altitude:
$ref: '#/components/schemas/Altitude'
Velocity:
required:
- speed
- units_speed
type: object
properties:
speed:
format: float
type: number
description: Ground speed in meters/second.
example: 200.1
units_speed:
type: string
enum:
- MetersPerSecond
track:
format: float
type: number
description: >-
Direction of flight expressed as a "True North-based" ground track
angle. This value is provided in degrees East of North with a
minimum resolution of 1 degree. A value of 360 indicates invalid, no
value, or unknown.
example: 120
default: 0
UssAvailabilityStatus:
type: object
required:
- uss
- availability
properties:
uss:
type: string
description: >-
Client ID (matching their `sub` in access tokens) of the USS to
which this availability applies.
availability:
$ref: '#/components/schemas/UssAvailabilityState'
UssAvailabilityState:
type: string
enum:
- Unknown
- Normal
- Down
description: >-
A USS is presumed to be in the Unknown state absent indication otherwise
by a USS with availability arbitration scope. Upon determination via
availability arbitration, a USS is Down when it does not respond
appropriately, and a Down USS may not perform the following operations
in the DSS:
* Create an operational intent in the Accepted or Activated states
* Modify an operational intent whose new or unchanged state is Accepted
or Activated
* Delete an operational intent
A USS in the Unknown state possesses all the capabilities, within the
DSS, of a USS in the Normal state.
SetUssAvailabilityStatusParameters:
type: object
required:
- old_version
- availability
properties:
old_version:
type: string
default: ''
description: >-
Version of USS's availability to change, for consistent
read-modify-write operations and consistent retry behavior.
availability:
$ref: '#/components/schemas/UssAvailabilityState'
UssAvailabilityStatusResponse:
type: object
required:
- status
- version
properties:
version:
type: string
description: >-
Current version of USS's availability. Used to change USS's
availability.
status:
$ref: '#/components/schemas/UssAvailabilityStatus'
#
# Data structures for logging
#
USSLogSet:
type: object
description: >-
The set of log data fulfilling this standard's Logging requirements.
properties:
messages:
description: >-
Outgoing messages sent to other USSs and the DSS, and incoming
messages received from other USSs, including instances where an
expected response to a request is not received.
type: array
items:
$ref: '#/components/schemas/ExchangeRecord'
default: [ ]
operator_notifications:
description: >-
Instances of operator notifications as specifically required within
this standard.
type: array
items:
$ref: '#/components/schemas/UserNotificationRecord'
default: [ ]
operator_inputs:
description: >-
Instances of operator input as specifically required within this
standard.
type: array
items:
$ref: '#/components/schemas/UserInputRecord'
default: [ ]
operator_associations:
description: >-
For a USS that manages operational intents, associations of an
operator with operational intents that transitioned to the Accepted
state.
type: array
items:
$ref: '#/components/schemas/OperatorAssociation'
default: [ ]
planning_attempts:
description: >-
For a USS that manages operational intents, instances where an
operational intent could not be planned or replanned due to
conflicts with other operational intents or constraints.
type: array
items:
$ref: '#/components/schemas/PlanningRecord'
default: [ ]
operational_intent_positions:
description: >-
For a USS performing conformance monitoring, all position data used
for conformance monitoring that is ingested from the UA.
type: array
items:
$ref: '#/components/schemas/OperationalIntentPositions'
default: [ ]
constraint_provider_associations:
description: >-
For a USS that performs constraint management, associations of an
authorized constraint provider with all constraints that transition
to the valid state.
type: array
items:
$ref: '#/components/schemas/ConstraintProviderAssociation'
default: [ ]
ExchangeRecord:
type: object
description: Details of a request/response data exchange.
required:
- url
- method
- recorder_role
- request_time
- request_source
properties:
url:
type: string
description: Full URL of request.
method:
type: string
description: HTTP verb used by requestor (e.g., "PUT," "GET," etc.)
headers:
description: >-
Set of headers associated with request or response. Requires
'Authorization:' field (at a minimum)
type: array
items:
type: string
default: [ ]
recorder_role:
type: string
description: >-
A coded value that indicates the role of the logging USS: 'Client'
(initiating a request to a remote USS) or 'Server' (handling a
request from a remote USS)
enum:
- Client
- Server
request_time:
description: The time at which the request was sent/received.
anyOf:
- $ref: '#/components/schemas/Time'
request_body:
description: Base64-encoded body content sent/received as a request.
type: string
default: ''
response_time:
description: The time at which the response was sent/received.
anyOf:
- $ref: '#/components/schemas/Time'
response_body:
type: string
default: ''
description: >-
Base64-encoded body content sent/received in response to request.
response_code:
type: integer
format: int32
default: 0
description: HTTP response code sent/received in response to request.
problem:
type: string
description: >-
'Human-readable description of the problem with the exchange, if any.'
ErrorReport:
type: object
description: A report informing a server of a communication problem.
required:
- exchange
properties:
report_id:
type: string
maxLength: 128
description: >-
ID assigned by the server receiving the report. Not populated when
submitting a report.
exchange:
anyOf:
- $ref: '#/components/schemas/ExchangeRecord'
description: >-
The request (by this USS) and response associated with the error.
PositionRecord:
type: object
description: >-
A record of vehicle telemetry information received by this USS
(typically for conformance monitoring).
required:
- time_received
- telemetry
properties:
time_received:
anyOf:
- $ref: '#/components/schemas/Time'
description: Time that this position data was received by the USS
telemetry:
$ref: '#/components/schemas/VehicleTelemetry'
OperationalIntentPositions:
type: object
description: >-
A record of position data gathered through the course of an operational
intent
required:
- operational_intent_id
properties:
positions:
type: array
items:
$ref: '#/components/schemas/PositionRecord'
default: [ ]
operational_intent_id:
description: ID of the operational intent associated with `positions`
anyOf:
- $ref: '#/components/schemas/EntityID'
PlanningRecord:
type: object
description: >-
A record of a single attempt to (successfully or unsuccessfully) create
or modify an operational intent.
required:
- time
- ovns
properties:
time:
anyOf:
- $ref: '#/components/schemas/Time'
description: Time that this planning event occurred
ovns:
description: >-
OVNs the planning USS was aware of when it was planning the
operational intent
type: array
default: [ ]
items:
$ref: '#/components/schemas/EntityOVN'
missing_operational_intents:
description: >-
List of missing operational intents (for planning attempts that were
denied by the DSS with code 409)
type: array
items:
$ref: '#/components/schemas/EntityID'
default: [ ]
missing_constraints:
description: >-
List of missing constraints (for planning attempts that were denied
by the DSS with code 409)
type: array
items:
$ref: '#/components/schemas/EntityID'
default: [ ]
operational_intent_id:
description: ID of the operational intent being planned
anyOf:
- $ref: '#/components/schemas/EntityID'
problem:
type: string
description: >-
A free text description of the problem(s) encountered during this
planning attempt.
UserNotificationRecord:
type: object
description: User notification record.
required:
- triggering_event_time
- notification_time
- notification_triggering_event
properties:
triggering_event_time:
anyOf:
- $ref: '#/components/schemas/Time'
description: Time of the notification triggering event
notification_time:
anyOf:
- $ref: '#/components/schemas/Time'
description: Time at which the user was notified
notification_details:
type: string
description: >-
Description of information that was provided to the user, as per the
referenced notification_triggering_event requirement
notification_triggering_event:
type: string
description: Requirement ID that pertains to the given notification
enum:
- GEN0400
- GEN0405
- SCD0090
- SCD0095
- ACM0010
- CMSA0115
- CMSA0300
- CSTP0005
- CSTP0010
- CSTP0020
- CSTP0025
- CSTP0030
- CSTO0035
UserInputRecord:
type: object
description: User input record
required:
- triggering_event_time
- operational_intent_id
- input_triggering_event
properties:
triggering_event_time:
anyOf:
- $ref: '#/components/schemas/Time'
description: Time in which user input was received by the USS
operational_intent_id:
anyOf:
- $ref: '#/components/schemas/EntityID'
description: >-
ID of the operational_intent ID pertaining to the user input
input_triggering_event:
type: string
description: Requirement ID that pertains to the given notification
enum:
- OPIN0040
- CMSA0010
- CMSA0025
- CMSA0100
- CMSA0105
- CMSA0110
- CMSA0200
- CMSA0205
- CMSA0210
- CMSA0215
input_details:
type: string
description: >-
Description of the information that was provided by the user, as per
the referenced input_triggering_event requirement
OperatorAssociation:
type: object
description: >-
Association between an operational intent and the operator of that
operational intent
required:
- operational_intent_id
- operator_id
properties:
operational_intent_id:
description: >-
ID of operational intent to which this association pertains
anyOf:
- $ref: '#/components/schemas/EntityID'
operator_id:
description: >-
Unique identifier of the operator responsible for the operational
intent
type: string
ConstraintProviderAssociation:
type: object
description: >-
Association between a constraint and the constraint provider responsible
for that constraint
required:
- constraint_id
- constraint_provider_id
properties:
constraint_id:
description: ID of constraint to which this association pertains
anyOf:
- $ref: '#/components/schemas/EntityID'
constraint_provider_id:
description: >-
Unique identifier of the constraint provider responsible for the
constraint
type: string
#
# ED-269 compliant GeoZone representation
#
GeoZone:
type: object
description: >-
An airspace of defined dimensions, above the land areas or territorial
waters of a State, within which a particular restriction or condition
for UAS flights applies.
required:
- identifier
- country
- type
- restriction
- zone_authority
properties:
identifier:
anyOf:
- $ref: '#/components/schemas/CodeZoneIdentifierType'
description: >-
A string of characters that uniquely identifies the UAS Zone within
the State/Territory identified by the country attribute.
Note - The UAS Zone is uniquely identified worldwide by the
combination of the country and the identifier attributes
country:
anyOf:
- $ref: '#/components/schemas/CodeCountryISOType'
description: >-
The State that has the authority to declare the zone.
Note - There will be no Zone belonging to two States. Not necessary
to code the information that two zones are "in neighboring States"
or "related".
zone_authority:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Authority'
name:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: >-
A free text name by which the zone may be known by the public or by
the UAS community.
type:
anyOf:
- $ref: '#/components/schemas/CodeZoneType'
description: >-
An indication whether the Zone is provided with its common
definition or with a customised definition, for a particular user.
restriction:
anyOf:
- $ref: '#/components/schemas/CodeRestrictionType'
description: >-
An indication if flying in the zone is conditional, forbidden or
unrestricted.
restriction_conditions:
type: array
items:
$ref: '#/components/schemas/ConditionExpressionType'
description: >-
An indication of the conditions under which the zone can be used
region:
type: integer
format: int32
minimum: 0
maximum: 65535
description: >-
Where applicable, identifies a region inside a State where the UAS
Zone is located.
Note 1) identified with a digit between 0-65535 (16 bit),
corresponding to a list of regions pre-defined for each State.
Note 2) this attribute is intended to facilitate extracting sub-sets
of data, for specific regions
reason:
items:
$ref: '#/components/schemas/CodeZoneReasonType'
description: >-
A coded indication for the reason that led to the establishment of
the zone.
maxItems: 9
type: array
other_reason_info:
type: string
maxLength: 30
description: >-
A free text description of the reason that led to the establishment
of the zone, when not covered by a pre-defined coded value.
regulation_exemption:
anyOf:
- $ref: '#/components/schemas/CodeYesNoType'
description: >-
This is an extension point. It allows adding additional attributes
of national interest through this element.
u_space_class:
anyOf:
- $ref: '#/components/schemas/CodeUSpaceClassType'
description: >-
A code that identifies the category or class of the zone applying a
"USpace concept".
Note: Two (draft) classifications exist, one from Eurocontrol and
one from CORUS. Therefore, two instances of this attribute are
expected, one from each sub-list. This might be later replaced with
separate attributes and separate lists of values.
message:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: >-
A message to be displayed to the user of the zone, typically on the
RPS for the Remote Pilot, to make him/her aware about specific
information associated with the zone (typically when it is not only
a restriction to fly in the zone, thus not only an alert or an
automatic limitation, for example : “image capture prohibited in
this zone”, “frequent strong winds in this zone”, “no landing or
take-off in this zone”). This message is also used to indicate
exemptions from regulation in a zone (see below). Several
information can be grouped in a message, separated by a “/”.
additional_properties:
type: object
default:
description: >-
Indicates that exemptions from the national or European regulations
are allowed in the UAS Zone, that will be detailed via the "message"
property.
CodeZoneIdentifierType:
type: string
maxLength: 7
description: >-
a string of maximum 7 characters that uniquely identifies the area
within a geographical scope.
NOTE (1): This shall not include the country identifier, which is a
separate attribute of the UAS Zone.
NOTE (2): The length of this data type is limited to 7 characters for
compatibility with ARINC 424 and AIXM, where an airspace designator may
have maximum 10 characters. The 10 characters are the result of
concatenating the UAS Zone attributes for country and identifier.
CodeCountryISOType:
type: string
minLength: 3
maxLength: 3
description: >-
A 3 letter identifier of a country or territory using the ISO 3166-1
alpha-3 standard.
NOTE: >-
The ISO 3-letter country codes come with the following advantages:
- allow to distinguish between remote territories and mainland
- are unique, unlike the ICAO Country codes where the same State
could have two or more codes
- are also used in military standards, such as NATO STANAG 1059
INT, which come with well document additions that might be also
useful for UAS areas.
CodeZoneType:
type: string
description: >-
A coded list of values which allows indicating that the definition of a
UAS Zone is specifically customised for a particular UAS or operator.
enum:
- COMMON
- CUSTOMIZED
- PROHIBITED
- REQ_AUTHORISATION
- CONDITIONAL
- NO_RESTRICTION
ConditionExpressionType:
type: string
maxLength: 10000
description: >-
A coded expression that provides information about what is authorised /
forbidden in a zone that has conditional access.
By difference with the “Message” field per zone, this coded expression
is made to be interopreted by the UAS while the “Message” is to
interpreted by the remote pilot.
NOTE: the maximum field length is 10 000 characters.
---------------------- Condition definition language ---------------- •
A list of relevant characteristics (CHARTYPE) has first to be
established per state, and their finite list of acceptable values
(CHARVAL)
• Each chartype and charval fields are defined by a limited set of
characters
• A public document shall give the definitions of each, and provide the
reference to legal or technical characteristics implied
• The Geozone editor per state can use these characteristics, with the
dedicated condition language defined below, to define exact conditions
per zone
• Each UAS Geofencing function shall be loaded with the corresponding
chararacteristic status of the UAS for the intended flight, so as to be
able to apply the conditions , either to generate alerts or to limit the
flight
• If the value of a given characteristic of the condition equation is
not defined in the UAS, the UAS Geofencing function should inform the
pilot in Geoawareness alerting or consider that the zone is forbidden,
by default in automatic Geofencing.
A conditional expression shall be of the following type:
• The UAS is PERMITTED XOR PROHIBITED (exclusive choice) to fly in this
zone at this time IF (Characteristic1) CHARTYPE1 = (Value1) CHARVAL1 AND
CHARTYPE 2 = CHARVAL 2 AND ... AND End IF
OR (...)
...
End OR
• Only the fields in bold need to be edited in the character string,
separated by”/”. Others are implicit.
Examples of CHARTYPE and CHARVALUE:
• CHARTYPE: operator type; Acceptable CHARVAL values:
Military/Police/Firefighting
• CHARTYPE: Operator ID (registration number); Acceptable CHARVAL
values: as per registration format
• CHARTYPE: Operation type: A1 as per EASA Open Types or S1 (National
standard Scenario 1), STS01 (EASA Specific standard scenario) or ...
• CHARTYPE: UTM operation type: Planned/Unplanned,
• CHARTYPE: passengers on board: yes /no Note that it is possible in
each national catalog of chartype and charval items, to define complex
categories of operation/drone /equipment. Example: In nation A, we may
have a type “drone level” with values Low, Medium, High. Each level
corresponds to a defined set of required UAS performance/operation
features/ operator qualification etc. This avoids to code a complex
combination in the geozone database. This conditional expression can
also be used to code a prohibition of image capture in a zone.
Example: PERMITTED/IMAGE CAPTURE=NO/NOISE
CLASS=A/OR/OPERATOR=POLICE
Meaning: >-
the fight is permitted in this zone at that time if No image is
captured (removed or deactivated) and if noise class = class A
(following a known classification) or if the UAS operator is the Police
CodeRestrictionType:
type: string
description: >-
An indication if flying in the zone is conditional, forbidden or
unrestricted.
CodeZoneReasonType:
type: string
description: >-
A coded indication of a reason that justifies the existence of an UAS
Zone
enum:
- AIR_TRAFFIC
- SENSITIVE
- PRIVACY
- POPULATION
- NATURE
- NOISE
- FOREIGN_TERRITORY
- EMERGENCY
- OTHER
CodeUSpaceClassType:
type: string
maxLength: 100
description: >-
A coded identifier for a category or class of the zone applying a
"USpace concept".
NOTE: >-
In the current model version, there is no specific list of values.
For example, the “X”, “Y”, “Z” types of zones as per SESAR JU Corus
project on USpace concept of operation could be used in a future
version. Until a precise list of values is defined, this data type will
be considered as string of characters of maximum 100 characters.
CodeYesNoType:
type: string
description: >-
A coded value that indicates a choice between a positive (yes) or a
negative (no) applicability.
enum:
- YES
- NO
Authority:
type: object
description: >-
A relevant authority that is in charge for authorising, being notified
or providing information for UAS operations in the UAS zone.
Rule: >-
at least one of the following shall be specified - siteURL, email,
phone.
properties:
name:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: The official name of a public or private authority
service:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: >-
The name of a specific department or service within the organisation
contact_name:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: >-
The name or role of a specific person that needs to be contacted
within the organisation
site_url:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: >-
The URL of the public internet site through which the organisation
may be contacted
Note: in the data coding format, this might be further constrained
in order to ensure a valid URL format.
email:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: >-
The e-mail address by which the organisation may be contacted.
Note: in the data coding format, this might be further constrained
in order to ensure a valid e-mail format.
phone:
anyOf:
- $ref: '#/components/schemas/TextShortType'
description: >-
A phone number at which the organisation may be contacted
purpose:
anyOf:
- $ref: '#/components/schemas/CodeAuthorityRole'
description: The role of the Authority in relation with the zone.
interval_before:
type: string
format: duration
description: >-
The minimal time interval required between notification or
authorization request and starting to operate in the zone, in the
format PnnDTnnHnnM (ISO 8601).
CodeAuthorityRole:
type: string
description: >-
A coded list of values indicating the role that an authority has in
relation with the UAS zone.
enum:
- AUTHORIZATION
- NOTIFICATION
- INFORMATION
TextShortType:
type: string
maxLength: 200
description: A free text with a maximum length of 200 characters
paths:
#
# DSS endpoints for operational intents
#
/dss/v1/operational_intent_references/query:
summary: >-
Query all operational intents in the DSS that intersect with a specified
geographic area, altitude-range, and time-range.
description: Interface to operational intent references in the DSS.
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryOperationalIntentReferenceParameters'
required: true
tags:
- Operational intent references
- dss
summary: >-
Query all operational intent references in the specified
area/volume/time from the DSS.
description: >-
Note that this endpoint does not produce any mutations in the DSS
despite using the HTTP POST verb. The HTTP GET verb is traditionally
used for operations like this one, but requiring or using a request body
for HTTP GET requests is non-standard and not supported by some
architectures. POST is used here instead of GET to ensure robust
support for the use of a request body.
operationId: queryOperationalIntentReferences
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/QueryOperationalIntentReferenceResponse'
description: Operational intents were successfully retrieved.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested area was too large.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/dss/v1/operational_intent_references/{entityid}:
summary: >-
Create/read endpoint for a specified operational intent reference in the
DSS.
parameters:
- name: entityid
description: EntityID of the operational intent.
schema:
$ref: '#/components/schemas/EntityID'
in: path
required: true
get:
tags:
- Operational intent references
- dss
summary: >-
Retrieve the specified operational intent reference from the DSS.
operationId: getOperationalIntentReference
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetOperationalIntentReferenceResponse'
description: Operational intent reference was retrieved successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested Entity could not be found.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
put:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutOperationalIntentReferenceParameters'
required: true
tags:
- Operational intent references
- dss
summary: Create the specified operational intent reference in the DSS.
operationId: createOperationalIntentReference
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeOperationalIntentReferenceResponse'
description: >-
An operational intent reference was created successfully in the DSS.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the operational intent in a
disallowed way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/AirspaceConflictResponse'
description: >-
* The provided key did not prove knowledge of all current and
relevant airspace Entities
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'412':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client attempted to transition the operational intent to
Accepted or Activated while marked as Down in the DSS.
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The area of the operational intent is too large.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/dss/v1/operational_intent_references/{entityid}/{ovn}:
summary: >-
Update endpoint for a specified operational intent reference in the DSS.
parameters:
- name: entityid
description: EntityID of the operational intent.
schema:
$ref: '#/components/schemas/EntityID'
in: path
required: true
- name: ovn
description: >-
Opaque version number of the existing operational intent reference.
schema:
$ref: '#/components/schemas/EntityOVN'
in: path
required: true
put:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutOperationalIntentReferenceParameters'
required: true
tags:
- Operational intent references
- dss
summary: Update the specified operational intent reference in the DSS.
operationId: updateOperationalIntentReference
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeOperationalIntentReferenceResponse'
description: >-
An operational intent reference was updated successfully in the DSS.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the operational intent in a
disallowed way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/AirspaceConflictResponse'
description: >-
* The provided key did not prove knowledge of all current and
relevant airspace Entities
* The provided `ovn` does not match the current version of the
existing operational intent.
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'412':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client attempted to transition the operational intent to
Accepted or Activated while marked as Down in the DSS.
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The area of the operational intent is too large.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
delete:
tags:
- Operational intent references
- dss
summary: Remove the specified operational intent reference from the DSS.
operationId: deleteOperationalIntentReference
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeOperationalIntentReferenceResponse'
description: >-
The specified operational intent was successfully removed from the
DSS.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the operational intent in a
disallowed way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested Entity could not be found.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The provided `ovn` does not match the current version of the
existing operational intent.
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'412':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client attempted to delete the operational intent while marked
as Down in the DSS.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# DSS endpoints for constraints
#
/dss/v1/constraint_references/query:
summary: >-
Query all constraint references in the DSS that intersect with a specified
area/volume/time.
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueryConstraintReferenceParameters'
required: true
tags:
- Constraint references
- dss
summary: >-
Query all constraint references in the specified area/volume from the
DSS.
description: >-
Note that this endpoint does not produce any mutations in the DSS
despite using the HTTP POST verb. The HTTP GET verb is traditionally
used for operations like this one, but requiring or using a request body
for HTTP GET requests is non-standard and not supported by some
architectures. POST is used here instead of GET to ensure robust
support for the use of a request body.
operationId: queryConstraintReferences
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/QueryConstraintReferencesResponse'
description: Constraint references were successfully retrieved.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested area was too large.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/dss/v1/constraint_references/{entityid}:
parameters:
- name: entityid
description: EntityID of the constraint.
schema:
$ref: '#/components/schemas/EntityID'
in: path
required: true
summary: >-
Create/read endpoint for a specified constraint reference in the DSS.
get:
tags:
- Constraint references
- dss
summary: Retrieve the specified constraint reference from the DSS.
operationId: getConstraintReference
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetConstraintReferenceResponse'
description: Constraint reference was retrieved successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested Entity could not be found.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
put:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutConstraintReferenceParameters'
required: true
tags:
- Constraint references
- dss
summary: Create the specified constraint reference in the DSS.
operationId: createConstraintReference
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeConstraintReferenceResponse'
description: >-
A constraint reference was created successfully in the DSS.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the constraint in a disallowed
way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* A constraint with the provided ID already exists.
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The area of the constraint is too large.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/dss/v1/constraint_references/{entityid}/{ovn}:
parameters:
- name: entityid
description: EntityID of the constraint.
schema:
$ref: '#/components/schemas/EntityID'
in: path
required: true
- name: ovn
description: >-
Opaque version number of the existing operational intent reference.
schema:
$ref: '#/components/schemas/EntityOVN'
in: path
required: true
summary: >-
Update/delete endpoint for a specified constraint reference in the DSS.
put:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutConstraintReferenceParameters'
required: true
tags:
- Constraint references
- dss
summary: Update the specified constraint reference in the DSS.
operationId: updateConstraintReference
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeConstraintReferenceResponse'
description: >-
A constraint reference was updated successfully in the DSS.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the constraint in a disallowed
way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The provided `ovn` does not match the current version of the
existing constraint.
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The area of the constraint is too large.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
delete:
tags:
- Constraint references
- dss
summary: Delete the specified constraint reference from the DSS.
operationId: deleteConstraintReference
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ChangeConstraintReferenceResponse'
description: The constraint was successfully removed from the DSS.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the constraint in a disallowed
way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested Entity could not be found.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The provided `ovn` does not match the current version of the
existing constraint.
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# DSS endpoints for subscriptions
#
/dss/v1/subscriptions/query:
summary: Subscriptions for airspace updates to a volume of interest.
post:
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QuerySubscriptionParameters'
required: true
tags:
- Subscriptions
- dss
description: >-
Query subscriptions intersecting an area of interest. Subscription
notifications are only triggered by (and contain full information of)
changes to, creation of, or deletion of, Entities referenced by or
stored in the DSS; they do not involve any data transfer (such as remote
ID telemetry updates) apart from Entity information.
Note that this parameter is a JSON object (in the 'request-body'). Note
that either or both of the 'altitude' and 'time' values may be omitted
from this parameter.
Only subscriptions belonging to the caller are returned. This endpoint
would be used if a USS lost track of subscriptions they had created
and/or wanted to resolve an error indicating that they had too many
existing subscriptions in an area.
summary: >-
Query all subscriptions in the specified area/volume from the DSS.
operationId: querySubscriptions
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/QuerySubscriptionsResponse'
description: Subscriptions were retrieved successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'413':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested area was too large.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/dss/v1/subscriptions/{subscriptionid}:
summary: Create/read endpoint for a specific subscription in the DSS.
parameters:
- name: subscriptionid
description: SubscriptionID of the subscription of interest.
schema:
$ref: '#/components/schemas/SubscriptionID'
in: path
required: true
get:
tags:
- Subscriptions
- dss
summary: Retrieve the specified subscription from the DSS.
operationId: getSubscription
description: Retrieve a specific subscription.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetSubscriptionResponse'
description: Subscription information was retrieved successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: A subscription with the specified ID was not found.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
put:
summary: Create the specified subscription in the DSS.
operationId: createSubscription
description: >-
Create a subscription.
Subscription notifications are only triggered by (and contain full
information of) changes to, creation of, or deletion of, Entities
referenced by or stored in the DSS; they do not involve any data
transfer (such as remote ID telemetry updates) apart from Entity
information.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutSubscriptionParameters'
required: true
tags:
- Subscriptions
- dss
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PutSubscriptionResponse'
description: A new subscription was created successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the subscription in a disallowed
way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint or the request.
* Client attempted to request notifications for an Entity type to
which the scopes included in the access token do not provide access.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* A subscription with the specified ID already exists.
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client may have issued too many requests within a small period
of time.
/dss/v1/subscriptions/{subscriptionid}/{version}:
summary: Update/delete a specific subscription in the DSS.
parameters:
- name: subscriptionid
description: SubscriptionID of the subscription of interest.
schema:
$ref: '#/components/schemas/SubscriptionID'
in: path
required: true
- name: version
description: Version of the subscription to be modified.
schema:
type: string
in: path
required: true
put:
summary: Update the specified subscription in the DSS.
operationId: updateSubscription
description: >-
Update a subscription.
Subscription notifications are only triggered by (and contain full
information of) changes to, creation of, or deletion of, Entities
referenced by or stored in the DSS; they do not involve any data
transfer (such as remote ID telemetry updates) apart from Entity
information.
The standard requires each operational intent to have a subscription
that cover the 4D volume of the operational intent. If a USS attempts
to update a subscription upon which an operational intent depends, and
this update would cause the operational intent to lose subscription
coverage, the update will be rejected by the DSS as a bad request.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutSubscriptionParameters'
required: true
tags:
- Subscriptions
- dss
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PutSubscriptionResponse'
description: A subscription was updated successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more input parameters were missing or invalid.
* The request attempted to mutate the subscription in a disallowed
way.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint or the request.
* Client attempted to request notifications for an Entity type to
which the scopes included in the access token do not provide access.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* A subscription with the specified ID already exists and is managed
by a different client.
* The provided `version` does not match the current subscription.
* Despite repeated attempts, the DSS was unable to complete the
update because of other simultaneous changes.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client may have issued too many requests within a small period
of time.
delete:
tags:
- Subscriptions
- dss
summary: Remove the specified subscription from the DSS.
operationId: deleteSubscription
description: >-
The standard requires each operational intent to have a subscription
that cover the 4D volume of the operational intent. If a USS attempts
to delete a subscription upon which an operational intent depends, the
deletion will be rejected by the DSS as a bad request.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSubscriptionResponse'
description: Subscription was successfully removed from DSS.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: A subscription with the specified ID was not found.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* A subscription with the specified ID is managed by a different
client.
* The provided `version` does not match the current subscription.
* Despite repeated attempts, the DSS was unable to complete the
deletion because of other simultaneous changes.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# DSS endpoints for reports
#
/dss/v1/reports:
summary: Error reports of potential operational issues relevant to DSSs.
post:
summary: Report information about communication issues to a DSS.
operationId: makeDssReport
description: >-
Report issues to a DSS. Data sent to this endpoint is archived.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorReport'
required: true
tags:
- Reports
- dss
responses:
'201':
description: A new Report was created successfully (and archived).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorReport'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more parameters were missing or invalid.
* The report could not be parsed, or contains unrecognized data.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint or the request.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# DSS endpoints for USS availability
#
/dss/v1/uss_availability/{uss_id}:
summary: Availability status of a USS
parameters:
- name: uss_id
description: >-
Client ID (matching their `sub` in access tokens) of the USS to which
this availability applies.
schema:
type: string
in: path
required: true
put:
summary: Set availability status of a USS.
operationId: setUssAvailability
description: Set availability status of a USS.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SetUssAvailabilityStatusParameters'
required: true
tags:
- Availability
- dss
responses:
'200':
description: >-
Availability status of specified USS was successfully updated.
content:
application/json:
schema:
$ref: '#/components/schemas/UssAvailabilityStatusResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: '* One or more parameters were missing or invalid.'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint or the request.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
get:
summary: Get availability status of a USS.
operationId: getUssAvailability
description: Get availability status of a USS.
tags:
- Availability
- dss
responses:
'200':
description: >-
Availability status of specified USS was successfully retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/UssAvailabilityStatusResponse'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: '* One or more parameters were missing or invalid.'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint or the request.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# USS endpoints for operational intents
#
/uss/v1/operational_intents/{entityid}:
summary: Query detailed information of an operational intent from a USS.
parameters:
- name: entityid
description: EntityID for this operational intent.
schema:
$ref: '#/components/schemas/EntityID'
in: path
required: true
get:
tags:
- Operational intent details
- p2p_utm
summary: Retrieve the specified operational intent details from a USS.
description: >-
The USS hosting this endpoint returns the details (and reference) of an
operational intent it manages. While the USS has a pending request to
change the operational intent in the DSS, the USS should report the most
recent version the USS knows was accepted by the DSS. So, before a USS
receives a response to create an operational intent reference in the
DSS, it should return 404 if queried for that operational intent at this
endpoint.
operationId: getOperationalIntentDetails
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetOperationalIntentDetailsResponse'
description: Operational intent details were retrieved successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested Entity could not be found.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/uss/v1/operational_intents/{entityid}/telemetry:
summary: >-
Detailed information on the position of an off-nominal operational intent.
parameters:
- name: entityid
description: EntityID for this operational intent.
schema:
$ref: '#/components/schemas/EntityID'
in: path
required: true
get:
tags:
- Operational intent details
- p2p_utm
summary: >-
Query detailed information on the position of an off-nominal operational
intent from a USS.
operationId: getOperationalIntentTelemetry
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetOperationalIntentTelemetryResponse'
description: >-
OperationalIntent telemetry details were retrieved successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested Entity could not be found.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Operational intent is not in a state that provides telemetry.
'412':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: No telemetry data is available.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/uss/v1/operational_intents:
summary: >-
A USS's representation of detailed information about operational intents.
post:
tags:
- Operational intent details
- p2p_utm
summary: Notify a peer USS of changed operational intent details.
operationId: notifyOperationalIntentDetailsChanged
description: >-
Notify a peer USS directly of changed operational intent details
(usually as a requirement of previous interactions with the DSS).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutOperationalIntentDetailsParameters'
required: true
responses:
'204':
description: >-
New or updated full operational intent information received
successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more parameters were missing or invalid.
* The Entity could not be parsed, or contains illegal data.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
* The client identified in the access token is not the manager of
this Entity according to the receiving client's records.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The Entity version specified in this message is lower than a
previously-received notification, or identical to a
previously-received notification and the Entity is different.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# USS endpoints for constraints
#
/uss/v1/constraints/{entityid}:
summary: Query detailed information of a constraint from a USS.
parameters:
- name: entityid
description: EntityID of the constraint.
schema:
$ref: '#/components/schemas/EntityID'
in: path
required: true
get:
tags:
- Constraint details
- p2p_utm
summary: Retrieve the specified constraint details from a USS.
operationId: getConstraintDetails
description: >-
The USS hosting this endpoint returns the details (and reference) of a
constraint it manages. While the USS has a pending request to change
the constraint in the DSS, the USS should report the most recent version
the USS knows was accepted by the DSS. So, before a USS receives a
response to create a constraint reference in the DSS, it should return
404 if queried for that constraint at this endpoint.
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/GetConstraintDetailsResponse'
description: Constraint details were retrieved successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more input parameters were missing or invalid.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: The requested Entity could not be found.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
/uss/v1/constraints:
summary: A USS's representation of detailed information about constraints.
post:
tags:
- Constraint details
- p2p_utm
summary: Notify a peer USS of changed constraint details.
operationId: notifyConstraintDetailsChanged
description: >-
Notify a peer USS directly of changed constraint details (usually as a
requirement of previous interactions with the DSS).
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PutConstraintDetailsParameters'
required: true
responses:
'204':
description: >-
New or updated full constraint information received successfully.
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more parameters were missing or invalid.
* The Entity could not be parsed, or contains illegal data.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
* The client identified in the access token is not the manager of
this Entity according to the receiving client's records.
'409':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The Entity version specified in this message is lower than a
previously-received notification, or identical to a
previously-received notification and the Entity is different.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# USS endpoints for reports
#
/uss/v1/reports:
summary: Error reports of issues communicating with a peer USS.
post:
tags:
- Reports
- p2p_utm
summary: >-
Notify USS of an error encountered that might otherwise go unnoticed.
operationId: makeUssReport
description: >-
Endpoint to provide feedback (errors, etc.) that might otherwise go
unnoticed by this USS. This endpoint is used for all feedback related
to operational intents and constraints.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorReport'
required: true
responses:
'201':
description: Report received and successfully archived.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorReport'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* One or more parameters were missing or invalid.
* The report could not be parsed, or contains unrecognized data.
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
Bearer access token was not provided in Authorization header, token
could not be decoded, or token was invalid.
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
* The access token was decoded successfully but did not include a
scope appropriate to this endpoint.
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: >-
The client issued too many requests in a short period of time.
#
# USS pseudo endpoint for logging
#
/uss/v1/log_sets/{log_set_id}:
summary: General summary
parameters:
- name: log_set_id
description: >-
USS-defined identifier for a set of log entries. For instance, this
ID may refer to all logs associated with a particular reportable
incident, or over a time range for the purpose of metric computation.
schema:
type: string
in: path
required: true
example: com.example.incident.20200107.v4
get:
tags:
- Logging
summary: Get USS logs
operationId: getLogSet
description: >-
A USS will not usually implement this endpoint directly, but rather will
be capable of exporting log data in a format equivalent to the response
format of this pseudo-endpoint according to the requirements of the
standard.
responses:
'200':
description: Log data successfully retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/USSLogSet'
montreal.icea.decea.mil.br:64235/swagger
