Document Restructure

23-019.adoc

@@ -45,13 +45,9 @@ include::sections/clause_05_conventions.adoc[]
 
 include::sections/clause_06_overview.adoc[]
 
-include::sections/clause_07a_sensing_core_entities.adoc[]
+include::sections/clause_07_core_data_model.adoc[]
 
-include::sections/clause_07b_sensing_OM_extension.adoc[]
-
-include::sections/clause_07d_sampling_entities.adoc[]
-
-include::sections/clause_07e_actuation_entities.adoc[]
+include::sections/clause_08_abstract_api.adoc[]
 
 include::sections/clause_08a_meta_model.adoc[]
 
@@ -61,12 +57,6 @@ include::sections/clause_08c_rest_api_read.adoc[]
 
 include::sections/clause_08d_rest_api_create_update_delete.adoc[]
 
-include::sections/clause_08e_rest_api_batch_requests.adoc[]
-
-include::sections/clause_08g_pubsub_api.adoc[]
-
-include::sections/clause_08f_rest_api_data_array.adoc[]
-
 include::sections/clause_09a_bindings_http.adoc[]
 
 include::sections/clause_09b_bindings_mqtt.adoc[]
@@ -77,6 +67,24 @@ include::sections/clause_09d_bindings_ogc_api_common.adoc[]
 
 include::sections/clause_10_media_types.adoc[]
 
+include::sections/clause_11_data_model_extensions.adoc[][]
+
+include::sections/clause_11a_sensing_OM_extension.adoc[]
+
+include::sections/clause_11b_sampling_entities.adoc[]
+
+include::sections/clause_11c_relations_extension.adoc[]
+
+include::sections/clause_11d_actuation_entities.adoc[]
+
+include::sections/clause_12_api_extensions.adoc[]
+
+include::sections/clause_12a_rest_api_batch_requests.adoc[]
+
+include::sections/clause_12b_rest_api_data_array.adoc[]
+
+include::sections/clause_12c_pubsub_api_extension.adoc[]
+
 ////
 add or remove annexes after "A" as necessary
 ////

sections/clause_06_overview.adoc

@@ -55,11 +55,11 @@ 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.
-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. 
+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 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).
+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 <<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.
@@ -150,7 +150,7 @@ SensorThings API uses the term of Sensor to describe the Observer that is used i
 - 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
+- A Datastream can now be linked to the Feature it observes as an optional link, named UltimateFeatureOfInterest, between Datastream and Feature is introduced
 
 | ObservedProperty | description attribute is now optional and not mandatory
 | Observation | 

sections/clause_07a_sensing_core_entities.adoc → sections/clause_07_core_data_model.adoc

@@ -1,5 +1,6 @@
 [[sensing-core]]
-== The SensorThings API Sensing Core Entities
+== The SensorThings API Data Model
+
 All data model requirements classes are grouped in the following requirements class:
 
 
@@ -21,19 +22,18 @@ requirement:: {identifier}/req-class/datamodel/sensing/observation
 requirement:: {identifier}/req-class/datamodel/sensing/feature  
 ====
 
-[[sensing-entities]]
-=== Sensing Entities
-
 The OGC SensorThings API v2.0 depicts the Core Sensing entities in <<img-sta-core>>
