5.1.  Identifiers

The normative provisions in this standard are denoted by the URI

http://www.opengis.net/spec/ogcapi-connectedsystems-1/1.0

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

5.2.  Abbreviated terms

In this document the following abbreviations and acronyms are used or introduced:

• API: Application Programming Interface

• CRS: Coordinate Reference System

• CSML: Climate Science Modeling Language

• GPS: Global Positioning System

• ISO: International Organization for Standardization

• MISB: Motion Imagery Standards Board

• OGC: Open Geospatial Consortium

• SAS: Sensor Alert Service

• SensorML: Sensor Model Language

• SI: Système International (International System of Units)

• SOS: Sensor Observation Service

• SPS: Sensor Planning Service

• SWE: Sensor Web Enablement

• TAI: Temps Atomique International (International Atomic Time)

• UML: Unified Modeling Language

• UTC: Coordinated Universal Time

• XML: eXtended Markup Language

• 1D: One Dimensional

• 2D: Two Dimensional

• 3D: Three Dimensional

6.1.  General

All resources defined in Part 1 of this Standard are feature resources, among which the System resource. Part 2 (this document) defines additional resource types to describe and interact with the dynamic data that flows in and out of these systems.

Part 2 of this Standard defines resource types that allow the provision of dynamic data about all kinds of devices, hardware components or processes that can transmit and/or receive data via communication networks (a.k.a. connected systems), including sensors, platforms, robots, human observers, forecast models, computer simulations, etc.

Flows carrying observation and status data coming out of a system are called Datastreams while flows carrying commands sent to a system are called Control Streams (note that the direction of the flow mentionned here is relative to the real system, which is different from the direction of the data flows going in and out of the API server).

6.2.  Design Considerations

TODO

6.3.  Resource Types

As indicated above, while part 1 of this Standard focused on defining “static” feature types, part 2 defines additional resources to deal with dynamic data associated to these features.

Figure 1 shows a UML class diagram of all Connected Systems API resources. Resources defined in part 2 are shown with a solid border while resources that were already defined in part 1 are shown with a dashed light gray outline.

Figure 1 — Class diagram of API resources

The table below provides a short summary description of these resource types:

Table 1 — Overview of resource types defined by this Standard

7.1.  Overview

All resource types defined in this Standard must comply with a common set of rules, many of which are inherited from OGC API — Common.

7.2.  Links

Since resources defined by this Standard can be accessed through multiple collections, any direct link to a resource (referenced by ID) must use its canonical URL.

The canonical URL for a resource is the one that accesses it through the catch-all collection of the corresponding resource type. These collections are rooted at the following URLs:

• {api_root}/datastreams

• {api_root}/observations

• {api_root}/controls

• {api_root}/commands

• {api_root}/system-events

This leads to the following canonical URL templates for individual resources:

• {api_root}/datastreams/{dsId}

• {api_root}/observations/{obsId}

• {api_root}/controls/{csId}

• {api_root}/commands/{cmdId}

• {api_root}/system-events/{evtId}

Table 2

7.3.  Resource IDs

Resource IDs are typically generated by the server and are not guaranteed to be globally unique. However, the server must ensure that IDs are unique within a given resource type.

Table 3

7.4.  Paged Responses

All collections of resource types defined in this Standard support paging.

Table 4

8.1.  Overview

This requirements class specifies how DataStream and Observation resource descriptions are provided using this API.

The DataStream resource represents a dataset that is produced by an (observation) system, that is itself represented by a System feature in the API.

A DataStream represents the real-time data stream coming out of the system as well as the historical data accumulated from such stream. It can be used to provide access to real-time data only, archived data only, or both. The time periods that are part of the Datastream resource description are used to disambiguate between these cases.

A DataStream also implements an homogeneous collection of observations as defined in Extensions to the SSN Ontology. Consequently, Observation resources are available through a sub-collection of a DataStream resource.

8.2.  Datastream Resources

This section defines the properties and associations (links to other resources) that apply to DataStream resources.

Below is the contextual class diagram of the DataStream resource:

Figure 2 — DataStream Resource Diagram

8.3.  Datastream Collections

Top level Datastream resource collections are identified with the item-type 'datastream'.

