Merge pull request #179 from opengeospatial/23-019_HK

First draft, Core Sensing and OM Extension

.gitignore

@@ -14,6 +14,7 @@ document.html
 document.xml
 document.presentation.xml
 *~
+.$*
 
 # Deploy key
 deploy_key

23-019.adoc

@@ -12,6 +12,8 @@
 :published-date: 2029-03-30
 :fullname: Hylke van der Schaaf
 :fullname_2: Steve Liang
+:fullname_3: Humaid Kidwai
+:fullname_4: Kathi Schleidt
 :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
@@ -48,9 +50,11 @@ include::sections/clause_07a_meta_model.adoc[]
 
 include::sections/clause_07b_sensing_entities.adoc[]
 
-include::sections/clause_07c_sampling_entities.adoc[]
+include::sections/clause_07c_sensing_OM_extension.adoc[]
 
-include::sections/clause_07d_actuation_entities.adoc[]
+include::sections/clause_07d_sampling_entities.adoc[]
+
+include::sections/clause_07e_actuation_entities.adoc[]
 
 include::sections/clause_08a_abstract_api_overview.adoc[]
 

metanorma.yml

@@ -2,5 +2,5 @@
 metanorma:
   source:
     files:
-      - document.adoc
+      - 23-019.adoc
 

sections/clause_06_overview.adoc

@@ -1,18 +1,153 @@
-[obligation=informative]
+[[overview1]]
 == SensorThings API overview
 
-Clauses not Containing Normative Material
 
-Paragraph
+[[who-should-use]]
+=== Who should use the OGC SensorThings API
 
