Merge pull request #961 from w3c/geo-location

geo location metadata

index.template.html

@@ -2777,7 +2777,14 @@ <h3>Semantic Annotations</h3>
     </p>
 
     <p>
-      As an example, the TD snippet given below extends the version information container
+    Next subsections shows some sample usage of different kind of ontologies in Thing Descriptions.
+    </p>
+
+    <section id="semantic-annotations-example-version-units">
+    <h3>Example I: Version and Unit Annotations</h3>
+
+    <p>
+      The TD snippet given below extends the version information container
       by adding version numbers for the hardware and firmware of the <a>Thing</a>, and uses
       values from external <a>Vocabularies</a> for the <a>Thing</a> and for the
       data schema unit: <a href="https://w3id.org/saref">SAREF</a>,
@@ -2819,6 +2826,10 @@ <h3>Semantic Annotations</h3>
 }
 </pre>
 
+</section>
+<section id="semantic-annotations-example-state">
+    <h3>Example II: State Annotations</h3>
+
     <p>
         In many cases, <a>TD Context Extensions</a> may be used to annotate pieces of a data schema,
         to be able to semantically process the state information of the physical world object,
@@ -2886,6 +2897,104 @@ <h3>Semantic Annotations</h3>
         of the lamp.
     </p>
 
+</section>
+<section id="semantic-annotations-example-geoloc">
+    <h3>Example III: Geolocation Annotations</h3>
+
+    <p>
+    For many use cases like in building, agraculture, or smart city location based data is required. This
+    information can be provided in the Thing Description in different ways and can be relyed on
+    different kind of location ontologies (e.g.,[[WGS84]], [[schema.org]) depending on purpose (e.g., indoor, outdoor).  
+    Also see [[sdw-bp]].
+    </p>
+
+    <p>
+        The TD snippet below uses <code>lat</code> and <code>long</code> from the [[WGS84]] ontology to 
+        provide static latitude and longitude metadata at Thing's top level. 
+    </p>
+
+    <pre class="example" id="saref-state-annotation-example">
+{
+    "@context": [
+        "https://www.w3.org/2019/wot/td/v1",
+        {
+            "geo": "http://www.w3.org/2003/01/geo/wgs84_pos#"        
+        }
+    ],
+    "@type": "Thing",
+    "geo:lat" : "26.58",
+    "geo:long" : "297.83",
+    ...
+    "properties": {
+        ...
+
+}
+</pre>
+
+
+<p>
+        In some use cases location based metadata have to be provided at the interaction level, e.g., 
+        as provided as a <a>Property</a> that returns the latest <code>longitude</code>, <code>latitude</code>, abd <code>elevation</code> values
+        based on [[schema.org]]:
+</p>
+
+<pre class="example" id="saref-state-annotation-example">
+{
+    "@context": [
+        "https://www.w3.org/2019/wot/td/v1",
+        {
+            "schema": "http://schema.org#"
+        }
+    ],
+    ...
+    "properties": {
+        "position": {
+            "type": "object",
+            "@type" : "schema:GeoCoordinates",
+            "properties": {
+                    "longitude": { "type": "number" },
+                    "latitude":  { "type": "number" },
+                    "elevation": { "type": "number" }
+            },
+            "forms": [{"href": "https://robot.example.com/position"}]
+        },
+        ...
+    },
+    ...
+}
+</pre>
+
+<p>
+        In the case it is desired to have a different name for, e.g., <code>longitude</code>, <code>latitude</code>, 
+        and <code>elevation</code>in the data model, <code>jsonld:context</code> can be used to link 
+        terms to specific vocabulary from a ontology (also see [[json-schema]], Section 3.3 Defining a JSON-LD context for data instances):
+</p>
+
+<pre class="example" id="saref-state-annotation-example">
+{
+    "@context": "https://www.w3.org/2019/wot/td/v1",
+    ...
+    "properties": {
+        "position": {
+        "jsonld:context": {
+            "schema": "http://schema.org/"
+            "long": "schema:longitude",
+            "lat": "schema:latitude",
+            "height": "schema:elevation"
+        },
+        "type": "object",
+        "properties": {
+            "long": { "type": "number" },
+            "lat": { "type": "number" },
+            "height": { "type": "number" }
+        }
+        }
+  },
+    ...
+}
+</pre>
+
+
 </section>
 
 <section>