Table 11

Table 12

Table 13

Table 14

8.4.  Observation Schema Resources

Multiple observation formats can be offered for any given datastream. This API provides a way for the server to communicate the schema (not necessarily a JSON schema) corresponding to each observation format.

Note that, even for standard media types such as O&M JSON, a different schema is needed for each individual datastream because the exact content of the observations result property changes according to the properties being observed.

Table 15

Example — Example

8.5.  Observation Resources

Observation resources are modeled on the corresponding Observation concept defined in the SSN Ontology.

However, since Observation resources exposed through the API are always part of a Datastream (e.g. a type of ObservationCollection), they don’t have to include all mandatory properties as most of them can be factored at the datastream level.

Thus, an Observation resource is not directly associated to a Sensor and a Procedure. Instead, it is the Datastream that the observation is part of, that is attached to a parent System. And it is the System that is, in turn, associated to the Procedure that it implements.

In addition, Observation resources are not restricted to a single observed property. It is thus possible to package the observation result of several properties in a single resource.

Below is the contextual class diagram of the Observation resource:

Figure 3 — Observation Resource Diagram

8.6.  Observation Collections

Top level Observation resource collections are identified with the item-type 'observation'.

Table 20

Table 21

Table 22

In addition to top-level collections, each datastream exposes its own observations as a sub-collection of the DataStream resource.

Table 23

8.7.  Basic Observation Filters

All observation collections support filtering using the query parameters described below.

9.1.  Overview

This requirements class specifies how ControlStream, Command, and CommandStatus resource descriptions are provided using this API.

The ControlStream resource represents a control channel that is used to change the value of certain controllable properties of a feature of interest (which can be a System).

A ControlStream represents the real-time stream of command messages sent to the system, as well as all historical commands received through the channel. It can be used to provide access to real-time commands only, archived commands only, or both. The time periods that are part of the ControlStream resource description are used to disambiguate between these cases.

Command resources are available through a sub-collection of a ControlStream resource, and each command can lead to the creation of one or more status reports (i.e. CommandStatus resources).

9.2.  ControlStream Resources

This section defines the properties and associations (links to other resources) that apply to ControlStream resources.

Below is the contextual class diagram of the ControlStream resource:

Figure 4 — ControlStream Resource Diagram

9.3.  ControlStream Collections

Top level ControlStream resource collections are identified with the item-type 'controlstream'.

Table 30

Table 31

Table 32

In addition to top-level collections, each system exposes its own control streams as a sub-collection.

Table 33

9.4.  Command Schema Resources

Multiple command formats can be offered for any given control stream. This API provides a way for the server to communicate the schema (not necessarily a JSON schema) corresponding to each command format.

Note that a different schema is needed for each individual control stream because the exact content of the command parameters property changes according to the properties being controlled.

Table 34

Example — Example

9.5.  Command Resources

Command resources are a generalization of the Actuation concept defined in the SSN Ontology.

Command resources exposed through the API are always part of a CommandStream, thus they don’t have to include all properties of an Actuation as many of them can be factored at the command stream level.

Thus, a Command resource is not directly associated to an Actuator and a Procedure. Instead, it is the CommandStream that the command is part of, that is attached to a parent System. And it is the System that is, in turn, associated to the Procedure that it implements.

In addition, Command resources are not restricted to a single controllable property (actuable property in SSN). It is thus possible to create commands that contain several parameters, and processing a command can result in actions on several properties at once (e.g. both orientation and FOV of a camera can be modified with a single ‘ptz’ command).

Below is the contextual class diagram of the Command resource:

Figure 5 — Command Resource Diagram

9.6.  Command Collections

Top level Command resource collections are identified with the item-type 'command'.

Table 40

Table 41

Table 42

In addition to top-level collections, each control stream exposes its own commands as a sub-collection of the ControlStream resource.

Table 43

9.7.  Command Status Resources

CommandStatus resources represent a status report describing the state of a command at a given point in time. Several status reports can be issued for any given command.

When commands are processed synchronously, a single status report is provided. But when commands are processed asynchronously, any number of status reports can be provided by the server. They are used to report early acceptance/rejection of the command, scheduling and execution steps as well as failure and cancellations.