-=== Relation to Observations, Measurements and Samples
+
+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.
+
+
+[[benefits]]
+=== 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<<footnote2>>, 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.
+
+
+[[overview2]]
+=== 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-entities1>>.
+
+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.
+The entities are explained in detail in <<sampling-entities>>.
+
+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 <<tasking-entities>>.
+
+The <<sensing-entities-om-extn>> and <<relations-extension>> 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
+
+Managing and retrieving observations and metadata from IoT sensor systems is one of the most common use cases.
+As a result, SensorThings API’s sensing part is designed based on the OMS model.
+OMS defines models for the exchange of information describing observation acts, their results as well as the feature involved in sampling when making observations.
+
+
+SensorThings API defines nine entities for the IoT sensing applications and two additional entities in the OM extension.
+<<sensingentities,base>> lists each component and its relationship with OMS.
+SensorThings API uses the term of Sensor to describe the Observer that is used in generating an Observation, instead of using OMS’ term of Observer.
+
+
+[[tab-sensing-entities]]
+.SensorThings API Sensing entities and equivalent concepts in OMS 3.0
+|===
+|SensorThings API Entities |OMS 3.0 Concepts
+
+|Thing 
+|Host
+
+|Datastream
+|-
+
+|Sensor
+|Observer
+
+|Deployment
+|Deployment
+
+|Observation
+|Observation
+
+|ObservingProcedure
+|Observing Procedure
+
+|ObservedProperty
+|Observed Property
+
+|Feature
+|Feature
+|===
+
+
+[[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 
+[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
+| Datastream | 
+
+- description attribute is now optional and not mandatory 
+- resultType replaces the observationType attribute, this eliminates MultiDatastream entity
+- unitOfMeasurement SHALL be embedded within the observedType attribute and does not exist as an independent attribute within the Datastream entity
+- A Datastream can link to multiple ObservedProperties which was only possible with MultiDatastream entity earlier.
+  The SWE-Common based observationType attribute eliminates the need for having a separate MultiDatastream entity
+- A Datastream can now be partitioned by the Feature it observes as an optional link between Datastream and Feature is introduced
+
+| ObservedProperty | description attribute is now optional and not mandatory
+| Observation | 
+
+- properties replaces the parameters attribute
+- An Observation may or may not link to any Feature in contrast to the mandatory link between Observation and FeatureOfInterest from v1.x 
+
+| Feature    | The Feature entity replaces the FeatureOfInterest entity from 1.x as it now takes the role of UltimateFeatureOfInterest or ProximateFeatureOfInterest depending upon the context and links with Observation and Datastream entities
+|====
 
 
 === Relation to OASIS-OData
 
-The OGC SensorThings API v2 interface is not an OData interface. It specifies a subset of the OData interface, and extends it at the same time.
+The OGC SensorThings API v2 interface is not an OData interface.
+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.
 
-EDIOR: Verify this is true.
+EDITOR: Check if this is true

sections/clause_07a_meta_model.adoc

@@ -1,24 +1,29 @@
-[[meta-data-model]]
-== Meta Data Model
+[[OData-Entity-Model]]
+== OData Entity Model
 
-This chapter describes the SensorThings API meta model that is used to describe the SensorThings API data model and its data model extensions.
-The meta model is also used to specify the rest and pub-sub apis.
-It is based on the ODATA Meta Model 
+Every OData service utilizes an entity model which MAY be distributed over several schemas.
+The service describes this model through a metadata document accessible by a simple HTTP _GET_ request to the <serviceRoot>/$metadata path.
+This chapter describes an overview of the types of entities in the metadata document that will be used to describe the SensorThings API data model and its data model extensions.
+The entities listed below are also used to describe the REST and MQTT bindings of the SensorThings API service.
 
 * https://docs.oasis-open.org/odata/odata/v4.01/odata-v4.01-part1-protocol.html#sec_DataModel 
 * https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html#sec_EntityModel
 
 
-The meta model consists of the following elements:
+The data model consists of the following elements:
 
 * `Entity Type`: named, structured, keyed element that defines the properties and relations of Entities.
-  The key of an Entity Type consists of one or more primitive properties of the Entity Type. 
-* `Entity`: instance of an `Entity Type`. An Entity can have only one Entity Type.
+  The key of an Entity Type consists of one or more primitive properties of the Entity Type.
+* `Entity`: instance of an `Entity Type`.
+  An Entity can have only one Entity Type.
 * `Primitive Type`: unnamed, unstructured type, such as String, Integer or DateTime.
   https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html#sec_PrimitiveTypes
-* `Complex Type`: named, structured, keyless, element consisting of a set of named properties. Instances of Complex Types can not be accessed outside of the Entity they are contained in.
+* `Complex Type`: named, structured, keyless, element consisting of a set of named properties.
+  Instances of Complex Types can not be accessed outside of the Entity they are contained in.
   A property with a Primitive Type is called a primitive property.
-* `Relation`: named connections between Entities. Relations defined as `navigation properties` in Entity Types. Relations have a cardinality.
+* `Relation`: named connections between Entities.
+  Relations defined as `navigation properties` in Entity Types.
+  Relations have a cardinality.
 * `Properties`: named elements that are part of structured types (Entity Types and Complex Types).
   Properties can be Primitive-, Complex- or navigation properties.
   Properties defined as part of a structured type (Entity/Complex Type) are `declared properties`.
@@ -41,7 +46,8 @@ The meta model consists of the following elements:
 
 EDITOR: Say something about `id`, primary keys, extensions and server-generated/user-supplied.
 
-EDITOR: Say something about absolute / relative URLs. Relative to what, and how is this done in MQTT? See https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_RelativeURLs
+EDITOR: Say something about absolute / relative URLs.
+Relative to what, and how is this done in MQTT? See https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_RelativeURLs
 
 
 [[tab-common-control-annotations]]
@@ -51,7 +57,7 @@ EDITOR: Say something about absolute / relative URLs. Relative to what, and how
 |Name |Definition |Data Type
 
 |@context
-|The context url contains the metadata document that describes the context of a payload. 
+|The context url contains the metadata document that describes the context of a payload.
 |URL
 
 |@id