I. Abstract
<Insert Abstract Text here>
II. Keywords
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, API, OData, openapi, html, MQTT
III. Preface
NOTE: Insert Preface Text here. Give OGC specific commentary: describe the technical content, reason for document, history of the document and precursors, and plans for future work.
There are two ways to specify the Preface: “simple clause” or “full clasuse”
If the Preface does not contain subclauses, it is considered a simple preface clause. This one is entered as text after the .Preface label and must be placed between the AsciiDoc document attributes and the first AsciiDoc section title. It should not be give a section title of its own.
If the Preface contains subclauses, it needs to be encoded as a full preface clause. This one is recognized as a full Metanorma AsciiDoc section with te title “Preface”, i.e. == Preface. (Simple preface content can also be encoded like full preface.)
Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.
V. Submitting Organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
- Fraunhofer-Gesellschaft, Germany
- University of Calgary, Canada
- SensorUp Inc., Canada
- Keys, USA
- DataCove e.U., Austria
1. Scope
NOTE: Insert Scope text here. Give the subject of the document and the aspects of that scope covered by the document.
2. Conformance
This standard defines XXXX.
Requirements for N standardization target types are considered:
AAAA
BBBB
Conformance with this standard shall be checked using all the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.
In order to conform to this OGC® interface standard, a software implementation shall choose to implement:
Any one of the conformance levels specified in Annex A (normative).
Any one of the Distributed Computing Platform profiles specified in Annexes TBD through TBD (normative).
All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified.
3. Normative references
The following documents are referred to in the text in such a way that some or all of their content constitutes requirements of this document. For dated references, only the edition cited applies. For undated references, the latest edition of the referenced document (including any amendments) applies.
Identification of Common Molecular Subsequences. Smith, T.F., Waterman, M.S., J. Mol. Biol. 147, 195–197 (1981)
ZIB Structure Prediction Pipeline: Composing a Complex Biological Workflow through Web Services. May, P., Ehrlich, H.C., Steinke, T. In: Nagel, W.E., Walter, W.V., Lehner, W. (eds.) Euro-Par 2006. LNCS, vol. 4128, pp. 1148–1158. Springer, Heidelberg (2006)
The Grid: Blueprint for a New Computing Infrastructure., Foster, I., Kesselman, C.. Morgan Kaufmann, San Francisco (1999).
Grid Information Services for Distributed Resource Sharing. Czajkowski, K., Fitzgerald, S., Foster, I., Kesselman, C. In: 10th IEEE International Symposium on High Performance Distributed Computing, pp. 181–184. IEEE Press, New York (2001)
The Physiology of the Grid: an Open Grid Services Architecture for Distributed Systems Integration. Foster, I., Kesselman, C., Nick, J., Tuecke, S. Technical report, Global Grid Forum (2002)
National Center for Biotechnology Information, http://www.ncbi.nlm.nih.gov
ISO: ISO 19101-1:2014, Geographic information — Reference model — Part 1: Fundamentals. International Organization for Standardization, Geneva (2014). https://www.iso.org/standard/59164.html.
ISO: ISO 19115-1:2014, Geographic information — Metadata — Part 1: Fundamentals. International Organization for Standardization, Geneva (2014). https://www.iso.org/standard/53798.html.
ISO: ISO 19157:2013, Geographic information — Data quality. International Organization for Standardization, Geneva (2013). https://www.iso.org/standard/32575.html.
ISO: ISO 19139:2007, Geographic information — Metadata — XML schema implementation. ISO (2007).
ISO: ISO 19115-3, Geographic information — Metadata — Part 3: XML schema implementation for fundamental concepts. International Organization for Standardization, Geneva https://www.iso.org/standard/80874.html.
Joan Masó, Lucy Bastin: OGC 15-097r1, OGC® Geospatial User Feedback Standard: Conceptual Model. Open Geospatial Consortium (2016). http://www.opengis.net/doc/IS/guf-conceptual/1.0.0.
Gerhard Gröger, Thomas H. Kolbe, Claus Nagel, Karl-Heinz Häfele: OGC 12-019, OGC City Geography Markup Language (CityGML) Encoding Standard. Open Geospatial Consortium (2012). http://www.opengis.net/spec/citygml/2.0.
Jiyeong Lee, Ki-Joune Li, Sisi Zlatanova, Thomas H. Kolbe, Claus Nagel, Thomas Becker: OGC 14-005r3, OGC® IndoorGML. Open Geospatial Consortium (2014). http://www.opengis.net/doc/IS/indoorgml/1.0.0.
Arliss Whiteside, Jim Greenwood: OGC 06-121r9, OGC Web Service Common Implementation Specification. Open Geospatial Consortium (2010). https://portal.ogc.org/files/?artifact_id=38867.
4. Terms and definitions
This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.
This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.
For the purposes of this document, the following additional terms and definitions apply.
This document uses the terms defined in Sub-clause 5.3 of [OGC06-121r9], which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this standard.
For the purposes of this document, the following additional terms and definitions apply.
term used for exemplary purposes
Note 1 to entry: An example note.
Example
Here’s an example of an example term.
[SOURCE: ISO 19101-1:2014]
5. Conventions
This sections provides details and examples for any conventions used in the document. Examples of conventions are symbols, abbreviations, use of XML schema, or special notes regarding how to read the document.
5.1. Identifiers
The normative provisions in this standard are denoted by the URI
http://www.opengis.net/spec/sensorthings/extensions/2.0
All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.
6. SensorThings API overview
6.1. Who should use the OGC SensorThings API
Organizations that need web-based platforms to manage, store, share, and analyze IoT-based sensor observation data should use the OGC SensorThings API. The OGC SensorThings API simplifies and accelerates the development of IoT applications. Application developers can use this open Standard to connect to various IoT devices and create innovative applications without worrying the daunting heterogeneous protocols of the different IoT devices, gateways and services. IoT device manufacturers can also use OGC SensorThings API as the API can be embedded within various IoT hardware and software platforms, so that the various IoT devices can effortlessly connect with the OGC Standard-compliant servers around the world. In summary, the OGC SensorThings API is transforming the numerous disjointed IoT systems into a fully connected platform where complex tasks can be synchronized and performed.
EDITORIAL NOTE
Add the many non-IoT uses!
6.2. Benefits of the OGC SensorThings API
In today’s world, most IoT devices (e.g., sensors and actuators) have proprietary software interfaces defined by their manufacturers and used selectively. New APIs are often required and developed on an as-needed basis, often in an environment with resource limitations and associated risks. This situation requires significant investment on the part of developers for each new sensor or project involving multiple systems and on the part of the providers of sensors, gateways, and portals or services where observations and measurements are required.
As a standardized data model and interface for sensors in the WoT and IoT, the OGC SensorThings API offers the following benefits: (1) it permits the proliferation of new high value services with lower overhead of development and wider reach, (2) it lowers the risks, time and cost across a full IoT product cycle, and (3) it simplifies the connections between devices-to-devices and devices-to-applications.
6.3. SensorThings API Overview
The OGC SensorThings API data model consists of three main parts: (1) the Sensing part, (2) the Sampling part and (3) the Tasking part. Additionally, SensorThings API supports the following two extensions to the data model: (1) the Sensing Extension (Observations & Measurements) and (2) the Relations extension
The Sensing part allows IoT devices and applications to CREATE, READ, UPDATE, and DELETE (i.e., HTTP POST, GET, PATCH, and DELETE) IoT data and metadata in a SensorThings service. The Sensing part is designed based on the OGC/ISO Observation, Measurements and Samples (OMS) model [OGC 20-004r3 and ISO 19156:2023]. An Observation is modeled as an act that produces a result whose value is an estimate of a property of a given Feature. An Observation instance is characterized by its event time (e.g., resultTime and phenonmenonTime), Feature, ObservedProperty, and the procedure used (often a Sensor). Moreover, Things are also modeled in the SensorThings API. A Thing draws from the same concept as a Host in OMS where a Host is defined as a collection of Observers (defined as Sensor in SensorThings API). Formally, its definition follows the ITU-T definition: “an object of the physical world (physical things) or the information world (virtual things) that is capable of being identified and integrated into communication networks” [ITU-T Y.2060]. The geographical Locations of Things are useful in almost every application and as a result are included as well. For the Things whose location changed, the HistoricalLocations entities offer the history of the Thing’s locations. A Thing also can have multiple Datastreams. A Datastream is a collection of Observations grouped by the same ObservedProperty, Sensor and optionally by Feature and ObservingProcedure. An Observation is an event performed by a Sensor that produces a result whose value is an estimate of an ObservedProperty of any given Feature which may be a proximate or ultimate FeatureofInterest. Details of each above described entity are provided in [sensing-core].
The Sampling part is a new addition to the SensorThings API. As is often the case, an Observation may not be a true representation of the intended Feature’s Property that an Observer may be trying to Observe. Sampling is a common strategy to understand the characteristics of an otherwise difficult-to-measure Property of any feature-of-interest. Samples are created by a Sampler, that may be a physical device or a human being. The method used to execute a Sampling may be described by a SamplingProcedure. This SamplingProcedure can be used by multiple Samplers and conversely, a Sampler may implement multiple SamplingProcedures. However, any Sampling that is executed by a Sampler is always associated with a unique SamplingProcedure. In addition, various preparation steps may be performed on samples both before and after observations are performed on the sample. The entities are explained in detail in Clause 8.
The Tasking part provides a standard way for parameterizing — also called tasking — of taskable IoT devices, such as individual sensors and actuators, composite consumer / commercial / industrial / smart cities in-situ platforms, mobile and wearable devices, or even unmanned systems platforms such as drones, satellites, connected and autonomous vehicles, etc. A Task defines a control action executed by an Actuator. Actuator is modeled to describe a device that is equipped with Tasking Capabilities. A TaskingCapability characterizes an Actuator’s (or in some cases, a Thing’s) ability to trigger a change in ActuableProperties of any FeatureOfInterest by executing the given Task. The Tasking Data Model thus mirrors the Sensing Data Model. Each of these entities are elaborated further in Clause 10.
The Clause 7 and Clause 9 are optional extensions to the data model that may be used for extended data modelling requirements.
7. Sensing Extension (Observations & Measurements)
The Sensing Extension (Observations & Measurements) adds two Classes to the Core data model, that are part of the Observations & Measurements part of the OMS standard: Deployment and ObservingProcedure. These classes can be used to describe additional details of the sensing systems used. This extension’s requirements are grouped in the following requirements class:
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing-extension-om |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirements class 2: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/deployment Requirements class 3: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/observing-procedure |
The entity types, properties and relations added by this extension are depicted in Figure 1.
Figure 1 — OM Extension
7.1. Deployment
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/deployment |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Prerequisites | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/datastream http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/sensor http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/thing |
| Normative statements | Requirement 1: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/deployment/properties Requirement 2: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/deployment/relations |
A Deployment is the association of a Sensor to a Thing that hosts this Sensor, and to the Datastreams that contain the Observations produced by the Sensor while it is/was hosted on this Thing.
Each Deployment links to one Sensor in order to maintain information regarding the relative position of the Sensor with respect to the Host (Thing), to record its deployment time and other additional infortmation. If a sensor is redeployed on to the same Host again, the same Datastream MAY be reused but the same Deployment entity cannot be re-used.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/deployment/properties |
|---|---|
| Included in | Requirements class 2: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/deployment |
| Statement | Each Deployment entity SHALL have the mandatory properties and MAY have the optional properties listed in Table 1. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/deployment/relations |
|---|---|
| Included in | Requirements class 2: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/deployment |
| Statement | Each Deployment entity SHALL have the direct relation between a Deployment entity and other entity types listed in Table 2. |
Table 1 — Properties of a Deployment entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
name | A property provides a label for Deployment entity, commonly a descriptive name. | String | 1 |
description | The description of the Deployment entity. | String | 0..1 |
properties | A JSON Object containing user-annotated properties. | JSON Object | 0..1 |
encodingType | The encoding type of the position property. If the position attribute is present, the encodingType must be specified. | IANA-MediaType | 0..1 |
position | The detailed description of the Sensor or system. The metadata type is defined by encodingType | String | 0..1 |
time | The time instant or period of when the Sensors are deployed and they start producing Datastreams. | TM_Object | 0..1 |
Table 2 — Direct relation between a Deployment entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
Deployment | Sensor | The Sensor that this Deployment describes the positioning of. | Sensor | 1 |
Deployment | Datastreams | The datastreams that contain the Observations that the deployed Sensor created while deployed on the related Thing. | Datastream | 0..1 |
Deployment | Host | The Thing that the linked Sensor is deploye on. | Thing | 1 |
Sensor | Deployments | The Deployments that this Sensor has been involved in. | Deployment | 0..* |
Datastream | Deployments | The deployments that resulted in Observations in this Datastream. | Deployment | 0..* |
Thing | Deployments | The Deployments that have been performed on the Thing. | Deployment | 0..* |
Deployment Examples
The assignment of an array of Sensors onto a platform within a Thing that monitors speed limit and driver distraction on a freeway
The information pertaining to the orientation of moving Sensors when observing moving Features can be described by a Deployment
7.2. ObservingProcedure
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/observing-procedure |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Prerequisites | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/datastream http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/observed-property http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/sensor |
| Normative statements | Requirement 3: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/observing-procedure/properties Requirement 4: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/observing-procedure/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/observing-procedure/properties |
|---|---|
| Included in | Requirements class 3: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/observing-procedure |
| Statement | Each ObservingProcedure entity SHALL have the mandatory properties and MAY have the optional properties listed in Table 3. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sensing/observing-procedure/relations |
|---|---|
| Included in | Requirements class 3: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/observing-procedure |
| Statement | Each ObservingProcedure entity SHALL have the direct relation between an ObservingProcedure entity and other entity types listed in Table 4. |
Table 3 — Properties of an ObservingProcedure entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client | ANY | 1 |
name | A property provides a label for ObservingProcedure entity, commonly a descriptive name. | String | 1 |
definition | The URI of the ObservingProcedure. Dereferencing this URI SHOULD result in a representation of the definition of the ObservingProcedure. | URI | 0..1 |
description | A description about the ObservingProcedure | String | 0..1 |
properties | A JSON Object containing user-annotated properties as key-value pairs | JSON Object | 0..1 |
Table 4 — Direct relation between an ObservingProcedure entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
ObservingProcedure | Datastreams | The Datastreams that implement this ObservingProcedure. | Datastream | 0..* |
ObservingProcedure | ObservedProperties | The ObservedProperties that can be Observed using this ObservingProcedure. | ObservedProperty | 1..* |
ObservingProcedure | Sensors | A Sensor MAY measure an ObservedProperty using zero-to-many ObservingProcedures. | Sensor | 0..* |
Datastream | ObservingProcedure | The ObservingProcedure used to generate the Observations a Datastream contains. | ObservingProcedure | 0..1 |
ObservedProperty | ObservingProcedure | The ObservingProcedures that can be used to observe this ObservedProperty. | ObservingProcedure | 0..* |
Sensor | ObservingProcedures | The ObservingProcedures that a Sensor implements. | Sensor | 0..* |
8. Sampling Extension
The sampling extension adds entity types, properties and relations needed to precicely describe the way samples are taken.
The entity types, properties and relations added by this extension are depicted in Figure 2.
Figure 2 — Sampling Extension
A Sample is a small part or fraction of a larger Feature. The Sample is used as a proxy for the larger Feature because Observations can not be made directly on the Feature itself. The act of taking a Sample is called a Sampling. The Sample is made by a Sampler, following a certain SamplingProcedure, though the Sampler and SamplingProcedure may not always be known and are thus optional.
Example: A small water sample is taken at a certain location in a river. The water sample is packaged and send to a laboratory for analysis.
8.1. Requirement Class: Sampler
The Sampler describes the machine, device, human or other entity that executed the sampling procedure to produce a sample.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/sampler |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 5: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampler/properties Requirement 6: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampler/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampler/properties |
|---|---|
| Included in | Requirements class 4: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/sampler |
| Statement | Each Sampler entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 5. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampler/relations |
|---|---|
| Included in | Requirements class 4: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/sampler |
| Statement | Each Sampler entity SHALL have the direct relation between a Sampler entity and other entity types listed in Table Table 6. |
Table 5 — Properties of a Sampler entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
name | A property provides a label for the Sampler entity, commonly a descriptive name. | String | 1 |
description | The description of the Sampler entity. | String | 0..1 |
properties | A JSON Object containing user-annotated properties. | JSON Object | 0..1 |
samplerType | The type of sampler. | URI | 1 |
Table 6 — Direct relation between a Sampler entity and other entity types
| Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|
Samplings | The Samplings made by this Sampler. | Sampling | 0..* |
SamplingProcedures | A sampler must implement at least one SamplingProcedure, but may implement many. | SamplingProcedure | 1..* |
8.2. Requirement Class: SamplingProcedure
The SamplingProcedure describes the method, or procedure, that the Sampler uses to create Samples. A Sampler must implement at least one SamplingProcedure, but can implement many. A Sample is created using one SamplingProcedure, though this SamplingProcedure may not be known.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/samplingprocedure |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 7: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/samplingprocedure/properties Requirement 8: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/samplingprocedure/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/samplingprocedure/properties |
|---|---|
| Included in | Requirements class 5: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/samplingprocedure |
| Statement | Each SamplingProcedure entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 7. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/samplingprocedure/relations |
|---|---|
| Included in | Requirements class 5: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/samplingprocedure |
| Statement | Each SamplingProcedure entity SHALL have the direct relation between a SamplingProcedure entity and other entity types listed in Table Table 8. |
Table 7 — Properties of a SamplingProcedure entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
name | A property provides a label for the SamplingProcedure entity, commonly a descriptive name. | String | 1 |
description | The description of the SamplingProcedure entity. | String | 0..1 |
encodingType | The encoding type of the location property. If the location attribute is present, the encodingType must also be present. | IANA-MediaType | 0..1 |
location | The location where the Sampling was executed | ANY | 0..1 |
properties | A JSON Object containing user-annotated properties. | JSON Object | 0..1 |
time | The time at which the sampling was executed. It can be a time instant, or, for Samplings that take a longer duration, a time interval. | String | 1 |
Table 8 — Direct relation between a SamplingProcedure entity and other entity types
| Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|
Samplings | The Samplings made using this SamplingProcedure. | Sampling | 0..* |
Samplers | The Samplers that implement this SamplingProcedure. | Sampler | 0..* |
8.3. Requirement Class: Sampling
The Sampling is the act of taking one or more Samples. The Sampling takes Samples from a SampledFeature. The Sampling is executed by a Sampler, following a SamplingProcedure. The Sampling can be associated with a Thing.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/sampling |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Prerequisites | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/feature http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/thing |
| Normative statements | Requirement 9: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampling/properties Requirement 10: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampling/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampling/properties |
|---|---|
| Included in | Requirements class 6: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/sampling |
| Statement | Each Sampling entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 9. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/sampling/relations |
|---|---|
| Included in | Requirements class 6: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/sampling |
| Statement | Each Sampling entity SHALL have the direct relation between a Sampling entity and other entity types listed in Table Table 10. |
Table 9 — Properties of a Sampling entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
name | A property provides a label for the Sampling entity, commonly a descriptive name. | String | 1 |
description | The description of the Sampling entity. | String | 0..1 |
properties | A JSON Object containing user-annotated properties. | JSON Object | 0..1 |
samplerType | The type of sampler. | URI | 0..1 |
Table 10 — Direct relation between a Sampling entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
Sampling | Thing | The Thing that this Sampling is associated with. This is, for example, the Envionmental Monitoring Station where the Sampling took place. | Thing | 0..1 |
Sampling | SampledFeature | The Feature that the Sampling took Samples of, and that the resulting Samples act as a proxy for. This relation is the inverse of the Samplings role. | Feature | 1 |
Sampling | Samples | The Samples made during the execution of this Sampling. This relation is the inverse of the Creator role. | Feature | 0..* |
Sampling | SamplingProcedure | The SamplingProcedure that was followed during the execution of this Sampling. | SamplingProcedure | 0..1 |
Sampling | Sampler | The Sampler that executed this Sampling. | Sampler | 0..1 |
Feature | Samplings | The Samplings that have been created of the source Feature. This relation is the inverse of the SampledFeature role. | Sampling | 1 |
Feature | Creator | The Sampling that created the Sample (source Feature). This relation is the inverse of the Samples role. | Sampling | 0..* |
Thing | Samplings | The Samplings that took place at the source Thing. | Sampling | 0..* |
8.4. Requirement Class: PreparationProcedure
After a sample is taken, a preparation procedure can be applied to it. For example, a specimen of butterfly species is treated with chemicals to preserve it, or a fish is frozen for long-term storage. The difference with the sampling procedure is that the preparation procedure does not result in one or more new samples, but that an existing sample is modified. The PreparationProcedure stores the generic procedure that can be applied to many samples. The PreparationSteps can be instantiated separately for each Sample and can store operational details, such as the exact amouts of chemicals used.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/preparation-procedure |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 11: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-procedure/properties Requirement 12: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-procedure/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-procedure/properties |
|---|---|
| Included in | Requirements class 7: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/preparation-procedure |
| Statement | Each PreparationProcedure entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 11. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-procedure/relations |
|---|---|
| Included in | Requirements class 7: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/preparation-procedure |
| Statement | Each PreparationProcedure entity SHALL have the direct relation between a PreparationProcedure entity and other entity types listed in Table Table 12. |
Table 11 — Properties of a PreparationProcedure entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
name | A property provides a label for the PreparationProcedure entity, commonly a descriptive name. | String | 1 |
description | The description of the PreparationProcedure entity. | String | 0..1 |
definition | The URI of the PreparationProcedure. Dereferencing this URI SHOULD result in a representation of the definition of the PreparationProcedure | URI | 0..1 |
properties | A JSON Object containing user-annotated properties. | JSON Object | 0..1 |
Table 12 — Direct relation between a PreparationProcedure entity and other entity types
| Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|
PreparationSteps | The concrete steps taken when this PreparationProcedure was applied to a Sample. | PreparationStep | 0..* |
8.5. Requirement Class: PreparationStep
When applying a PreparationProcdedure to a Sample, the process is recorded in individual PreparationSteps. For a simple, short PreparationProcedure, a single PreparationStep can be sufficient to record the fact that the preparation procedure was applied to the Sample, and the time at which the procedure was applied. For a complex procedure, that takes a long time, many PreparationSteps may be recorded.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/preparation-step |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Prerequisite | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/feature |
| Normative statements | Requirement 13: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-step/properties Requirement 14: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-step/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-step/properties |
|---|---|
| Included in | Requirements class 8: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/preparation-step |
| Statement | Each PreparationStep entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 13. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/sampling/preparation-step/relations |
|---|---|
| Included in | Requirements class 8: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sampling/preparation-step |
| Statement | Each PreparationStep entity SHALL have the direct relation between a PreparationStep entity and other entity types listed in Table Table 14. |
Table 13 — Properties of a PreparationStep entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
name | A property provides a label for the PreparationStep entity, commonly a descriptive name. | String | 1 |
description | The description of the PreparationStep entity. | String | 0..1 |
definition | The URI defining the PreparationStep. Dereferencing this URI SHOULD result in a representation of the definition of the PreparationStep | URI | 0..1 |
properties | A JSON Object containing user-annotated properties. | JSON Object | 0..1 |
time | The time when the PreparationStep was executed. | TM_Instant | 1 |
Table 14 — Direct relation between a PreparationStep entity and other entity types
| Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|
PreparationProcedure | The PreparationProcedue that this PreparationStep is part of. | PreparationProcedure | 1 |
PreparedSample | The Feature that represents the Sample that this PreparationStep is applied to. | Feature | 1 |
9. Relations Extension
The relations extension adds the ability to relate Things to other Things, Features to other Features, Datastreams to other Datastreams and Observations to other Observations. These relations can be semantically annotated in both directions. Possible use cases include:
Linking sub-systems to their parent systems, both implemented as Things.
Linking Datastreams that contain aggregate data to the source-Datastreams containing the raw data.
Linking Rivers (Features) to the Rivers or Lakes that they flow into.
Linking Rooms to the Floors they are on, and those Floors to the Buildings they are in.
Linking derivative Observations to the source Observations they are derived from.
Relations can link between two Entities in the same service, or link to an external resource.
The entity types, properties and relations added by this extension are depicted in Figure 3.
Figure 3 — Relations Extension
9.1. Requirement Class: RelationRole
When creating a relation between two entities, a key aspect of this relation is what it means that these two entities are related. This meaning for a relation is the role of the relation and is described in the RelationRole entity that is associated with each relation. A relation has two directions. If Entity-A is related to Entity-B with role-1, then Entity-B is related to Entity-A with the inverse of role-1. The RelationRole Entity holds a name and definition for both directions of the relation.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/relationrole |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Prerequisites | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/datastream http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/feature http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/observation http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/thing |
| Normative statements | Requirement 15: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/relationrole/properties Requirement 16: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/relationrole/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/relationrole/properties |
|---|---|
| Included in | Requirements class 9: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/relationrole |
| Statement | Each RelationRole entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 15. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/relationrole/relations |
|---|---|
| Included in | Requirements class 9: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/relationrole |
| Statement | Each RelationRole entity SHALL have the direct relation between a RelationRole entity and other entity types listed in Table Table 16. |
Table 15 — Properties of a RelationRole entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
name | The name of the relation in the source → target direction. Generally, this should be a verb so that Source name Target forms a sentence. | String | 1 |
definition | The URI that defines this role. | String | 0..1 |
inverseName | The name of the relation in the target → source direction. Generally, this should be a verb so that Target name Source forms a sentence. | String | 1 |
inverseDefinition | The URI that defines the inverse of this role. | String | 0..1 |
description | The human readable description of the RelationRole entity. | String | 0..1 |
properties | A JSON Object containing user-annotated properties. | JSON Object | 0..1 |
Table 16 — Direct relation between a RelationRole entity and other entity types
| Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|
DatastreamRelations | The list of Datastream-Datastream relations that this RelationRole describes. | DatastreamRelation | 0..* |
FeatureRelations | The list of Feature-Feature relations that this RelationRole describes. | FeatureRelation | 0..* |
ObservationRelations | The list of Observation-Observation relations that this RelationRole describes. | ObservationRelation | 0..* |
ThingRelations | The list of Thing-Thing relations that this RelationRole describes. | ThingRelation | 0..* |
9.2. Requirement Class: DatastreamRelation
A DatastreamRelation Entity relates a source Datastream to a target Datastream, or to an external resource, using a RelationRole.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/datastreamrelation |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 17: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/datastreamrelation/properties Requirement 18: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/datastreamrelation/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/datastreamrelation/properties |
|---|---|
| Included in | Requirements class 10: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/datastreamrelation |
| Statement | Each DatastreamRelation entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 17. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/datastreamrelation/relations |
|---|---|
| Included in | Requirements class 10: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/datastreamrelation |
| Statement | Each DatastreamRelation entity SHALL have the direct relation between a DatastreamRelation entity and other entity types listed in Table Table 18. |
Table 17 — Properties of a DatastreamRelation entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
externalTarget | A URL or URI of an external target that acts as the target for this relation. If an externalTarget is set, the Source relation must not be set. | String | 0..1 |
Table 18 — Direct relation between a DatastreamRelation entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
DatastreamRelation | Source | The source Datastream for this relation. This is the inverse of TargetDatastreamRelations. | Datastream | 1 |
DatastreamRelation | Target | The target Datastream for this relation. This must be set if, and only if, the externalTarget property is not set. This is the inverse of SourceDatastreamRelations. | Datastream | 0..1 |
Datastream | TargetDatastreamRelations | The list of DatastreamRelation entities where this Datastream is the Source. In other words, following this link leads to the Targets. This is the inverse of Source. | DatastreamRelation | 0..* |
Datastream | SourceDatastreamRelations | The list of DatastreamRelation entities where this Datastream is the Target. In other words, following this link leads to the Sources. This is the inverse of Target. | DatastreamRelation | 0..* |
9.3. Requirement Class: FeatureRelation
A FeatureRelation Entity relates a source Feature to a target Feature, or to an external resource, using a RelationRole.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/featurerelation |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 19: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/featurerelation/properties Requirement 20: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/featurerelation/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/featurerelation/properties |
|---|---|
| Included in | Requirements class 11: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/featurerelation |
| Statement | Each FeatureRelation entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 19. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/featurerelation/relations |
|---|---|
| Included in | Requirements class 11: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/featurerelation |
| Statement | Each FeatureRelation entity SHALL have the direct relation between a FeatureRelation entity and other entity types listed in Table Table 20. |
Table 19 — Properties of a FeatureRelation entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
externalTarget | A URL or URI of an external target that acts as the target for this relation. If an externalTarget is set, the Source relation must not be set. | String | 0..1 |
Table 20 — Direct relation between a FeatureRelation entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
FeatureRelation | Source | The source Feature for this relation. This is the inverse of TargetFeatureRelations. | Feature | 1 |
FeatureRelation | Target | The target Feature for this relation. This must be set if, and only if, the externalTarget property is not set. This is the inverse of SourceFeatureRelations. | Feature | 0..1 |
Feature | TargetFeatureRelations | The list of FeatureRelation entities where this Feature is the Source. In other words, following this link leads to the Targets. This is the inverse of Source. | FeatureRelation | 0..* |
Feature | SourceFeatureRelations | The list of FeatureRelation entities where this Feature is the Target. In other words, following this link leads to the Sources. This is the inverse of Target. | FeatureRelation | 0..* |
9.4. Requirement Class: ObservationRelation
A ObservationRelation Entity relates a source Observation to a target Observation, or to an external resource, using a RelationRole.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/observationrelation |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 21: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/observationrelation/properties Requirement 22: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/observationrelation/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/observationrelation/properties |
|---|---|
| Included in | Requirements class 12: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/observationrelation |
| Statement | Each ObservationRelation entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 21. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/observationrelation/relations |
|---|---|
| Included in | Requirements class 12: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/observationrelation |
| Statement | Each ObservationRelation entity SHALL have the direct relation between a ObservationRelation entity and other entity types listed in Table Table 22. |
Table 21 — Properties of a ObservationRelation entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
externalTarget | A URL or URI of an external target that acts as the target for this relation. If an externalTarget is set, the Source relation must not be set. | String | 0..1 |
Table 22 — Direct relation between a ObservationRelation entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
ObservationRelation | Source | The source Observation for this relation. This is the inverse of TargetObservationRelations. | Observation | 1 |
ObservationRelation | Target | The target Observation for this relation. This must be set if, and only if, the externalTarget property is not set. This is the inverse of SourceObservationRelations. | Observation | 0..1 |
Observation | TargetObservationRelations | The list of ObservationRelation entities where this Observation is the Source. In other words, following this link leads to the Targets. This is the inverse of Source. | ObservationRelation | 0..* |
Observation | SourceObservationRelations | The list of ObservationRelation entities where this Observation is the Target. In other words, following this link leads to the Sources. This is the inverse of Target. | ObservationRelation | 0..* |
9.5. Requirement Class: ThingRelation
A ThingRelation Entity relates a source Thing to a target Thing, or to an external resource, using a RelationRole.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/thingrelation |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 23: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/thingrelation/properties Requirement 24: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/thingrelation/relations |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/thingrelation/properties |
|---|---|
| Included in | Requirements class 13: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/thingrelation |
| Statement | Each ThingRelation entity SHALL have the mandatory properties and MAY have the optional properties listed in Table Table 23. |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/relations/thingrelation/relations |
|---|---|
| Included in | Requirements class 13: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/relations/thingrelation |
| Statement | Each ThingRelation entity SHALL have the direct relation between a ThingRelation entity and other entity types listed in Table Table 24. |
Table 23 — Properties of a ThingRelation entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. Its value is computed by the server when creating the entity unless specified by the client. | ANY | 1 |
externalTarget | A URL or URI of an external target that acts as the target for this relation. If an externalTarget is set, the Source relation must not be set. | String | 0..1 |
Table 24 — Direct relation between a ThingRelation entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
ThingRelation | Source | The source Thing for this relation. This is the inverse of TargetThingRelations. | Thing | 1 |
ThingRelation | Target | The target Thing for this relation. This must be set if, and only if, the externalTarget property is not set. This is the inverse of SourceThingRelations. | Thing | 0..1 |
Thing | TargetThingRelations | The list of ThingRelation entities where this Thing is the Source. In other words, following this link leads to the Targets. This is the inverse of Source. | ThingRelation | 0..* |
Thing | SourceThingRelations | The list of ThingRelation entities where this Thing is the Target. In other words, following this link leads to the Sources. This is the inverse of Target. | ThingRelation | 0..* |
10. Actuation Extension
All actuation entites are grouped into the following requirements class:
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirements class 15: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/tasking-capability Requirements class 16: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/task Requirements class 17: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/actuator |
The entity types, properties and relations added by this extension are depicted in Figure 4.
Figure 4 — Tasking Extension
10.1. Tasking Capability
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/tasking-capability |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Prerequisites | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/feature http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/observed-property http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/thing |
| Normative statements | Requirement 25: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/tasking-capability/properties Requirement 26: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/tasking-capability/relations |
The TaskingCapability entity contains information about the capabilities of the taskable device. It contains all the parameters that can be used for controlling the device. SWE Common JSON encoding rules [OGC17-011r2] are used to define these parameters for TaskingCapability.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/tasking-capability/properties |
|---|---|
| Included in | Requirements class 15: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/tasking-capability |
| Statement | Each TaskingCapability entity SHALL have the mandatory properties and MAY have the optional properties listed in Table 25. |
Table 25 — Properties of a TaskingCapability entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. | ANY | 1 |
name | A property provides a label for TaskingCapability entity, commonly a descriptive name | String | 1 |
description | The description of the Deployment entity | String | 0..1 |
properties | A JSON Object containing user-annotated properties as key-value pairs | JSON Object | 0..1 |
taskingParameters | The taskingParameters property describes optional and mandatory tasking parameters. Clients use the definition to provide corresponding tasking parameter values. To ensure common understanding between client and server, a common exchange protocol is used to express both descriptions and tasking parameter values. SensorThings uses the JSON encoding defined in OGC 17-011r2 to define taskingParameters | JSON Object (SWE-Common AbstractDataComponent) | 1 |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/tasking-capability/relations |
|---|---|
| Included in | Requirements class 15: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/tasking-capability |
| Statement | Each TaskingCapability entity SHALL have the direct relation between a TaskingCapability entity and other entity types listed in Table 26. |
Table 26 — Direct relation between a TaskingCapability entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
TaskingCapability | Tasks | A TaskingCapability has zero-to-many Tasks. A Task has one-and-only-one TaskingCapability | Task | 0..* |
TaskingCapability | Actuator | A TaskingCapability has one-and-only-one Actuator. An Actuator has zero-to-many TaskingCapabilities | Actuator | 1 |
TaskingCapability | Thing | A TaskingCapability has one-and-only-one Thing. A Thing has zero-to-many TaskingCapabilities | Thing | 1 |
TaskingCapability | UltimateFeatureOfInterest | A TaskingCapability may have an UltimateFeatureOfInterest upon which a TaskingCapability can execute a Task. A Feature may have zero-to-many TaskingCapabilities | Feature | 0..1 |
TaskingCapability | ActuableProperties | A TaskingCapability may have one or more ObservedProperties that are changed by the Actuator. | ObservedProperty | 0..* |
Thing | TaskingCapabilities | The TaskingCapabilities that are related to the Thing. | TaskingCapability | 0..* |
Feature | TaskingCapabilities | The TaskingCapabilities that are can be used to control aspects of the Feature. | TaskingCapability | 0..* |
ObservedProperty | TaskingCapabilities | The TaskingCapabilities that are related to the ObservedProperty. | TaskingCapability | 0..* |
10.2. Task
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/task |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Prerequisite | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/sensing/feature |
| Normative statements | Requirement 27: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/task/properties Requirement 28: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/task/relations |
The Task entity represents a task that can be executed by the Actuator. The Task entity contains the parameters that are required to execute the task. SWE Common JSON encoding rules [OGC17-011r2] are used to define these parameters for the Task entity.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/task/properties |
|---|---|
| Included in | Requirements class 16: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/task |
| Statement | Each Task entity SHALL have the mandatory properties and MAY have the optional properties listed in Table 27. |
Table 27 — Properties of a Task entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. | ANY | 1 |
creationTime | The time when the task is created. This time SHALL only be added automatically by the service. | TM_Instant | 1 |
runTime | The total time taken when the task is executed | TM_Object | 0..1 |
status | The status of the task. The status of the task can be one of the values listed in Table 29. | CodeList | 0..1 |
taskingParameters | The taskingParameters property describes optional and mandatory tasking parameters. Clients use the definition to provide corresponding tasking parameter values. To ensure common understanding between client and server, a common exchange protocol is used to express both descriptions and tasking parameter values. SensorThings uses the JSON encoding for SWE Common data block defined in OGC 08-094r1 to define taskingParameters. taskingParameters is a SWE Common data block and MUST have key-value pairs in a JSON object. Key MUST be the name described in TaskingCapablity’s taskingParamaters and value MUST be the value of that parameter for this Task. | JSON Object (SWE-Common AbstractDataComponent) | 1 |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/task/relations |
|---|---|
| Included in | Requirements class 16: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/task |
| Statement | Each Task entity SHALL have the direct relation between a Task entity and other entity types listed in Table 28. |
Table 28 — Direct relation between a Task entity and other entity types
| Source Entity Type | Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|---|
Task | TaskingCapability | A Task has one-and-only-one TaskingCapability. | TaskingCapability | 1 |
Task | ProximateFeatureOfInterest | A Task may have a Feature that is the target of the Task. | Feature | 0..1 |
Feature | Tasks | Feature may have many Tasks associated to it. | Task | 0..* |
Table 29 — List of Status Codes used for identifying the status of the Task entity
| StatusCode | Description |
|---|---|
| Created | Created status |
| Running | Running status |
| Completed | Completed status |
| Rejected | Rejected status |
| Failed | Failed status |
10.3. Actuator
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/actuator |
|---|---|
| Obligation | requirement |
| Target type | Target Type: Data Model |
| Normative statements | Requirement 29: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/actuator/properties Requirement 30: http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/actuator/relations |
An Actuator is a device that can be controlled/tasked. The Actuator entity contains information and metadata about taskable actuator. Each TaskingCapability has one Actuator and defines the parameters that can be set/tasked for the Actuator.
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/actuator/properties |
|---|---|
| Included in | Requirements class 17: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/actuator |
| Statement | Each Actuator entity SHALL have the mandatory properties and MAY have the optional properties listed in Table 30. |
Table 30 — Properties of an Actuator entity
| Name | Description | Data Type | Multiplicity |
|---|---|---|---|
id | A unique, read-only property that serves as an identifier for the entity. | ANY | 1 |
name | A property provides a label for Actuator entity, commonly a descriptive name | String | 1 |
description | The description of the Actuator entity | String | 0..1 |
encodingType | The encoding type of the metadata property. If the metadata attribute is present, the encodingType must be specified. A list of suggested values can be found in Table 32. | IANA-MediaType | 0..1 |
metadata | The metadata property provides detailed information about the Actuator entity. The content of the metadata property is implementation dependent. | ANY | 0..1 |
properties | A JSON Object containing user-annotated properties as key-value pairs | JSON Object | 0..1 |
| Identifier | http://www.opengis.net/spec/sensorthings/extensions/2.0/req/datamodel/actuation/actuator/relations |
|---|---|
| Included in | Requirements class 17: http://www.opengis.net/spec/sensorthings/extensions/2.0/req-class/datamodel/actuation/actuator |
| Statement | Each Actuator entity SHALL have the direct relation between an Actuator entity and other entity types listed in Table 31. |
Table 31 — Direct relation between an Actuator entity and other entity types
| Role | Description | Target Entity Type | Multiplicity |
|---|---|---|---|
TaskingCapability | An Actuator has zero-to-many TaskingCapabilities. A TaskingCapability has one-and-only-one Actuator | TaskingCapability | 0..* |
Table 32 — List of some code values used for identifying types for the encodingType of the Actuator entity
| Actuator Encoding Type | IANA-MediaType |
|---|---|
| application/pdf | |
| HTML | text/html |
The Actuator encodingType lets clients know how to interpret metadata’s value(s). This list is not exhoustive and other values may also be used.
11. Batch Request Extension
Batch requests are a way to combine multiple requests into one. https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_BatchRequestshttps://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_BatchRequestsandResponses
The Batch Request Extension is an abstract API extension, meaning it can be applied to both the HTTP and MQTT bindings, and any other binding that implements the abstract API.
EDITORIAL NOTE
Describe v2.0/$batch as OData Action
11.1. Requirement Class A or Requirement A Example
intro text for the requirement class.
Use the following table for Requirements Classes.
11.1.1. Requirement 1
intro text for the requirement.
Use the following table for Requirements, number sequentially.
11.1.2. Requirement 2
intro text for the requirement.
Use the following table for Requirements, number sequentially.
12. Data Array Extension
The Data Array Extension describes a resultformat that allows a more compact representation of data. It also describes an interface that allows for more efficient upload of observations.
12.1. Requesting Data
intro text for the requirement class.
Use the following table for Requirements Classes.
12.2. Creating Observations
12.2.1. Requirement 1
intro text for the requirement.
Use the following table for Requirements, number sequentially.
12.2.2. Requirement 2
intro text for the requirement.
Use the following table for Requirements, number sequentially.
Annex A
(informative)
Conformance Class Abstract Test Suite (Normative)
NOTE: Ensure that there is a conformance class for each requirements class and a test for each requirement (identified by requirement name and number)
Annex B
(informative)
Revision History
Table B.1 — Revision History
| Date | Release | Editor | Primary clauses modified | Description |
|---|---|---|---|---|
| 2023-05-09 | 0.1 | Hylke van der Schaaf | all | initial version |
Bibliography
NOTE: The TC has approved Springer LNCS as the official document citation type.
Springer LNCS is widely used in technical and computer science journals and other publications
– Actual References:
[n] Journal: Author Surname, A.: Title. Publication Title. Volume number, Issue number, Pages Used (Year Published)
[1] OGC: OGC Testbed 12 Annex B: Architecture (2015).