diff --git a/23-019.adoc b/23-019.adoc index 4129fac..d99188c 100644 --- a/23-019.adoc +++ b/23-019.adoc @@ -12,9 +12,11 @@ :published-date: 2029-03-30 :fullname: Hylke van der Schaaf :fullname_2: Steve Liang +:fullname_3: Kathi Schleidt +:fullname_4: Humaid Kidwai :docsubtype: implementation :keywords: ogcdoc, OGC document, API, OData, openapi, html, MQTT -:submitting-organizations: Fraunhofer-Gesellschaft, Germany; University of Calgary, Canada; SensorUp Inc., Canada; Keys, USA; DataCove e.U., Austria +:submitting-organizations: Fraunhofer-Gesellschaft, Germany; University of Calgary, Canada; DataCove e.U., Austria :mn-document-class: ogc :mn-output-extensions: xml,html,doc,pdf :local-cache-only: @@ -44,25 +46,27 @@ include::sections/clause_05_conventions.adoc[] include::sections/clause_06_overview.adoc[] -include::sections/clause_07a_meta_model.adoc[] +include::sections/clause_07a_sensing_core_entities.adoc[] -include::sections/clause_07b_sensing_entities.adoc[] +include::sections/clause_07b_sensing_OM_extension.adoc[] include::sections/clause_07c_sampling_entities.adoc[] include::sections/clause_07d_actuation_entities.adoc[] -include::sections/clause_08a_abstract_api_overview.adoc[] +include::sections/clause_08a_meta_model.adoc[] -include::sections/clause_08b_rest_api_read.adoc[] +include::sections/clause_08b_abstract_api_overview.adoc[] -include::sections/clause_08c_rest_api_create_update_delete.adoc[] +include::sections/clause_08c_rest_api_read.adoc[] -include::sections/clause_08d_rest_api_batch_requests.adoc[] +include::sections/clause_08d_rest_api_create_update_delete.adoc[] -include::sections/clause_08e_rest_api_data_array.adoc[] +include::sections/clause_08e_rest_api_batch_requests.adoc[] -include::sections/clause_08f_pubsub_api.adoc[] +include::sections/clause_08g_pubsub_api.adoc[] + +include::sections/clause_08f_rest_api_data_array.adoc[] include::sections/clause_09a_bindings_http.adoc[] diff --git a/images/GRP0001.png b/images/GRP0001.png new file mode 100644 index 0000000..c3ecb9e Binary files /dev/null and b/images/GRP0001.png differ diff --git a/images/GRP0002.png b/images/GRP0002.png new file mode 100644 index 0000000..b14d15e Binary files /dev/null and b/images/GRP0002.png differ diff --git a/images/GRP0003.png b/images/GRP0003.png new file mode 100644 index 0000000..7b3eab5 Binary files /dev/null and b/images/GRP0003.png differ diff --git a/sections/clause_06_overview.adoc b/sections/clause_06_overview.adoc index 4a42834..f660268 100644 --- a/sections/clause_06_overview.adoc +++ b/sections/clause_06_overview.adoc @@ -50,14 +50,16 @@ For the Things whose location changed, the HistoricalLocations entities offer th 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 <>. +Details of each above described entity are provided in <>. 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. -In order to generate Samplings, a Sampler, that may be any physical device or even a human being part of a survey campaign, must carefully select a SamplingProcedure. -Samplings may be generated by a sequence of SamplingProcedures (and vice-versa), however a Sampler must employ a unique SamplingProcedure to maintain unique Sampling-Sampler-SamplingProcedure relationships. -In scenarios where a Feature is not directly available for Sampling, a PreparationProcedure composed of multiple PreparationSteps may optionally be used to generate a PreparedFeature. +In order to generate Samplings, a Sampler, that may be any physical device (or even a human being part of a survey campaign), must carefully select a SamplingProcedure. +A Sampling may be generated by a SamplingProcedure. +This SamplingProcedure can be used by multiple Samplers and conversely, a Sampler may implement multiple SamplingProcedures. +However, any Sampling that is generated by a Sampler is always associated with a unique SamplingProcedure. +In scenarios where a Feature is not directly available for Sampling, a PreparationProcedure composed of multiple PreparationSteps may optionally be used to generate a PreparedSample (Feature entity). The entities are explained in detail in <>. 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. @@ -67,7 +69,7 @@ A TaskingCapability characterizes an Actuator's (or in some cases, a Thing's) ab The Tasking Data Model thus mirrors the Sensing Data Model. Each of these entities are elaborated further in <>. -The <> and <> are optional extensions to the data model that may be used for extended data modelling requirements. +The <> and <> are optional extensions to the data model that may be used for extended data modelling requirements. [[observations-measurements]] === SensorThings API and Relation to ISO/OGC Observations, Measurements and Samples @@ -116,13 +118,15 @@ SensorThings API uses the term of Sensor to describe the Observer that is used i [[revision-differences]] === SensorThings API 2.0 changes from 1.1 [#sta-changes,reftext='{table-caption} {counter:table-num}'] -.Changes in the SensorThings API 2.0 data model compared to v1.x +.Changes in the SensorThings API 2.0 data model compared to v1.1 [width="100%",cols="5,20a",options="header"] |==== | *Entity* | *Changes* | Sensor | description attribute is now optional and not mandatory | Thing | description attribute is now optional and not mandatory -| Location | description attribute is now optional and not mandatory +| Location | +- description attribute is now optional and not mandatory +- For a Thing having multiple Locations, these Locations MAY be in same encodingTypes OR the encodingTypes MAY be be in different spaces (e.g., one encodingType in Geometrical space and one encodingType in Topological space). | Datastream | - description attribute is now optional and not mandatory @@ -144,10 +148,8 @@ SensorThings API uses the term of Sensor to describe the Observer that is used i === Relation to OASIS-OData -The OGC SensorThings API v2 interface is not an OData interface. +The OGC SensorThings API v2 interface is not an OData interface and does not claim to be an OData service. It specifies a subset of the OData interface, and extends it at the same time. - -An SensorThings API Server implementation can implement the full OData specification. -An OData client can access a SensorThings API service. +An SensorThings API Server implementation can implement the full OData specification. An OData client can access a SensorThings API service. EDITOR: Check if this is true diff --git a/sections/clause_07b_sensing_entities.adoc b/sections/clause_07a_sensing_core_entities.adoc similarity index 97% rename from sections/clause_07b_sensing_entities.adoc rename to sections/clause_07a_sensing_core_entities.adoc index f55afa5..2d71e49 100644 --- a/sections/clause_07b_sensing_entities.adoc +++ b/sections/clause_07a_sensing_core_entities.adoc @@ -1,7 +1,5 @@ -[[sensing-entities]] -=== Sensing Entities - - +[[sensing-core]] +== The SensorThings API Sensing Core Entities All data model requirements classes are grouped in the following requirements class: @@ -17,15 +15,13 @@ requirement:: {identifier}/req-class/datamodel/sensing/thing requirement:: {identifier}/req-class/datamodel/sensing/location requirement:: {identifier}/req-class/datamodel/sensing/historical-location requirement:: {identifier}/req-class/datamodel/sensing/datastream -requirement:: {identifier}/req-class/datamodel/sensing/deployment -requirement:: {identifier}/req-class/datamodel/sensing/location -requirement:: {identifier}/req-class/datamodel/sensing/historical-location -requirement:: {identifier}/req-class/datamodel/sensing/datastream -requirement:: {identifier}/req-class/datamodel/sensing/deployment requirement:: {identifier}/req-class/datamodel/sensing/sensor +requirement:: {identifier}/req-class/datamodel/sensing/observed-property +requirement:: {identifier}/req-class/datamodel/sensing/observation +requirement:: {identifier}/req-class/datamodel/sensing/feature ==== -[[sensing-entities2]] +[[sensing-entities]] === Sensing Entities The OGC SensorThings API v2.0 depicts the Core Sensing entities in Figure {counter:figure-num} @@ -36,11 +32,10 @@ image::images/GRP0001.png[Sensing Core, align="center"] In this section, we define each entity depicted in <> and its relationships with other entities. Additionally, we also provide examples to model the entities in different contexts. -==== Requirement Class: Thing +[[thing]] +==== Thing [requirements_class] -.thing - ==== [%metadata] identifier:: {identifier}/req-class/datamodel/sensing/thing @@ -130,8 +125,6 @@ A Thing SHOULD have only one Location. However, in some complex use cases, a Thing MAY have more than one Location representations. In such case, the Thing MAY have more than one Locations. -These Locations SHALL have different encodingTypes and the encodingTypes SHOULD be in different spaces (e.g., one encodingType in Geometrical space and one encodingType in Topological space). - | `HistoricalLocation` | HistoricalLocations | One mandatory to many optional | A Thing has zero-to-many HistoricalLocations. A HistoricalLocation has one-and-only-one Thing. @@ -893,7 +886,7 @@ Each Feature entity SHALL have the mandatory properties and MAY have the optiona [%metadata] identifier:: {identifier}/req/datamodel/sensing/feature/relations -Each Thing entity SHALL have the direct relation between a Thing entity and other entity types listed in Table XX. +Each Feature entity SHALL have the direct relation between a Feature entity and other entity types listed in Table {counter:table-num}. ==== diff --git a/sections/clause_07c_sensing_OM_extension.adoc b/sections/clause_07b_sensing_OM_extension.adoc similarity index 99% rename from sections/clause_07c_sensing_OM_extension.adoc rename to sections/clause_07b_sensing_OM_extension.adoc index b8596ed..feba78e 100644 --- a/sections/clause_07c_sensing_OM_extension.adoc +++ b/sections/clause_07b_sensing_OM_extension.adoc @@ -1,5 +1,3 @@ -:sectnums: |,all| -:sectanchors: [[sensing-OM-extension]] === Sensing Extension (Observations & Measurements) diff --git a/sections/clause_07d_actuation_entities.adoc b/sections/clause_07d_actuation_entities.adoc index d36d6d4..209f1bc 100644 --- a/sections/clause_07d_actuation_entities.adoc +++ b/sections/clause_07d_actuation_entities.adoc @@ -1,40 +1,240 @@ +:sectnums: |,all| +:sectanchors: +[[actuation]] +=== Actuation +All actuation entites are grouped into the following requirements class: + +[requirements_class] +==== +[%metadata] +identifier:: {identifier}/req-class/datamodel/actuation +obligation:: requirement +subject:: Target Type: Data Model +requirement:: {identifier}/req-class/datamodel/actuation/tasking-capability +requirement:: {identifier}/req-class/datamodel/actuation/task +requirement:: {identifier}/req-class/datamodel/actuation/actuator +==== + [[actuation-entities]] -=== Actuation Entities +==== Actuation Entities + +The Actuation entities are described by the entities in Figure {counter:figure-num} +[#img-sta-actuation,link=images/GRP0003.png, reftext='{figure-caption} {counter:figure-num}', title='Actuation Entities'] +image::images/GRP0003.png["Actuation Entities", align="center"] + +[[tasking-capability]] +===== Tasking Capability + +[requirements_class] +==== +[%metadata] +identifier:: {identifier}/req-class/datamodel/actuation/tasking-capability +obligation:: requirement +subject:: Target Type: Data Model +requirement:: {identifier}/req/datamodel/actuation/tasking-capability/properties +requirement:: {identifier}/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. + + +[requirement] +==== +[%metadata] +identifier:: {identifier}/req/datamodel/actuation/tasking-capability/properties + +Each TaskingCapability entity SHALL have the mandatory properties and MAY have the optional properties listed in Table {counter:table-num}. +==== +[#tasking-capability-properties,reftext='{table-caption} {counter:table-num}'] +.Properties of a TaskingCapability entity +[width="100%",cols="5,17,3,3,3",options="header"] +|==== +| *Name* | *Definition* | *Data Type* | *Usage* | *Multiplicity* + +| `id` | A unique, read-only property that serves as an identifier for the entity. | ANY | Required | One + +| `name` | A property provides a label for TaskingCapability entity, commonly a descriptive name | String | Required | One + +| `description` | The description of the Deployment entity | String | Optional | Zero-to-one + +| `properties` | A JSON Object containing user-annotated properties as key-value pairs | JSON Object | Optional | Zero-to-one + +| `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) | Required | One + +|==== + + +[requirement] +==== +[%metadata] +identifier:: {identifier}/req/datamodel/actuation/tasking-capability/relations + +Each TaskingCapability entity SHALL have the direct relation between a TaskingCapability entity and other entity types listed in Table {counter:table-num}. +==== + + + +[#tasking-capability-relations,reftext='{table-caption} {counter:table-num}'] +.Direct relation between a TaskingCapability entity and other entity types +[width="100%",cols="5,5,10,10",options="header"] +|==== +| *Entity Name* | *Role* | *Multiplicity* | *Description* + +| `Task` | Tasks | One mandatory to many optional | A TaskingCapability has zero-to-many Tasks. A Task has one-and-only-one TaskingCapability + +| `Thing` | Thing | Many optional to one mandatory | A TaskingCapability has one-and-only-one Thing. A Thing has zero-to-many TaskingCapabilities -==== Requirement Class: Thing +| `Actuator` | Host | Many optional to one mandatory | A TaskingCapability has one-and-only-one Actuator. An Actuator has zero-to-many TaskingCapabilities + +| `Feature` | UltimateFeatureOfInterest | Many optional to one optional | A TaskingCapability may have an UltimateFeatureOfInterest upon which a TaskingCapability can execute a Task. A Feature may have zero-to-many TaskingCapabilities + +| `ObservedProperty` | ActuableProperties | Many optional to many mandatory | A TaskingCapability may have an ObservedProperty that is observed by the Actuator. An ObservedProperty may have zero-to-many TaskingCapabilities +|==== + +[[task]] +===== Task [requirements_class] -.thing +==== +[%metadata] +identifier:: {identifier}/req-class/datamodel/actuation/task +obligation:: requirement +subject:: Target Type: Data Model +requirement:: {identifier}/req/datamodel/actuation/task/properties +requirement:: {identifier}/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. + +[requirement] +==== +[%metadata] +identifier:: {identifier}/req/datamodel/actuation/task/properties +Each Task entity SHALL have the mandatory properties and MAY have the optional properties listed in Table {counter:table-num}. +==== + +[#task-properties,reftext='{table-caption} {counter:table-num}'] +.Properties of a Task entity +[width="100%",cols="5,17,3,3,3",options="header"] +|==== +| *Name* | *Definition* | *Data Type* | *Usage* | *Multiplicity* + +| `id` | A unique, read-only property that serves as an identifier for the entity. | ANY | Required | One +| `creationTime`| The time when the task is created. This time SHALL only be added automatically by the service. | TM_Instant | Optional | One +| `runTime` | The total time taken when the task is executed | TM_Object | Optional | One +| `status` | The status of the task. The status of the task can be one of the following values: “created”, “started”, “completed”, “rejected, “failed”. | CodeList | Optional | One +| `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) | Required | One +|==== + +[requirement] ==== [%metadata] -identifier:: {identifier}/req-class/datamodel/thing +identifier:: {identifier}/req/datamodel/actuation/task/relations + +Each Task entity SHALL have the direct relation between a Task entity and other entity types listed in Table {counter:table-num}. +==== + +[#task-relations,reftext='{table-caption} {counter:table-num}'] +.Direct relation between a Task entity and other entity types +[width="100%",cols="5,5,10,10",options="header"] +|==== +| *Entity Name* | *Role* | *Multiplicity* | *Description* + +| `TaskingCapability` | TaskingCapability | Many optional to one mandatory | A Task has one-and-only-one TaskingCapability. A TaskingCapability has zero-to-many Tasks +| `Feature` | ProximateFeatureOfInterest | Many optional to one optional | A Task may have a Feature that is the target of the Task. A Feature may have zero-to-many Tasks +|==== + + +[#task-status-status-codes,reftext='{table-caption} {counter:table-num}'] +.List of Status Codes used for identifying the status of the Task entity +[width="100%",cols="15,5",options="header"] +|==== +| *StatusCode* | *Description* + +| `Created` | Created status +| `Running` | Running status +| `Completed` | Completed status +| `Rejected` | Rejected status +| `Failed` | Failed status +|==== + +[[actuator]] + +===== Actuator + +[requirements_class] +==== +[%metadata] +identifier:: {identifier}/req-class/datamodel/actuation/actuator obligation:: requirement subject:: Target Type: Data Model -inherit:: {identifier}/req-class/datamodel/entity-control-information -requirement:: {identifier}/req/datamodel/thing/properties -requirement:: {identifier}/req/datamodel/thing/relations +requirement:: {identifier}/req/datamodel/actuation/actuator/properties +requirement:: {identifier}/req/datamodel/actuation/actuator/relations ==== -The Thing is a cool Entity that can be anything. -Say something about OMS-Host, OMS-Deployment, FeatureOfInterest and Locations +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. [requirement] ==== [%metadata] -identifier:: {identifier}/req/datamodel/thing/properties +identifier:: {identifier}/req/datamodel/actuation/actuator/properties -Each Thing entity SHALL have the mandatory properties and MAY have the optional properties listed in Table XX. +Each Actuator entity SHALL have the mandatory properties and MAY have the optional properties listed in Table {counter:table-num}. ==== +[#actuator-properties,reftext='{table-caption} {counter:table-num}'] +.Properties of an Actuator entity +[width="100%",cols="5,17,3,3,3",options="header"] +|==== +| *Name* | *Definition* | *Data Type* | *Usage* | *Multiplicity* +| `id` | A unique, read-only property that serves as an identifier for the entity. | ANY | Required | One +| `name` | A property provides a label for Actuator entity, commonly a descriptive name | String | Required | One +| `description` | The description of the Actuator entity | String | Optional | Zero-to-one +| `encodingType`| The encoding type of the metadata property. Its value is one of the ValueCode enumeration (see <>) | ANY | Required | One +| `metadata` | The metadata property provides detailed information about the Actuator entity. The content of the metadata property is implementation dependent. | ANY | Required | One +| `properties` | A JSON Object containing user-annotated properties as key-value pairs | JSON Object | Optional | Zero-to-one + +|==== [requirement] ==== [%metadata] -identifier:: {identifier}/req/datamodel/thing/relations +identifier:: {identifier}/req/datamodel/actuation/actuator/relations -Each Thing entity SHALL have the direct relation between a Thing entity and other entity types listed in Table XX. +Each Actuator entity SHALL have the direct relation between an Actuator entity and other entity types listed in Table {counter:table-num}. ==== +[#actuator-relations,reftext='{table-caption} {counter:table-num}'] +.Direct relation between an Actuator entity and other entity types +[width="100%",cols="5,5,10,10",options="header"] +|==== +| *Entity Name* | *Role* | *Multiplicity* | *Description* + +| `TaskingCapability` | TaskingCapability | One mandatory to many optional | An Actuator has zero-to-many TaskingCapabilities. A TaskingCapability has one-and-only-one Actuator + +|==== + + +[#actuator-encodingType-value-codes,reftext='{table-caption} {counter:table-num}'] +.List of some code values used for identifying types for the encodingType of the Actuator entity +[width="100%",cols="15,5",options="header"] +|==== +| *Actuator encodingType* | *ValueCode Value* +| `PDF` | application/pdf +| `SensorML` | http://www.opengis.net/doc/IS/SensorML/2.0 +|==== + +The Actuator encodingType allows clients to know how to interpret metadata’s value(s). Currently, the SensorThings API defines two common Actuator metadata encodingTypes. Most sensor manufacturers provide their sensor datasheets in a PDF format. As a result, PDF is a Sensor encodingType supported by SensorThings API. The second Sensor encodingType is SensorML. + + + + + + diff --git a/sections/clause_07a_meta_model.adoc b/sections/clause_08a_meta_model.adoc similarity index 100% rename from sections/clause_07a_meta_model.adoc rename to sections/clause_08a_meta_model.adoc diff --git a/sections/clause_08a_abstract_api_overview.adoc b/sections/clause_08b_abstract_api_overview.adoc similarity index 100% rename from sections/clause_08a_abstract_api_overview.adoc rename to sections/clause_08b_abstract_api_overview.adoc diff --git a/sections/clause_08b_rest_api_read.adoc b/sections/clause_08c_rest_api_read.adoc similarity index 100% rename from sections/clause_08b_rest_api_read.adoc rename to sections/clause_08c_rest_api_read.adoc diff --git a/sections/clause_08c_rest_api_create_update_delete.adoc b/sections/clause_08d_rest_api_create_update_delete.adoc similarity index 100% rename from sections/clause_08c_rest_api_create_update_delete.adoc rename to sections/clause_08d_rest_api_create_update_delete.adoc diff --git a/sections/clause_08d_rest_api_batch_requests.adoc b/sections/clause_08e_rest_api_batch_requests.adoc similarity index 100% rename from sections/clause_08d_rest_api_batch_requests.adoc rename to sections/clause_08e_rest_api_batch_requests.adoc diff --git a/sections/clause_08e_rest_api_data_array.adoc b/sections/clause_08f_rest_api_data_array.adoc similarity index 100% rename from sections/clause_08e_rest_api_data_array.adoc rename to sections/clause_08f_rest_api_data_array.adoc diff --git a/sections/clause_08f_pubsub_api.adoc b/sections/clause_08g_pubsub_api.adoc similarity index 100% rename from sections/clause_08f_pubsub_api.adoc rename to sections/clause_08g_pubsub_api.adoc