Below is the contextual class diagram of the CommandStatus resource:

Figure 6 — Command Status Resource Diagram

10.1.  Overview

SystemEvent resources are used to capture information about various events and maintenance operations occuring on (observing) systems such as recalibrations, part replacements, software updates, relocations/deployments, operator handoffs, decommissioning, etc.

This section predefines a certain number of event types but the list can be extended further by extensions.

10.2.  System Event Resources

SystemEvent resources are modeled on the SensorML Event class.

Below is the contextual class diagram of the SystemEvent resource:

Figure 7 — System Event Diagram

10.3.  System Events Collection

System events are made available as a sub-collection of System resources.

Table 56

10.4.  Simple Queries

System events can be filtered using simple query parameters defined in OGC API — Common — Part 2.

Table 57

Table 58

See Clause 13 for more filtering options.

11.1.  Overview

This requirements class specifies how a server can historize System feature descriptions and make the different versions available through the API.

The history mechanism allows the server to retain older versions of a system’s description, valid at different times. This is useful to capture the exact metadata of the system at a given point in time since it can be needed to properly process older observations (e.g. older calibration tables, etc.).

Typically, a new entry would be added to the system history whenever a description with a newer valid time is created. History entries are also often correlated with system events. A new history entry is typically created when a system event results in important changes to the system’s metadata (such as relocation, recalibration, etc. See Clause 10).

When history is supported, the datetime query parameter can be used to retrieve a system’s description at a specific point in time.

11.2.  System History Collection

A system’s description history is made available as a sub-collection of System resources.

Table 59

11.3.  System Temporal Filtering

When system history is supported, the datetime query parameter used to filter system collections is used to determine what version of the system description(s) should be returned by the server.

Table 60

• The latest description is the one that is currently valid or, if none is currently valid, the last one valid before the current time.

Table 61

Table 62

12.1.  Overview

TODO

13.1.  Overview

This requirements class specifies additional filtering options that may be used to select only a subset of the resources in a collection.

All filters defined in this section are implemented using URL query parameters and can be used in addition to the ones defined in other requirements classes.

TODO

14.1.  Overview

This requirements class specifies how instances of the resource types defined in this Standard are created, replaced, udpated and deleted using the API.

14.2.  Batch Mode

TODO

15.1.  Requirements Class “JSON Encoding”

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc — include::requirements/encoding/json/requirements_class_json.adoc[]

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc - include::../openapi/examples/datastreams/datastream-simple.json[]

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc - include::../openapi/examples/observations/obs-simple.json[]

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc - include::../openapi/examples/observations/obs-location.json[]

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc - include::../openapi/examples/controlStreams/controlStream-ptz.json[]

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc - include::../openapi/examples/commands/command-ptz.json[]

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc - include::../openapi/examples/commandStatus/command-status-accepted.json[]

Unresolved directive in sections/clause_20_requirements_class_json_encoding.adoc - include::../openapi/examples/commandStatus/command-status-completed.json[]

15.2.  Requirements Class “SWE Common JSON Encoding”

Unresolved directive in sections/clause_21_requirements_class_swecommon_json_encoding.adoc — include::requirements/encoding/swecommon/requirements_class_swecommon_json.adoc[]

15.3.  Requirements Class “SWE Common Text Encoding”

Unresolved directive in sections/clause_22_requirements_class_swecommon_text_encoding.adoc — include::requirements/encoding/swecommon/requirements_class_swecommon_text.adoc[]

15.4.  Requirements Class “SWE Common Binary Encoding”

Unresolved directive in sections/clause_23_requirements_class_swecommon_binary_encoding.adoc — include::requirements/encoding/swecommon/requirements_class_swecommon_binary.adoc[]

16.1.  Requirements Class “Websocket Transport”

Unresolved directive in sections/clause_30_requirements_class_websocket.adoc — include::requirements/protocol/websocket/requirements_class_websocket.adoc[]

16.2.  Requirements Class “MQTT Transport”

Unresolved directive in sections/clause_31_requirements_class_mqtt.adoc — include::requirements/protocol/mqtt/requirements_class_mqtt.adoc[]