-[#img-sta-core,link=images/GRP0001.png, reftext='{figure-caption} {counter:figure-num}', title='Sensing Core']
-image::images/GRP0001.png[Sensing Core, align="center"]  
+[#img-sta-core,link=figures/Datamodel-SensorThingsApi-V2-Core.drawio.png, reftext='{figure-caption} {counter:figure-num}', title='Sensing Core']
+image::figures/Datamodel-SensorThingsApi-V2-Core.drawio.png[Sensing Core, align="center"]  
+
+NOTE: move image into document once finished
 
 
 In this section, we define each entity depicted in <<img-sta-core>> and its relationships with other entities.
 Additionally, we also provide examples to model the entities in different contexts.
 
 [[thing]]
-==== Thing
+=== Thing
 
 [requirements_class]
 ====
@@ -55,8 +55,9 @@ A Thing is related to the Platform entity as described in Section 4.9.2.1 of [OG
 ====
 *Thing Examples*
 
-- A weather forecasting facility that houses multiple weather sensors deployed across several sites
+- A weather station that houses a varying set of environmental sensors
 - A drone that mounts a LiDAR sensor for mapping purposes
+- A science vessel that has many sensors installed
 - An upstream oil well that is equipped with compound gas detection devices
 ====
 
@@ -78,7 +79,7 @@ Each Thing entity SHALL have the mandatory properties and MAY have the optional
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client.
+Its value is computed by the server when creating  the entity unless specified by the client.
 | ANY              | Required | One
 
 | `name`
@@ -131,7 +132,7 @@ A HistoricalLocation has one-and-only-one Thing.
 
 
 [[location]]
-==== Location
+=== Location
 
 [requirements_class]
 ====
@@ -184,7 +185,7 @@ Each Location entity SHALL have the mandatory properties and MAY have the option
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client.
+Its value is computed by the server when creating  the entity unless specified by the client.
 | ANY              | Required | One
 
 | `name`
@@ -236,7 +237,7 @@ One HistoricalLocation SHALL have one or more Locations.
 
 
 [[historicallocation]]
-==== HistoricalLocation
+=== HistoricalLocation
 
 [requirements_class]
 ====
@@ -314,7 +315,7 @@ When a user directly adds new HistoricalLocation, and the time of this new Histo
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client.
+Its value is computed by the server when creating  the entity unless specified by the client.
 | ANY         | Required | One
 
 | `time`
@@ -343,7 +344,7 @@ One Thing MAY have zero-to-many HistoricalLocations.
 
 
 [[datastream]]
-==== Datastream
+=== Datastream
 
 [requirements_class]
 ====
@@ -397,7 +398,7 @@ Each Datastream entity SHALL have the direct relation between a Datastream entit
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client
+Its value is computed by the server when creating  the entity unless specified by the client
 | ANY
 | Required | One
 
@@ -417,17 +418,20 @@ Its value is computed by the server when creating or updating the entity unless
 | Required | One
 
 | `observedArea`
-| The spatial bounding box of the spatial extent of the Feature that belong to the Observations associated with this Datastream
+| The spatial bounding box of the spatial extent of the Feature that belong to the Observations associated with this Datastream.
+This is usually generated by the server.
 | Geometry
 | Optional | Zero-to-one
 
 | `phenomenonTime`
 | The temporal interval of the phenomenon times of all observations belonging to this Datastream.
+This is usually generated by the server.
 | TM_Period
 | Optional | Zero-to-one
 
 | `resultTime`
 | The temporal interval of the result times of all observations belonging to this Datastream.
+This is usually generated by the server.
 | TM_Period
 | Optional | Zero-to-one
 
@@ -565,7 +569,7 @@ This also obsoletes MultiDatastreams as the same information can be described us
 
 
 [[sensor]]
-==== Sensor
+=== Sensor
 
 [requirements_class]
 ====
@@ -608,7 +612,7 @@ Each Sensor entity SHALL have the direct relation between a Sensor entity and ot
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client.
+Its value is computed by the server when creating  the entity unless specified by the client.
 | ANY         | Required | One
 
 | `name`
@@ -667,7 +671,7 @@ Note that the metadata property may contain either a URL to metadata content (e.
 It is up to clients to perform string parsing necessary to properly handle metadata content.
 
 [[observedproperty]]
-==== ObservedProperty
+=== ObservedProperty
 
 [requirements_class]
 ====
@@ -708,7 +712,7 @@ Each ObservedProperty entity SHALL have the direct relation between an ObservedP
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client.
+Its value is computed by the server when creating  the entity unless specified by the client.
 | ANY          | Required | One
 
 | `name`
@@ -745,7 +749,7 @@ The Observations of different Datastreams MAY observe the same ObservedProperty.
 
 
 [[observation]]
-==== Observation
+=== Observation
 
 [requirements_class]
 ====
@@ -786,7 +790,7 @@ Each Observation entity SHALL have the direct relation between an Observation en
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client.
+Its value is computed by the server when creating  the entity unless specified by the client.
 | ANY         | Required | One
 
 | `phenomenonTime`
@@ -841,7 +845,7 @@ The relationship is optional and SHALL exist in cases where the observed Feature
 
 
 [[feature]]
-==== Feature
+=== Feature
 
 [requirements_class]
 ====
@@ -899,7 +903,7 @@ Each Feature entity SHALL have the direct relation between a Feature entity and
 
 | `id`
 | A unique, read-only property that serves as an identifier for the entity.
-Its value is computed by the server when creating or updating the entity unless specified by the client.
+Its value is computed by the server when creating  the entity unless specified by the client.
 | ANY         | Required | One
 
 | `name`

sections/clause_08_abstract_api.adoc

@@ -0,0 +1,3 @@
+== Abstract API
+
+This section describes the abstract API.