i.           Abstract

The OGC SensorThings API provides an open, geospatial-enabled and unified way to interconnect the Internet of Things (IoT) devices, data, and applications over the Web. At a high level the OGC SensorThings API provides two main functionalities and each function is handled by a part. The two parts are the Sensing part and the Tasking part. The Sensing part provides a standard way to manage and retrieve observations and metadata from heterogeneous IoT sensor systems. The Tasking part is planned as a future work activity and will be defined in a separate document as the Part II of the SensorThings API.

ii.          Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, iot, internet of things, sensor things, sensors, swe, sensor webs, sensor web enablement, sensor networks

iii.          Preface

The OGC SensorThings API provides an open, geospatial-enabled and unified way to interconnect the Internet of Things devices, data, and applications over the Web. The OGC SensorThings API is an open standard, and that means it is non-proprietary, platform-independent, and perpetual royalty-free. Although it is a new standard, it builds on a rich set of proven-working and widely-adopted open standards, such as the Web protocols and the OGC Sensor Web Enablement (SWE) standards, including the ISO/OGC Observation and Measurement data model [OGC 10-004r3 and ISO 19156:2011]. That also means the OGC SensorThings API is extensible and can be applied to not only simple but also complex use cases.

At a high level the OGC SensorThings API provides two main functionalities and each function is handled by a part. The two parts are the Part I - Sensing and the Part II - Tasking. The Sensing part provides a standard way to manage and retrieve observations and metadata from heterogeneous IoT sensor systems. The Tasking part provides a standard way for parameterizing - also called tasking - of task-able IoT devices, such as sensors or actuators. The Tasking part is planned as a future work activity and will be defined in a separate document as the Part II of the SensorThings API.

The Sensing part provides functions similar to the OGC Sensor Observation Service (SOS) and the Tasking part will provide functions similar to the OGC Sensor Planning Service (SPS). The main difference between the SensorThings API and the OGC SOS and SPS is that the SensorThings API is designed specifically for the resource-constrained IoT devices and the Web developer community. As a result, the SensorThings API follows the REST principles, the use of an efficient JSON encoding, the use of MQTT protocol, the use of the flexible OASIS OData protocol and URL conventions.

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.

iv.          Submitting organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

University of Calgary, Canada

National Central University, Taiwan

Lockheed Martin, USA

AIST, Japan

FCU.GIS, Taiwan

ITRI, Taiwan

GeoConnections, Canada

Noblis, USA

Fraunhofer, Germany

v.          Submitters

All questions regarding this submission should be directed to the editor or the submitters:

1.    Scope

The OGC SensorThings API provides an open standard-based and geospatial-enabled framework to interconnect the Internet of Things devices, data, and applications over the Web.

2.    Conformance

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[1].

All requirements-classes and conformance-classes described in this document are owned by the standard(s) identified.

The following table list the requirements classes defined by this standard.

NOTE: The smaller blue text in the following table is the path fragment that appended to the following URI: http://www.opengis.net/spec/iot_sensing/1.0/, and it provides the URI that can be used to unambiguously identify the requirement and the conformance class.

3.    References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

ISO 8601:2004 Data elements and interchange formats – Information interchange - Representation of dates and times.

OGC 10-004r3 and ISO 19156:2011(E), OGC Abstract Specification Topic 20: Geographic information — Observations and Measurements

OASIS OData Version 4.0 Part 1: Protocol Plus Errata 02

OASIS OData Version 4.0 Part 2: URL Conventions Plus Errata 02

OASIS OData JSON Format Version 4.0 Plus Errata 02

OASIS OData ABNF Construction Rules Errata 02

RFC 2046, Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types

RFC 2616, Hypertext Transfer Protocol -- HTTP/1.1

RFC 4627, the application/json Media Type for Javascript Object Notation (JSON), July 2006

Unified Code for Units of Measure (UCUM) – Version 1.9, April 2015

4.    Terms and Definitions

This document uses the terms defined in Sub-clause 5.3 of [OGC 06-121r8], 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.

4.1 Collection

Sets of Resources, which can be retrieved in whole or in part. [RFC5023]

4.2   Entity

Entities are instances of entity types. [OASIS OData Version 4.0 Part 1: Protocol Plus Errata 02]

Note: Thing, Sensor, Datastream, Observation are some example entity types of the OGC SensorThings API.

4.3  Entity sets

Entity sets are named collections of entities (e.g. Sensors is an entity set containing Sensor entities). An entity’s key uniquely identifies the entity within an entity set. Entity sets provide entry points into an OGC SensorThings API service. [OASIS OData Version 4.0 Part 1: Protocol Plus Errata 02]

4.4   (Internet of) Thing

A thing is 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]

4.5   Measurement

A set of operations having the object of determining the value of a quantity [OGC 10-004r3 / ISO 19156:2011]

4.6   Observation

Act of measuring or otherwise determining the value of a property [OGC 10-004r3 /  ISO 19156:2011]

4.7   Observation Result

Estimate of the value of a property determined through a known observation procedure [OGC 10-004r3 / ISO 19156:2011]

4.8   Resource

A network-accessible data object or service identified by an URI, as defined in [RFC 2616]

4.9   REST

The Representational State Transfer (REST) style is an abstraction of the architectural elements within a distributed hypermedia system. REST focuses on the roles of components, the constraints upon their interaction with other components, and their interpretation of significant data elements. It encompasses the fundamental constraints upon components, connectors, and data that define the basis of the Web architecture, and thus the essence of its behavior as a network-based application. An API that conforms to the REST architectural principles/constraints is called a RESTful API.

4.10   Sensor

An entity capable of observing a phenomenon and returning an observed value. Type of observation procedure that provides the estimated value of an observed property at its output. [OGC 12-000]

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    Presentation of Requirements and Recommendations

Requirements are presented using the following style:

<number> is a unique number within the document.

<requirement text> is the requirement itself. Normative verbs like SHALL are written in capitals.

The smaller blue text at the bottom of the box <requirement id> is the path and it provides the URI of the requirement which can be used to unambiguously identify the requirement.

Normative verbs like SHALL are written in capitals.

5.2    Identifiers

The normative provisions in this specification are denoted by the URI

http://www.opengis.net/spec/iot_sensing/1.0/

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

6.    Symbols (and abbreviated terms)

API                          Application Programming Interface

CS-W                       Catalog Service Web

CRUD                      Create, Read, Update, and Delete

GML                        Geography Markup Language

HTML                      HyperText Markup Language

HTTP                      Hypertext Transfer Protocol

IoT                          Internet of Things

ISO                          International Organization for Standardization

JSON                       JavaScript Object Notation

OData                       the Open Data Protocol

OGC                                    Open Geospatial Consortium

OWS                        OGC Web Services

O&M                       Observations and Measurements

REST                       REpresentational State Transfer

SensorML                 Sensor Model Language

SOS                         Sensor Observation Service

SPS                         Sensor Planning Service

SWE                                    Sensor Web Enablement

UCUM                     Unified Code for Units of Measure

UML                        Unified Modeling Language

WoT                                    Web of Things

XML                        eXtensible Markup Language

7.    SensorThings API overview

7.1    Who should use the OGC SensorThings API

Organizations that need web-based platforms to manage, store, share, 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.

7.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[2], 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.

7.3    SensorThings API Overview

The OGC SensorThings API data model consists of two parts: (1) the Sensing part and (2) the Tasking part. 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 ISO/OGC Observation and Measurement (O&M) model [OGC 10-004r3 and ISO 19156:2011]. The key to the model is that an Observation is modeled as an act that produces a result whose value is an estimate of a property of the observation target or FeatureOfInterest. An Observation instance is classified by its event time (e.g., resultTime and phenonmenonTime), FeatureOfInterest, ObservedProperty, and the procedure used (often a Sensor). Moreover, Things are also modeled in the SensorThings API, and 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 and Sensor. An Observationis an event performed by a Sensorthat produces a result whose value is an estimate of an ObservedPropertyof the FeatureOfInterest. Details of each above described entity are provided in Section 8.

7.4    SensorThings API and ISO/OGC Observations and Measurements

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 ISO/OGC Observation and Measurement (O&M) model [OGC 10-004r3 and ISO 19156:2011]. O&M 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 eight entities for the IoT sensing applications. Table 1 lists each component and its relationship with O&M. Low-cost and simple sensors are key enablers for the vision of IoT. As a result, SensorThings API uses the term of Sensor to describe the procedure that is used in making an Observation, instead of using O&M’s term of procedure.

7.5    SensorThings API and OASIS OData

SensorThings API follows OData’s specification for requesting entities. That means the entity control information, resource path usages, query options, the relevant JSON encodings, and batch-processing request follow OData 4.0. By using OData’s standard ways for requesting entities, developers who are familiar with OData can create SensorThings applications easily. However, SensorThings API does not follow the OData Common Schema Definition Language and as a result does not follow its metadata service entity model. Thus, SensorThings API should not be seen as an OData compliant API. SensorThings API’s future work will explore possible harmonization between SensorThings API and OData.

7.6    SensorThings API and OGC Key-Value Pair (KVP) Encodings

Please note that SensorThings API’s Key-Value Pair (KVP) encoding is different from many existing OGC service implementation standards, such as SOS or Web Map Service (WMS). The main reason is that OData offers a complete set of KVP encodings (see Clause 9.3.3.6) that is designed specifically for RESTful web services, while OGC baseline currently does not have common KVP encodings for the RESTful binding. As a result, OGC SensorThings API version 1.0 chooses to use OData KVP encodings only. It is our future work to support OGC KVP encodings as an extension once a common OGC RESTful binding is available.

7.7    SensorThings API and Security

As things in the Internet of Things are connected to the network. Such ubiquitous network connectivity results in significant security threats. In the IoT reference model defined by ITU-T [ITU-T Y.2060] IoT security capabilities are not an independent layer but must be associated with all layers. The following figure show the ITU-T IoT reference model. The reference model has four layers, namely (1) Applications Layer, (2) Service Support and Application Support Layer, (3) Network Layer, and (4) Device Layer. And security capabilities are a cross-layer component that is associated with the four layers.

Based on the IoT reference model, SensorThings API falls into the scope of the Service Support and Application Support Layer and the security issues should be addressed by the cross-cutting security capabilities. As a result, SensorThings API does not define specific security capabilities. Instead SensorThings API is designed to leverage the existing and future IoT security capabilities.

8.    The SensorThings API Sensing Entities

8.1    Common Control Information

In SensorThings control information is represented as annotations whose names start with iot followed by a dot ( . ). Annotations are name/value pairs that have a dot ( . ) as part of the name.

When annotating a name/value pair for which the value is represented as a JSON object, each annotation is placed within the object and represented as a single name/value pair. In SensorThings the name always starts with the “at” sign (@), followed by the namespace iot, followed by a dot (.), followed by the name of the term (e.g., “@iot.id”:1).

When annotating a name/value pair for which the value is represented as a JSON array or primitive value, each annotation that applies to this name/value pair is placed next to the annotated name/value pair and represented as a single name/value pair. The name is the same as the name of the name/value pair being annotated, followed by the “at” sign (@), followed by the namespace iot, followed by a dot (.), followed by the name of the term.  (e.g., “Locations@iot.navigationLink”:“http://example.org/v.1.0/Things(1)/Locations”)

8.2    The Sensing Entities

The SensorThings API Sensing part’s Entities are depicted in Figure 2.

In this section, we explain the properties in each entity type and the direct relation to the other entity types. In addition, for each entity type, we show an example of the associated JSON encoding.

8.2.1    Thing

The OGC SensorThings API follows the ITU-T definition, i.e., with regard to the Internet of Things, a thing is 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].

Example 1 an example of a Thing entity:

  {
    "@iot.id": 1,
    "@iot.selfLink":
  "http://example.org/v1.0/Things(1)",
   
  "Locations@iot.navigationLink":
  "Things(1)/Locations",
   
  "Datastreams@iot.navigationLink":
  "Things(1)/Datastreams",
   
  "HistoricalLocations@iot.navigationLink":
  "Things(1)/HistoricalLocations",
    "name": "Oven",

    "description": "This
  thing is an oven.",
    "properties": {
      "owner": "Noah
  Liang",
      "color": "Black"
    }
  }

8.2.2    Location

The Location entity locates the Thing or the Things it associated with. A Thing’s Location entity is defined as the last known location of the Thing.

A Thing’s Location may be identical to the Thing’s Observations’ FeatureOfInterest. In the context of the IoT, the principle location of interest is usually associated with the location of the Thing, especially for in-situ sensing applications. For example, the location of interest of a wifi-connected thermostat should be the building or the room in which the smart thermostat is located. And the FeatureOfInterest of the Observations made by the thermostat (e.g., room temperature readings) should also be the building or the room. In this case, the content of the smart thermostat’s location should be the same as the content of the temperature readings’ feature of interest.

However, the ultimate location of interest of a Thing is not always the location of the Thing (e.g., in the case of remote sensing). In those use cases, the content of a Thing’s Location is different from the content of theFeatureOfInterestof the Thing’s Observations. Section 7.1.4 of [OGC 10-004r3 and ISO 19156:2011] provides a detailed explanation of observation location.

Example 2 an example of a Location entity:

  {
    "@iot.id": 1,
    "@iot.selfLink":
  "http://example.org/v1.0/Locations(1)",
   
  "Things@iot.navigationLink":
  "Locations(1)/Things",
   
  "HistoricalLocations@iot.navigationLink":
  "Locations(1)/HistoricalLocations",
    "encodingType":
  "application/vnd.geo+json",

    "name": "CCIT",

    "description": "Calgary
  Center for Innvative Technologies",
    "location": {
      "type":
  "Feature",
      "geometry":{
        "type": "Point",
        "coordinates": [-114.06,51.05]
      }
    }
  }

A thing can be geo-referenced in different spaces. For example, for some applications it is more suitable to use a topological space model (e.g., IndoorGML) to describe an indoor things’ location rather than using a geometric space model (e.g., GeoJSON). Currently GeoJSON is the only Location encodingType of the SensorThings API. In the future we expect to extend SensorThings API’s capabilities by adding additional encodingType to the code values listed in the above table. For example, one potential new Location encodingType can be a JSON encoding for IndoorGML.

8.2.3    HistoricalLocation

A Thing’s HistoricalLocation entity set provides the times of the current (i.e., last known) and previous locations of the Thing.

The HistoricalLocation can also be created, updated and deleted. One use case is to migrate historical observation data from an existing observation data management system to a SensorThings API system.

Example 3 An example of a HistoricalLocations entity set (e.g., Things(1)/HistoricalLocations):

  {
   
  "value": [
      {
       
  "@iot.id": 1,
       
  "@iot.selfLink":
  "http://example.org/v1.0/HistoricalLocations(1)",
       
  "Locations@iot.navigationLink":
  "HistoricalLocations(1)/Locations",
       
  "Thing@iot.navigationLink": "HistoricalLocations(1)/Thing",
       
  "time": "2015-01-25T12:00:00-07:00"
      },
      {
       
  "@iot.id": 2,
       
  "@iot.selfLink":
  "http://example.org/v1.0/HistoricalLocations(2)",
       
  "Locations@iot.navigationLink":
  "HistoricalLocations(2)/Locations",
        "Thing@iot.navigationLink":
  "HistoricalLocations(2)/Thing",
       
  "time": "2015-01-25T13:00:00-07:00"
      }
    ],
    "@iot.nextLink":"http://example.org/v1.0/Things(1)/HistoricalLocations?$skip=2&$top=2"
  }

8.2.4     Datastream

A Datastream groups a collection of Observations measuring the same ObservedProperty and produced by the same Sensor.

Example 4 A Datastream entity example:

  {
    "@iot.id": 1,
    "@iot.selfLink":
  "http://example.org/v1.0/Datastreams(1)",
    "Thing@iot.navigationLink":
  "HistoricalLocations(1)/Thing",
    "Sensor@iot.navigationLink":
  "Datastreams(1)/Sensor",
    "ObservedProperty@iot.navigationLink":
  "Datastreams(1)/ObservedProperty",
    "Observations@iot.navigationLink":
  "Datastreams(1)/Observations",
    "name": "oven
  temperature",

    "description": "This
  is a datastream measuring the air temperature in an oven.",
    "unitOfMeasurement":
  {
      "name":
  "degree Celsius",
      "symbol":
  "°C",
      "definition":
  "http://unitsofmeasure.org/ucum.html#para-30"
    },
    "observationType":
  "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
    "observedArea": {
      "type":
  "Polygon",
      "coordinates":
  [[[100,0],[101,0],[101,1],[100,1],[100,0]]]
    },
    "phenomenonTime":
  "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z",
    "resultTime":
  "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z"
  }

The observationType defines the result types for specialized observations [OGC 10-004r3 and ISO 19156:2011 Table 3]. The following table shows some of the valueCodes that maps the UML classes in O&M v2.0 [OGC 10-004r3 and ISO 19156:2011] to observationType names and observation result types.

8.2.5     Sensor

A Sensor is an instrument that observes a property or phenomenon with the goal of producing an estimate of the value of the property[3].

The Sensor encodingType allows clients to know how to interpret metadata’s value. Currently SensorThings API defines two common Sensor 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.

Example 5 An example of a Sensor entity:

  {
    "@iot.id": 1,
    "@iot.selfLink":
  "http://example.org/v1.0/Sensors(1)",
   
  "Datastreams@iot.navigationLink":
  "Sensors(1)/Datastreams",
    "name": "TMP36",

    "description": "TMP36
  - Analog Temperature sensor",
    "encodingType": "application/pdf",
    "metadata":
  "http://example.org/TMP35_36_37.pdf"
  }

8.2.6     ObservedProperty

An ObservedProperty specifies the phenomenon of an Observation.

Example 6 an example ObservedProperty entity:

  {
    "@iot.id": 1,
    "@iot.selfLink":
  "http://example.org/v1.0/ObservedProperties(1)",
   
  "Datastreams@iot.navigationLink":
  "ObservedProperties(1)/Datastreams",
    "description":
  "The dewpoint temperature is the temperature to which the air must be
  cooled, at constant pressure, for dew to form. As the grass and other objects
  near the ground cool to the dewpoint, some of the water vapor in the
  atmosphere condenses into liquid water on the objects.",
    "name":
  "DewPoint Temperature",
    "definition":
  "http://dbpedia.org/page/Dew_point"
  }

8.2.7     Observation

An Observation is the act of measuring or otherwise determining the value of a property [OGC 10-004r3 and ISO 19156:2011]

Example 7  An Observation entity example - The following example shows an Observation whose Datastream has an ObservationType of OM_Measurement. A result’s data type is defined by the observationType.

  {
   
  "@iot.id": 1,
   
  "@iot.selfLink":
  "http://example.org/v1.0/Observations(1)",
   
  "FeatureOfInterest@iot.navigationLink":
  "Observations(1)/FeatureOfInterest",
   
  "Datastream@iot.navigationLink":"Observations(1)/Datastream",
   
  "phenomenonTime": "2014-12-31T11:59:59.00+08:00",
   
  "resultTime": "2014-12-31T11:59:59.00+08:00",
   
  "result": 70.4
  }

8.2.8    FeatureOfInterest

An Observation results in a value being assigned to a phenomenon. The phenomenon is a property of a feature, the latter being the FeatureOfInterest of the Observation [OGC and ISO 19156:2011]. In the context of the Internet of Things, many Observations’ FeatureOfInterest can be the Location of the Thing. For example, the FeatureOfInterest of a wifi-connect thermostat can be the Location of the thermostat (i.e., the living room where the thermostat is located in). In the case of remote sensing, the FeatureOfInterest can be the geographical area or volume that is being sensed.

Example 8 an example of a FeatureOfInterest entity

  {
   
  "@iot.id": 1,
   
  "@iot.selfLink":
  "http://example.org/v1.0/FeaturesOfInterest(1)",
   
  "Observations@iot.navigationLink":
  "FeaturesOfInterest(1)/Observations",
    "name":
  "Weather Station YYC.",
   
  "description": "This is a weather station located at
  the Calgary Airport.",
   
  "encodingType": "application/vnd.geo+json",
   
  "feature": {
      "type":
  "Feature",
      "geometry":{
        "type": "Point",
        "coordinates": [-114.06,51.05]
      }
    }
  }

9.    SensorThings Service Interface

An OGC SensorThings API service exposes a service document resources that describe its data model. The service document lists the entity sets that can be CRUD. SensorThings API clients can use the service document to navigate the available entities in a hypermedia-driven fashion.

9.1    URI Components

The OGC SensorThings API service groups the same types of entities into entity sets.Each entity has a unique identifier and one-to-many properties. Also, in the case of an entity holding a relationship with entities in other entity sets, this type of relationship is expressed with navigation properties (i.e., navigationLink and associationLink).

Therefore, in order to perform CRUD actions on the resources, the first step is to address to the target resource(s) through URI. There are three major URI components used here, namely (1) the service root URI, (2) the resource path, and (3) the query options. In addition, the service root URI consists of two parts: (1) the location of the SensorThings service and (2) the version number. The version number follows the format indicated below:

    “v”majorversionnumber + “.” + minorversionnumber

Example 9 complete URI example

  http://example.org/v1.0/Observations?$orderby=ID&$top=10
  _______________________/___________/___________________/
            |                 |               |
    service root URI     resource path   query options

By attaching the resource path after the service root URI, clients can address to different types of resources such as an entity set, an entity, a property, or a navigation property. Finally, clients can apply query options after the resource path to further process the addressed resources, such as sorting by properties or filtering with criteria.

9.2    Resource Path

The resource path comes right after the service root URI and can be used to address to different resources. The following lists the usages of the resource path.

9.2.1     Usage 1: no resource path

URI Pattern: SERVICE_ROOT_URI

Response: A JSON object with a property named value. The value of the property SHALL be a JSON Array containing one element for each entity set of the SensorThings Service.

Each element SHALL be a JSON object with at least two name/value pairs, one with name name containing the name of the entity set (e.g., Things, Locations, Datastreams, Observations, ObservedProperties and Sensors) and one with name url containing the URL of the entity set, which may be an absolute or a relative URL.

[Adapted from OData 4.0-JSON-Format section 5]

Example 10 a SensorThings request with no resource path

Example Request:

http://example.org/v1.0/

Example Response:

  {
  "value": [
      {
  "name": "Things",
  "url": "http://example.org/v1.0/Things"
      },
      {
  "name": "Locations",
  "url": " http://example.org/v1.0/Locations"
      },
      {
  "name": "Datastreams",
  "url": " http://example.org/v1.0/Datastreams"
      },
      {
  "name": "Sensors",
  "url": " http://example.org/v1.0/Sensors"
      },
      {
  "name": "Observations",
  "url": " http://example.org/v1.0/Observations"
      },
      {
  "name": "ObservedProperties",
  "url": "
  http://example.org/v1.0/ObservedProperties"
      },
      {
  "name": "FeaturesOfInterest",
  "url": "
  http://example.org/v1.0/FeaturesOfInterest"
      }
    ]
  }

9.2.2     Usage 2: address to a collection of entities

To address to an entity set, users can simply put the entity set name after the service root URI. The service returns a JSON object with a property of value. The value of the property SHALL be a list of the entities in the specified entity set.

URI Pattern: SERVICE_ROOT_URI/ENTITY_SET_NAME

Response: A list of all entities (with all the properties) in the specified entity set when there is no service-driven pagination imposed. The response is represented as a JSON object containing a name/value pair named value. The value of the value name/value pair is a JSON array where each element is representation of an entity or a representation of an entity reference. An empty collection is represented as an empty JSON array.

The count annotation represents the number of entities in the collection. If present, it comes before the value name/value pair.

When there is service-driven pagination imposed, the nextLink annotation is included in a response that represents a partial result.

[Adapted from OData 4.0-JSON-Format section 12]

Example 11 an example to address an entity set

Example Request:

http://example.org/v1.0/ObservedProperties

Example Response:

  {
  "@iot.count":84
  "value": [
      {
  "@iot.id": 1,
  "@iot.selfLink":
  "http://example.org/v1.0/ObservedProperties(1)",
  "Datastreams@iot.navigationLink":
  "ObservedProperties(1)/Datastreams",
  "description": "The dew point is the temperature at
  which the water vapor in air at constant barometric pressure condenses into
  liquid water at the same rate at which it evaporates.",
  "name": "DewPoint Temperature",
  "definition": "http://dbpedia.org/page/Dew_point"
      },
      {
  "@iot.id ": 2,
  "@iot.selfLink":
  "http://example.org/v1.0/ObservedProperties(2)",
  "Datastreams@iot.navigationLink": "ObservedProperties(2)/Datastreams",
  "description": "Relative humidity is the ratio of the
  partial pressure of water vapor in an air-water mixture to the saturated
  vapor pressure of water at a prescribed temperature.",
  "name": "Relative Humidity",
        "definition":
  "http://dbpedia.org/page/Relative_humidity"
  },{…},{…},{…}
    ]
  "@iot.nextLink":"http://example.org/v1.0/ObservedProperties?$top=5&$skip=5"
  }

9.2.3     Usage 3: address to an entity in a collection

Users can address to a specific entity in an entity set by place the unique identifier of the entity between brace symbol “()” and put after the entity set name. The service then returns the entity with all its properties.

URI Pattern: SERVICE_ROOT_URI/ENTITY_SET_NAME(ID_OF_THE_ENTITY)

Response:A JSON object of the entity (with all its properties) that holds the specified id in the entity set.

Example 12: an example request that addresses to an entity in a collection

Example Request:

http://example.org/v1.0/Things(1)

9.2.4     Usage 4: address to a property of an entity

Users can address to a property of an entity by specifying the property name after the URI addressing to the entity. The service then returns the value of the specified property. If the property has a complex type value, properties of that value can be addressed by further property name composition.

If the property is single-valued and has the null value, the service SHALL respond with 204 No Content. If the property is not available, for example due to permissions, the service SHALL respond with 404 Not Found.

[Adapted from OData 4.0-Protocol 11.2.3]

URI Pattern: SERVICE_ROOT_URI/RESOURCE_PATH_TO_AN_ENTITY/PROPERTY_NAME

Response: The specified property of an entity that holds the id in the entity set.

Example 13: an example to address to a property of an entity

Example Request:

http://example.org/v1.0/Observations(1)/resultTime

Example Response:

  {

   "resultTime":
  "2010-12-23T10:20:00-07:00"

  }

9.2.5     Usage 5: address to the value of an entity’s property

To address the raw value of a primitive property, clients append a path segment containing the    string $value to the property URL.           

The default format for TM_Object types is text/plain using the ISO8601 format, such as 2014-03-01T13:00:00Z/2015-05-11T15:30:00Z for TM_Period and 2014-03-01T13:00:00Z for TM_Instant.

URI Pattern: SERVICE_ROOT_URI/ENTITY_SET_NAME(ID_OF_THE_ENTITY)/PROPERTY_NAME/$value

Response: The raw value of the specified property of an entity that holds the id in the entity set.

Example 14: an example of addressing to the value of an entity’s property

Example:

http://example.org/v1.0/Observations(1)/resultTime/$value 

Example Response:

  2015-01-12T23:00:13-07:00

9.2.6     Usage 6: address to a navigation property (navigationLink)

As the entities in different entity sets may hold some relationships, users can request the linked entities by addressing to a navigation property of an entity. The service then returns one or many entities that hold a certain relationship with the specified entity.

URI Pattern: SERVICE_ROOT_URI/ENTITY_SET_NAME(ID_OF_THE_ENTITY)/LINK_NAME

Response: A JSON object of one entity or a JSON array of many entities that holds a certain relationship with the specified entity.

Example 15: an example request addressing to a navigational property

Example:

  http://example.org/v1.0/Datastreams(1)/Observations  

returns all the Observations in the Datastream that holds the id 1.

9.2.7     Usage 7: address to an associationLink

As the entities in different entity sets may hold some relationships, users can request the linked entities’ selfLinks by addressing to an association link of an entity. An associationLink can be used to retrieve a reference to an entity or an entity set related to the current entity. Only the selfLinks of related entities are returned when resolving associationLinks.

URI Pattern: SERVICE_ROOT_URI/ENTITY_SET_NAME(KEY_OF_THE_ENTITY)/LINK_NAME/$ref

Response: A JSON object with a value property. The value of the value property is a JSON array containing one element for each associationLink. Each element is a JSON object with a name/value pairs. The name is url and the value is the selfLinks of the related entities.

Example 16: an example of addressing to an association link

Example Request:

  http://example.org/v1.0/Datastreams(1)/Observations/$ref  

returns all the selfLinks of the Observations of Datastream(1).

Example Response:

  {
  "value": [
      {
        "@iot.selfLinks":
  "http://example.org/v1.0/Observations(1)"
      },
      {
        "@iot.selfLinks":
  "http://example.org/v1.0/Observations(2)"
      }
    ]
  }

9.2.8     Usage 8: nested resource path

As users can use navigation properties to link from one entity set to another, users can further extend the resource path with unique identifiers, properties, or links (i.e., Usage 3, 4 and 6).

Example 17: examples of nested resource path

Example Request 1:

http://example.org/v1.0/Datastreams(1)/Observations(1) 

returns a specific Observation entity in the Datastream.

Example Request 2:

http://example.org/v1.0/Datastreams(1)/Observations(1)/resultTime 

turns the resultTime property of the specified Observation in the Datastream.

Example Request 3:

http://example.org/v1.0/Datastreams(1)/Observations(1)/FeatureOfInterest 

returns the FeatureOfInterest entity of the specified Observation in the Datastream.

9.3    Requesting Data

Clients issue HTTP GET requests to OGC SensorThings API services for data. The resource path of the URL specifies the target of the request. Additional query operators can be specified through query options that are presented as follows. The query operators are prefixed with a dollar ($) character and specified as key-value pairs after the question symbol (?) in the request URI. Many of the OGC SensorThings API’s query options are adapted from OData’s query options. OData developers should be able to pick up SensorThings API query options very quickly.

9.3.1     Evaluating System Query Options

The OGC SensorThings API adapts many of OData’s system query options and their usage. These query options allow refining the request.

The result of the service request is as if the system query options were evaluated in the following order.

Prior to applying any server-driven pagination:

• $filter
• $count
• $orderby
• $skip
• $top

After applying any server-driven pagination:

• $expand
• $select

9.3.2     Specifying Properties to Return

The $select and $expand system query options enable the client to specify the set of properties to be included in a response.

9.3.2.1     $expand

Example 18: examples of $expand query option

Example Request 1:

http://example.org/v1.0/Things?$expand=Datastreams 

returns the entity set of Things as well as each of the Datastreams associated with each Thing entity.

Example Request 1 Response:

  {
    "values":[
       {
         "@iot.id": 1,
         "@iot.selfLink":
  "http://example.org/v1.0/Things(1)",
         "Locations@iot.navigationLink":
  "Things(1)/Locations",
         "Datastreams@iot.count":1,
         "Datastreams": [
            {
               "@iot.id":
  1,
               "@iot.selfLink":
  "http://example.org/v1.0/Datastreams(1)",
               "name": "oven
  temperature",

               "description":
  "This is a datastream measuring the air temperature in an oven.",
               "unitOfMeasurement": {
                  "name": "degree
  Celsius",
                  "symbol": "°C",
                  "definition":
  "http://unitsofmeasure.org/ucum.html#para-30"
                },
                "observationType":
  "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
                "observedArea": {
                  "type":
  "Polygon",
                  "coordinates":
  [[[100,0],[101,0],[101,1],[100,1],[100,0]]]
                },
                "phenomenonTime": "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z",
                "resultTime":
  "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z"
            }
         ],
         "HistoricalLocations@iot.navigationLink":
  "Things(1)/HistoricalLocations",
         "description": "This thing is
  a convection oven.",

         "name": "Oven",
         "properties": {
           "owner": "John Doe",
           "color": "Silver"
         }
       }
    ]
  }

Example Request 2:

http://example.org/v1.0/Things?$expand=Datastreams/ObservedProperty 

returns the collection of Things, the Datastreams associated with each Thing, and the ObservedProperty associated with each Datastream.

Example Request 3:

http://example.org/v1.0/Datastreams(1)?$expand=Observations,ObservedProperty 

returns the Datastream whose id is 1 as well as the Observations and ObservedProperty associated with this Datastream.

Query options can be applied to the expanded navigation property by appending a semicolon-separated list of query options, enclosed in parentheses, to the navigation property name. Allowed system query options are $filter, $select, $orderby, $skip, $top, $count, and $expand.

[Adapted from OData 4.0- URL 5.1.2]

Example Request 4:

http://example.org/v1.0/Datastreams(1)?$expand=Observations($filter=result eq 1) 

returns the Datastream whose id is 1 as well as its Observations with a result equal to 1.

9.3.2.2     $select

Example 19: examples of $select query option

Example Request 1:

http://example.org/v1.0/Observations?$select=result,resultTime 

returns only the result and resultTime properties for each Observation entity.

Example Request 2:

http://example.org/v1.0/Datastreams(1)?$select=id,Observations&$expand=Observations/FeatureOfInterest 

returns the id property of the Datastream entity, and all the properties of the entity identified by the Observations and FeatureOfInterest navigation properties.

Example Request 3:

http://example.org/v1.0/Datastreams(1)?$expand=Observations($select=result) 

returns the Datastream whose id is 1 as well as the result property of the entity identified by the Observations navigation property.

9.3.3     Query Entity Sets

9.3.3.1    $orderby

Example 20: examples of $orderby query option

Example Request 1:

http://example.org/v1.0/Observations?$orderby=result 

returns all Observations ordered by the result property in ascending order.

Example Request 2:

http://example.org/v1.0/Observations?$expand=Datastream&$orderby=Datastreams/id desc, phenomenonTime 

returns all Observations ordered by the id property of the linked Datastream entry in descending order, then by the phenomenonTime property of Observations in ascending order.

9.3.3.2     $top

Example 21: examples of $top query option

Example Request 1:

http://example.org/v1.0/Things?$top=5 

returns only the first five entities in the Things collection.

Example Request 2:

http://example.org/v1.0/Observations?$top=5&$orderby=phenomenonTime%20desc 

returns the first five Observation entries after sorted by the phenomenonTime property in descending order.

9.3.3.3     $skip

Example 22: examples of $skip query option

Example Request 1:

  http://example.org/v1.0/Things?$skip=5  

returns Thing entities starting with the sixth Thing entity in the Things collection.

Example Request 2: http://example.org/v1.0/Observations?$skip=2&$top=2&$orderby=resultTime returns the third and fourth Observation entities from the collection of all Observation entities when the collection is sorted by the resultTime property in ascending order.

9.3.3.4     $count

Example 23: examples of $count query option

Example Request 1:

  http://example.org/v1.0/Things?$count=true  

return, along with the results, the total number of Things in the collection.

Example Response:

  {
    "@iot.count":
  2,
   
  "value": [
      {…},
      {…}
    ]
  }

9.3.3.5    $filter

Example 24: examples of $filter query option

Example Request 1:http://example.org/v1.0/Observations?$filter=result lt 10.00 returns all Observations whose result is less than 10.00.

In addition, clients can choose to use the properties of linked entities in the $filter predicate. The following are examples of the possible uses of the $filter in the data model of the SensorThings service.

Example Request 2: http://example.org/v1.0/Observations?$filter=Datastream/id eq ‘1’ returns all Observations whose Datastream’s id is 1.

Example Request 3: http://example.org/v1.0/Things?$filter=geo.distance(Locations/location, geography’POINT(-122, 43)’) gt 1 returns Things that the distance between their last known locations and POINT(-122 43) is greater than 1.

Example Request 4:

http://example.org/v1.0/Things?$expand= Datastreams/Observations/FeatureOfInterest&$filter=Datastreams/Observations/FeatureOfInterest/id eq ‘FOI_1’ and Datastreams/Observations/resultTime ge 2010-06-01T00:00:00Z and Datastreams/Observations/resultTime le 2010-07-01T00:00:00Z returns Things that have any observations of a feature of interest with a unique identifier equals to ’FOI_1’ in June 2010.

9.3.3.5.1     Built-in filter operations

The OGC SensorThings API supports a set of built-in filter operations, as described in the following table. These built-in filter operator usages and definitions follow the [OData Specification Section 11.2.5.1.1] and [OData Version 4.0 ABNF].

9.3.3.5.2     Built-in query functions

The OGC SensorThings API supports a set of functions that can be used with the $filter or $orderby query operations. The following table lists the available functions and they follows the OData Canonical function definitions listed in Section 5.1.1.4 of the [OData Version 4.0 Part 2: URL Conventions] and the syntax rules for these functions are defined in [OData Version 4.0 ABNF].

In order to support spatial relationship functions, SensorThings API defines nine additional geospatial functions based on the spatial relationship between two geometry objects. The spatial relationship functions are defined in the OGC Simple Feature Access specification [OGC 06-104r4 part 1, clause 6.1.2.3]. The names of these nine functions start with a prefix “st_” following the OGC Simple Feature Access specification [OGC 06-104r4]. In addition, the Well-Known Text (WKT) format is the default input geometry for these nine functions.

9.3.3.6     Server-Driven Paging (nextLink)

Example 25: http://example.org/v1.0/Things returns a subset of the Thing entities of requested collection of Things. The nextLink contains a link allowing retrieving the next partial set of items.

Example Response:

  {
   
  "value": [
      {…},
      {…}
    ],
   
  "@iot.nextLink":
  "http://examples.org/v1.0/Things?$top=100&$skip=100"
  }

10.    SensorThings Sensing Create-Update-Delete

10.1    Overview

As many IoT devices are resource-constrained, the SensorThings API adopts the efficient REST web service style. That means the Create, Update, Delete actions can be performed on the SensorThings entity types. The following subsection explains the Create, Update, and Delete protocol.

10.2     Create an entity

10.2.1     Request

   HTTP Method: POST
   URI Pattern:SERVICE_ROOT_URI/COLLECTION_NAME
   Header: Content-Type: application/json
   Message Body: A single valid entity representation for the specified collection.

  POST /v1.0/Things HTTP/1.1
   
  Host: example.org/
  Content-Type: application/json
   
  {
     "name":
  "thermostat",

     "description":"This
  is a smart thermostat with WiFi communication capabilities."
  }

10.2.1.1    Link to existing entities when creating an entity

Example 27: create an Observation entity, which links to an existing Sensor entity (whose id is 1), an existing FeatureOfInterest entity (whose id is 2).

  POST /v1.0/Observations HTTP/1.1
  Host: example.org
  Content-Type: application/json
   
  {
    "Datastream":
  {
      "@iot.id":
  1
    },
   
  "phenomenonTime": “2013-04-18T16:15:00-07:00",
   
  "result": 124,
    "FeatureOfInterest":
  {
      "@iot.id":
  2
    }
  }

10.2.1.2    Create related entities when creating an entity

Example 28: create a Thing while creating two related Sensors and one related Observation (which links to an existing FeatureOfInterest entity and an existing ObservedProperty entity).

  POST /v1.0/Things HTTP1.1
  Host: example.org
  Content-Type: application/json
   
  {
    "description":
  "This an oven with a temperature datastream.",

    "name": "oven",
    "Locations": [
      {
        "name": "CCIT",
        "description":
  "Calgary Centre for Innovative Technologies",

        "encodingType":
  "application/vnd.geo+json",
        "location": {
          "type":
  "Feature",
          "geometry": {
            "type":
  "Point",
           
  "coordinates": [10,10]
          }
        }
      }
    ],
    "Datastreams": [
      {
        "name": "oven
  temperature",

        "description":
  "This is a datastream for an oven’s internal temperature.",
       
  "unitOfMeasurement": {
          "name":
  "degree Celsius",
          "symbol":
  "°C",
          "definition":
  "http://unitsofmeasure.org/ucum.html#para-30"
        },
       
  "observationType":
  "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
        "observedArea":
  {
          "type":
  "Polygon",
          "coordinates":
  [[[100,0], [101,0], [101,1], [100,1], [100,0]]]
        },
       
  "phenomenonTime": "2009-01-11T16:22:25.00Z/2011-08-21T08:32:10.00Z",
        "Observations":
  [
          {
           
  "phenomenonTime": "2012-06-26T03:42:02-0600",
            "result":
  70.4,
           
  "FeatureOfInterest": {
              "name":
  "CCIT #361",

              "description": "This
  is CCIT #361, Noah’s dad’s office",
             
  "encodingType": "application/vnd.geo+json",
              "feature":
  {
                "type":
  "Feature",
               
  "geometry": {
                 
  "type": "Polygon",
                 
  "coordinates": [
                    [[100,50], [10,9], [23,4],
  [100,50]], [[30,20], [10,4], [4,22], [30,20]]

                  ]
                }}}}
        ],
       
  "ObservedProperty": {
          "name":
  "DewPoint Temperature",
          "definition":
  "http://sweet.jpl.nasa.gov/ontology/property.owl#DewPointTemperature",
          "description":
  "The dewpoint temperature is the temperature to which the air must be
  cooled, at constant pressure, for dew to form. As the grass and other objects
  near the ground cool to the dewpoint, some of the water vapor in the
  atmosphere condenses into liquid water on the objects."
        },
        "Sensor": {
          "name": "DS18B20",
          "description":
  "DS18B20 is an air temperature sensor…",

          "encodingType":
  "application/pdf",
          "metadata":
  "http://datasheets.maxim-ic.com/en/ds/DS18B20.pdf"
        }
      }
    ]
  }

10.2.2    Response

10.3    Update an entity

10.3.1    Request

In SensorThings PATCH is the preferred means of updating an entity. PATCH provides more resiliency between clients and services by directly modifying only those values specified by the client.

The semantics of PATCH, as defined in [RFC5789], are to merge the content in the request payload with the entity’s current state, applying the update only to those components specified in the request body. The properties provided in the payload corresponding to updatable properties SHALL replace the value of the corresponding property in the entity. Missing properties of the containing entity or complex property SHALL NOT be directly altered.

Services MAY additionally support PUT, but should be aware of the potential for data-loss in round-tripping properties that the client may not know about in advance, such as open or added properties, or properties not specified in metadata. Services that support PUT SHALL replace all values of structural properties with those specified in the request body. Omitting a non-nullable property with no service-generated or default value from a PUT request results in a 400 Bad Request error.

Key and other non-updatable properties that are not tied to key properties of the principal entity, can be omitted from the request. If the request contains a value for one of these properties, the service SHALL ignore that value when applying the update.

The service ignores entity id in the payload when applying the update.

The entity SHALL NOT contain related entities as inline content. It MAY contain binding information for navigation properties. For single-valued navigation properties this replaces the relationship. For collection-valued navigation properties this adds to the relationship.

On success, the response SHALL be a valid success response.

Services MAY additionally support JSON PATCH format [RFC6902] to express a sequence of operations to apply to a SensorThings entity.

[Adapted from OData 4.0-Protocol 11.4.3]

HTTP Method: PATCH or PUT

URI Pattern: An URI addressing to a single entity.

Header: Content-Type: application/json

Message Body: A single entity representation including a subset of properties for the specified collection.

Example 29: update the Thing whose id is 1.

  PATCH /v1.0/Things(1) HTTP1.1
  Host: example.org
  Content-Type: application/json
   
  {
   
  "description":"This thing is an oven."
  }

10.3.2    Response

On success, the response SHALL be a valid success response. In addition, when the client sends an update request to a valid URL where an entity does not exist, the service SHALL fail the request.

Upon successful completion, the service must respond with 200 OK or 204 No Content. Regarding all the HTTP status code, please refer to the HTTP Status Code section.

10.4    Delete an entity

10.4.1    Request

A successful DELETE request to an entity’s edit URL deletes the entity. The request body SHOULD be empty. 

Services SHALL implicitly remove relations to and from an entity when deleting it; clients need not delete the relations explicitly.

Services MAY implicitly delete or modify related entities if required by integrity constraints. Table 25 listed SensorThings API’s integrity constraints when deleting an entity.

HTTP Method:DELETE

URI Pattern: An URI addressing to a single entity.

Example 30: delete the Thing with unique identifier equals to 1

  DELETE http://example.org/v1.0/Things(1)

11.    Batch Requests

11.1    Introduction

The SensorThings service interface provides interfaces for users to perform CRUD actions on resources through different HTTP methods. However, as many IoT devices are resource-constrained, handling a large number of communications may not be practical. This section describes how a SensorThings service can support executing multiple operations sent in a single HTTP request through the use of batch processing. This section covers both how batch operations are represented and processed. SensorThings batch request extension is adapted from [OData 4.0 Protocol 11.7] and all subsections. The only difference is that the OData-Version header SHOULD be omitted in SensorThings. Readers are encouraged to read the OData specification section 11.7 before reading the examples below.

11.2    Batch-processing request

A batch request is represented as a Multipart MIME v1.0 message [RFC2046], a standard format allowing the representation of multiple parts, each of which may have a different content type, within a single request.

The example below shows a GUID as a boundary and example.org/v1.0/ for the URI of the service.

Batch requests are submitted as a single HTTP POST request to the batch endpoint of a service, located at the URL $batch relative to the service root (e.g., example.org/v1.0/$batch).

Note: In the example, request bodies are excluded in favor of English descriptions inside ‘<>’ brackets to simplify the example.

Example 31-1: A Batch Request header example

  POST /v1.0/$batch HTTP/1.1
  Host: example.org
  Content-Type:
  multipart/mixed;boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
   
  <BATCH_REQUEST_BODY>

Note: The batch request boundary must be quoted if it contains any of the following special characters:

  ( ) < > @
  , ; :  / " [ ] ? =

11.2.1    Batch request body example

The following example shows a Batch Request that contains the following operations in the order listed

• A query request
• Change Set that contains the following requests:
• Insert entity (with Content-ID = 1)
• Update request (with Content-ID = 2)
• A second query request

Note: For brevity, in the example, request bodies are excluded in favor of English descriptions inside <> brackets.

Note also that the two empty lines after the Host header of the GET request are necessary: the first is part of the GET request header; the second is the empty body of the GET request, followed by a CRLF according to [RFC2046].

[Adapted from OData 4.0 Protocol 11.7.2]

Example 31-2: a Batch Request body example

  POST /v1.0/$batch HTTP/1.1 
  Host: host 
  Content-Type: multipart/mixed;boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
  Content-Length: ###
   
  --batch_36522ad7-fc75-4b56-8c71-56071383e77b
  Content-Type: application/http
  
  Content-Transfer-Encoding:binary
   
  GET /v1.0/Things(1) 
  Host: host
   
   
  --batch_36522ad7-fc75-4b56-8c71-56071383e77b
  Content-Type:
  multipart/mixed;boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
   
  --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
  
  Content-Type: application/http
  
  Content-Transfer-Encoding:
  binary 
  Content-ID: 1
   
  POST /v1.0/Things HTTP/1.1 
  Host: host  
  Content-Type: application/json
  
  Content-Length: ### 
   
  <JSON representation of a
  new Thing>
  --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
  
  Content-Type: application/http
  
  Content-Transfer-Encoding:binary
  Content-ID: 2
   
  PATCH /v1.0/Things(1) HTTP/1.1
  
  Host: host 
  Content-Type: application/json
  
  If-Match: xxxxx 
  Content-Length: ### 
   
  <JSON representation of
  Things(1)>
  --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd--
  --batch_36522ad7-fc75-4b56-8c71-56071383e77b
  
  Content-Type: application/http
  
  Content-Transfer-Encoding:
  binary 
   
  GET /v1.0/Things(3) HTTP/1.1 
  Host: host 
   
   
  --batch_36522ad7-fc75-4b56-8c71-56071383e77b--

11.2.2    Referencing new entities in a change set example

Example 31-3: A Batch Request that contains the following operations in the order listed:

A change set that contains the following requests:

1. Insert a new Datastream entity (with Content-ID = 1)
2. Insert a second new entity, a Sensor entity in this example (reference request with Content-ID = 1)

  POST
  /v1.0/$batch HTTP/1.1 
  Host: host 
  Content-Type:
  multipart/mixed;boundary=batch_36522ad7-fc75-4b56-8c71-56071383e77b
   
  --batch_36522ad7-fc75-4b56-8c71-56071383e77b
  Content-Type:
  multipart/mixed;boundary=changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
   
  --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
  Content-Type:
  application/http 
  Content-Transfer-Encoding:
  binary 
  Content-ID:
  1 
   
  POST
  /v1.0/Datastreams HTTP/1.1 
  Host:
  host  
  Content-Type:
  application/json
  Content-Length:
  ### 
   
  <JSON
  representation of a new Datastream>
  --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd
  Content-Type:
  application/http 
  Content-Transfer-Encoding:
  binary 
  Content-ID:
  2
   
  POST
  /v1.0/Sensor HTTP/1.1 
  Host:
  host 
  Content-Type:
  application/json
  Content-Length:
  ### 
   
  <JSON
  representation of a new Sensor>
  --changeset_77162fcd-b8da-41ac-a9f8-9357efbbd--
  --batch_36522ad7-fc75-4b56-8c71-56071383e77b--

11.3    Batch-processing response

Example 31-4: referencing the batch request example 31-2 above, assume all the requests except the final query request succeed. In this case the response would be:

  HTTP/1.1
  200 Ok
  Content-Length:
  ####
  Content-Type:
  multipart/mixed;boundary=b_243234_25424_ef_892u748
   
  --b_243234_25424_ef_892u748
  Content-Type: application/http
  Content-Transfer-Encoding:
  binary
   
  HTTP/1.1
  200 Ok
  Content-Type:
  application/json
  Content-Length:
  ###
   
  <JSON
  representation of the Thing entity with id = 1>
  --b_243234_25424_ef_892u748
  Content-Type:
  multipart/mixed;boundary=cs_12u7hdkin252452345eknd_383673037
   
  --cs_12u7hdkin252452345eknd_383673037
  Content-Type:
  application/http
  Content-Transfer-Encoding:
  binary
  Content-ID:
  1
   
  HTTP/1.1
  201 Created
  Content-Type:
  application/json
  Location: http://host/v1.0/Things(99)
  Content-Length:
  ###
   
  <JSON
  representation of a new Thing entity>
   
  --cs_12u7hdkin252452345eknd_383673037
  Content-Type:
  application/http
  Content-Transfer-Encoding:
  binary
  Content-ID:
  2
   
  HTTP/1.1
  204 No Content
  Host:
  host
   
   
  --cs_12u7hdkin252452345eknd_383673037--
  --b_243234_25424_ef_892u748
  Content-Type: application/http
  Content-Transfer-Encoding:
  binary
   
  HTTP/1.1
  404 Not Found
  Content-Type:
  application/json
  Content-Length:
  ###
   
  <Error
  message>
  --b_243234_25424_ef_892u748--

11.4    Asynchronous batch requests

Example 31-5: referencing the example 31-2 above again, assume that when interrogating the monitor URL for the first time only the first request in the batch finished processing and all the remaining requests except the final query request succeed. In this case the response would be:

  HTTP/1.1
  200 Ok
  Content-Length:
  ####
  Content-Type:
  multipart/mixed;boundary=b_243234_25424_ef_892u748
   
  --b_243234_25424_ef_892u748
  Content-Type: application/http
  Content-Transfer-Encoding:
  binary
   
  HTTP/1.1
  200 Ok
  Content-Type:
  application/json
  Content-Length:
  ###
   
  <JSON
  representation of the Thing entity with id = 1>
  --b_243234_25424_ef_892u748
  Content-Type: application/http
  Content-Transfer-Encoding:
  binary
   
  HTTP/1.1
  202 Accepted 
  Location: http://service-root/async-monitor
  Retry-After:
  ###
   
   
  --b_243234_25424_ef_892u748--

Client makes a second request using the returned monitor URL:

  HTTP/1.1
  200 Ok
  Content-Length:
  ####
  Content-Type:
  multipart/mixed;boundary=b_243234_25424_ef_892u748
   
  --b_243234_25424_ef_892u748
  Content-Type:
  multipart/mixed;boundary=cs_12u7hdkin252452345eknd_383673037
   
  --cs_12u7hdkin252452345eknd_383673037
  Content-Type:
  application/http
  Content-Transfer-Encoding:
  binary
  Content-ID:
  1
   
  HTTP/1.1
  201 Created
  Content-Type:
  application/json
  Location: http://host/v1.0/Things(99)
  Content-Length:
  ###
   
  <JSON
  representation of a new Thing entity>
  --cs_12u7hdkin252452345eknd_383673037
  Content-Type:
  application/http
  Content-Transfer-Encoding:
  binary
  Content-ID:
  2
   
  HTTP/1.1
  204 No Content
  Host:
  host
   
   
  --cs_12u7hdkin252452345eknd_383673037--
  --b_243234_25424_ef_892u748
  Content-Type: application/http
  Content-Transfer-Encoding:
  binary
   
  HTTP/1.1
  404 Not Found
  Content-Type:
  application/json
  Content-Length:
  ###
   
  <Error
  message>
  --b_243234_25424_ef_892u748—

12.    SensorThings MultiDatastream extension

Observation results may have many data types, including primitive types like category or measure, but also more complex types such as time, location and geometry [OGC 10-004r3 and ISO 19156:2011]. SensorThings’ MultiDatastream entity is an extension to handle complex observations when the result is an array.

A MultiDatastream groups a collection of Observations and the Observations in a MultiDatastream have a complex result type.

The MultiDatastream extension entities are depicted in Figure 3.

Example 32: MultiDatastream entity example 1

  {
    "@iot.id":
  1,
    "@iot.selfLink":
  "http://example.org/v1.0/MultiDatastreams(1)",
    "Thing@iot.navigationLink":
  "MultiDatastreams(1)/Thing",
    "Sensor@iot.navigationLink":
  "MultiDatastreams(1)/Sensor",
    "ObservedProperty@iot.navigationLink":
  "MultiDatastreams(1)/ObservedProperties",
    "Observations@iot.navigationLink":"MultiDatastreams/Observations",
  "name": "temperature, RH, visibility",
  "description": "This is a
  MultiDatastream from a simple weather station measuring air temperature,
  relative humidity and visibility",
  "observationType":
  "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_ComplexObservation",
   
  "multiObservationDataTypes": [
     
  "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
     
  "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_Measurement",
     
  "http://www.opengis.net/def/observationType/OGC-OM/2.0/OM_CategoryObservation"
    ],
   
  "unitOfMeasurements": [
      {
       
  "name": "degree Celsius",
       
  "symbol": "
  °C",
       
  "definition": " http://unitsofmeasure.org/ucum.html#para-30"
      },
      {
       
  "name": " percent
  ",
       
  "symbol": "%",
       
  "definition": " http://unitsofmeasure.org/ucum.html#para-29"
      },
      {
       
  "name": "null",
       
  "symbol": "null",
       
  "definition": "null"
      }
    ],
   
  "observedArea": {
     
  "type": "Polygon",
     
  "coordinates": [
        [
         
  [100,0],[101,0],[101,1],[100,1],[100,0]
        ]
      ]
    },
   
  "phenomenonTime":
  "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z",
   
  "resultTime":
  "2014-03-01T13:00:00Z/2015-05-11T15:30:00Z"
  }

Example 33: an example ObservedProperties collection of the above MultiDatastream: Please note that the order of the elements in the value array match the order of the related Observations/result array as well as the order of the related unitOfMeasurements array.

  {
    "value": [
      {
        "@iot.id": 1,
        "@iot.selfLink":
  "http://example.org/v1.0/ObservedProperties(1)",
       
  "Datastreams@iot.navigationLink":
  "ObservedProperties(1)/Datastreams",
       
  "MultiDatastreams@iot.navigationLink":
  "ObservedProperties(1)/ MultiDatastreams",
        "description":
  "The dew point is the temperature at which the water vapor in a sample
  of air at constant barometric pressure condenses into liquid water at the
  same rate at which it evaporates. At temperatures below the dew point, water
  will leave the air.",
        "name":
  "Dew point temperature"
      },
      {
        "@iot.id ": 2,
        "@iot.selfLink":
  "http://example.org/v1.0/ObservedProperties(2)",
       
  "Datastreams@iot.navigationLink":
  "ObservedProperties(2)/Datastreams",
        "MultiDatastreams@iot.navigationLink":
  "ObservedProperties(2)/ MultiDatastreams",
        "description":
  "Relative humidity (abbreviated RH) is the ratio of the partial pressure
  of water vapor to the equilibrium vapor pressure of water at the same
  temperature.",
        "name": "Relative
  Humidity"
      },
      {
        "@iot.id": 3,
        "@iot.selfLink":
  "http://example.org/v1.0/ObservedProperties(3)",
       
  "Datastreams@iot.navigationLink":
  "ObservedProperties(3)/Datastreams",
       
  "MultiDatastreams@iot.navigationLink": "ObservedProperties(3)/MultiDatastreams",
        "description":
  "Visibility is a measure of the distance at which an object or light can
  be clearly discerned. ",
        "name":
  "Visibility (Weather)"
      }
    ]
  }

Example 34: an example Observation of the above MultiDatastream: Please note that the order of the elements in the result array match (1) the order of the related ObservedProperties (i.e., Observation(id)/MultiDatastreams(id)/ObservedProperties ), (2) the order of the related unitOfMeasurements array (i.e., Observation(id)/ MultiDatastream(id)/unitOfMeasurements ) and (3) the order of the related multiObservationDataTypes (i.e., Observation(id)/MultiDatastream(id)/multiObservationDataTypes).

  {
   
  "@iot.id": 1,
   
  "@iot.selfLink": "http://example.org/v1.0/Observations(1)",
   
  "FeatureOfInterest@iot.navigationLink":
  "Observations(1)/FeatureOfInterest",
   
  "MultiDatastream@iot.navigationLink":
  "Observations(1)/MultiDatastream",
   
  "phenomenonTime": "2014-12-31T11:59:59.00+08:00",
   
  "resultTime": "2014-12-31T11:59:59.00+08:00",
   
  "result": [
      25,
      65,
     
  "clear"
    ]
  }

13.    SensorThings Data Array Extension

Similar to the SWE DataArray in the OGC SOS, SensorThings API also provides the support of dataArray (in addition to formatting every observation entity as a JSON object) to aggregate multiple Observation entities and reduce the request (e.g., POST) and response (e.g., GET) size. SensorThings mainly use dataArray in two scenarios: (1) get Observation entities in dataArray, and (2) create Observation entities with dataArray.

13.1    Retrieve a Datastream’s Observation entities in dataArray

In SensorThings services, users are able to request for multiple Observation entities and format the entities in the dataArray format. When a SensorThings service returns a dataArray response, the service groups Observation entities by Datastream or MultiDatastream, which means the Observation entities that link to the same Datastream or the same MultiDatastream are aggregated in one dataArray.

13.1.1    Request

In order to request for dataArray, users must include the query option "$resultFormat=dataArray" when requesting Observation entities. For example, http://example.org/v1.0/Observations?$resultFormat=dataArray.

13.1.2    Response

The response Observations in dataArray format contains the following properties.

Example 35: an example of getting Observation entities from a Datastream in dataArray result format:

  GET /v1.0/Datastreams(1)/Observations?$resultFormat=dataArray 

  HTTP/1.1 200 OK
  Host: www.example.org
  Content-Type: application/json
   
  {
    "value": [
      {
       
  "Datastream@iot.navigationLink": "Datastreams(1)",
        "components": [
          "id",
         
  "phenomenonTime",
          "resultTime",
          "result"
        ],
       
  "dataArray@iot.count":3,
        "dataArray": [
          [
            1,
           
  "2005-08-05T12:21:13Z",
           
  "2005-08-05T12:21:13Z",
            20
          ],
          [
            2,
           
  "2005-08-05T12:22:08Z",
           
  "2005-08-05T12:21:13Z",
            30
          ],
          [
            3,
            "2005-08-05T12:22:54Z",
           
  "2005-08-05T12:21:13Z",
            0
          ]
        ]
      }
    ]
  }

Example 36: an example of getting Observation entities from a MultiDatastream in dataArray result format

  GET /v1.0/MultiDatastreams(1)/Observations?$resultFormat=dataArray 

  HTTP/1.1 200 OK
  Host: www.example.org
  Content-Type: application/json
   
  {
   
  "value": [
      {
       
  "MultiDatastream@iot.navigationLink":
  "MultiDatastreams(1)",
       
  "components": [
         
  "id",
         
  "phenomenonTime",
         
  "resultTime",
         
  "result"
        ],
       
  "dataArray@iot.count":3,
       
  "dataArray": [
          [
            1,
           
  "2010-12-23T11:20:00-0700",
           
  "2010-12-23T11:20:00-0700",
            [
              10.2,
             
  65,
             
  "clear"
            ]
          ],
          [
            2,
           
  "2010-12-23T11:22:08-0700",
           
  "2010-12-23T11:20:00-0700",
            [
             
  11.3,
             
  63,
             
  "clear"
            ]
          ],
          [
            3,
           
  "2010-12-23T11:22:54-0700",
           
  "2010-12-23T11:20:00-0700",
            [
             
  9.8,
             
  67,
             
  "clear"
            ]
          ]
        ]
      }
    ]
  }

13.2    Create Observation entities with dataArray

Besides creating Observation entities one by one with multiple HTTP POST requests, there is a need to create multiple Observation entities with a lighter message body in a single HTTP request. In this case, a sensing system can buffer multiple Observations and send them to a SensorThings service in one HTTP request. Here we propose an Action operation CreateObservations.

13.2.1    Request

Users can invoke the CreateObservations action by sending a HTTP POST request to the SERVICE_ROOT_URL/CreateObservations.

For example, http://example.org/v1.0/CreateObservations.

The message body aggregates Observations by Datastreams, which means all the Observations linked to one Datastream SHALL be aggregated in one JSON object. The parameters of each JSON object are shown in the following table.

As an Observation links to one FeatureOfInterest, to establish the link between an Observation and a FeatureOfInterest, users should include the FeatureOfInterest ids in the dataArray. If no FeatureOfInterest id presented, the FeatureOfInterest will be created based on the Location entities of the linked Thing entity by default.

Example 37: example of a request for creating Observation entities in dataArray

  POST /v1.0/CreateObservations HTTP/1.1
  Host: example.org/
  Content-Type: application/json
   
  [
    {
     
  "Datastream": {
       
  "@iot.id": 1
      },
     
  "components": [
       
  "phenomenonTime",
       
  "result",
       
  "FeatureOfInterest/id"
      ],
     
  "dataArray@iot.count":2,
     
  "dataArray": [
        [
         
  "2010-12-23T10:20:00-0700",
          20,
          1
        ],
        [
         
  "2010-12-23T10:21:00-0700",
          30,
          1
        ]
      ]
    },
    {
     
  "Datastream": {
       
  "@iot.id": 2
      },
     
  "components": [
       
  "phenomenonTime",
       
  "result",
       
  "FeatureOfInterest/id"
      ],
     
  "dataArray@iot.count":2,
     
  "dataArray": [
        [
         
  "2010-12-23T10:20:00-0700",
          65,
          1
        ],
        [
         
  "2010-12-23T10:21:00-0700",
          60,
          1
        ]
      ]
    }
  ]

13.2.2    Response

Upon successful completion the service SHALL respond with 201 Created. The response message body SHALL contain the URLs of the created Observation entities, where the order of URLs must match with the order of Observations in the dataArray from the request. In the case of the service having exceptions when creating individual observation entities, instead of responding with URLs, the service must specify "error" in the corresponding array element.

Example 38: an example of a response of creating Observation entities with dataArray

  POST /v1.0/CreateObservations HTTP/1.1 
  201 Created
  Host: example.org
  Content-Type: application/json
   
  [
  "http://examples.org/v1.0/Observations(1)",
  "error",
  "http://examples.org/v1.0/Observations(2)"
  ]

14.    SensorThings Sensing MQTT Extension

In addition to support HTTP protocol, a SensorThings service MAY support MQTT protocol to enhance the SensorThings service publish and subscribe capabilities. This section describes the SensorThings MQTT extension.

14.1    Create a SensorThings Observation with MQTT Publish

SensorThings MQTT extension provides the capability of creating Observation entity using MQTT protocol. To create an Observation entity in MQTT, the client sends a MQTT Publish request to the SensorThings service and the MQTT topic is the Observations resource path. The MQTT application message contains a single valid Observation entity representation. Figure 4 contains the sequence diagram for creating Observation using MQTT publish as well as MQTT sending notifications for Observation creation.

If the MQTT topic for the Observation is a navigationLink from Datastream or FeatureOfInterest, the new Observation entity is automatically linked to that Datastream or FeatureOfInterest respectively.

Similar to creating Observations with HTTP POST, creating Observations with MQTT Publish follow the integrity constraints for creating Observation listed in Table 24. The two special cases defined in Req 33 are also applied in the case of creating Observations with MQTT Publish.

14.1.1    Link to existing entities when creating an Observation entity

To link to existing entities when creating an Observation entity with MQTT, the conditions in Req 34 is applied.

14.1.2    Create related entities when creating an Observation entity (deep insert)

To create related entities when creating an entity with MQTT, the condition in Req 35 is applied.

14.2    Receive updates with MQTT Subscribe

To receive notifications from a SensorThings service when some entities updated, a client can send a MQTT Subscribe request to the SensorThings service. SensorThings API defined the following four MQTT subscription use cases. Figure 5 contains the sequence diagram of receiving updates using MQTT Subscribe.

14.2.1    Receive updates of a SensorThings entity set with MQTT Subscribe

MQTT Control Packet: Subscribe

Topic Pattern:RESOURCE_PATH/COLLECTION_NAME

Example Topic:Datastreams(1)/Observations

Response:When a new entity is added to the entity set (e.g., a new Observation created) or an existing entity of the entity set is updated, the service returns a complete JSON representation of the newly created or updated entity.

14.2.2    Receive updates of a SensorThings entity with MQTT Subscribe

MQTT Control Packet: Subscribe

Topic Pattern:RESOURCE_PATH_TO_AN_ENTITY

Example Topic:Datastreams(1)

Response:When a property of the subscribed entity is updated, the service returns a complete JSON representation of the updated entity.

14.2.3    Receive updates of a SensorThings entity’s property with MQTT Subscribe

MQTT Control Packet: Subscribe

Topic Pattern: RESOURCE_PATH_TO_AN_ENTITY/PROPERTY_NAME

Example Topic: Datastreams(1)/observedArea

Response: When the value of the subscribed property is changed, the service returns a JSON object. The returned JSON object follows as defined in Section 9.2.4 - Usage 4: address to a property of an entity.

Example 39: an example response of receiving updates of an entity’s property with MQTT Subscribe . - The example shows a sample response of the following MQTT topic subscription – Datastreams(1)/description

  {
  "description": "This is an updated description of a
  thing"
  }

14.2.4    Receive updates of the selected properties of the newly created entities or updated entities of a SensorThings entity set with MQTT Subscribe

MQTT Control Packet: Subscribe

Topic Pattern:RESOURCE_PATH/COLLECTION_NAME?$select=PROPERTY_1,PROPERTY_2,…

Response:When a new entity is added to an entity set or an existing entity is updated (e.g., a new Observation created or an existing Observation is updated), the service returns a JSON representation of the selected properties of the newly created or updated entity.

Note: In the case of an entity’s property is updated, it is possible that the selected properties are not the updated property, so that the returned JSON does not reflect the update.

Example 40: an example response of receiving updates of the selected property of an entity set with MQTT Subscribe . - The example shows a sample response of the following MQTT topic subscription - Datastreams(1)/Observations?$select=phenomenonTime,result

  {
   
  "result": 45,
   
  "phenonmenonTime": "2015-02-05T17:00:00Z"
  }

Annex A - Conformance Class Abstract Test Suite (Normative)

A.1     SensorThings Read (Core) Tests

This section contains the conformance classes for the SensorThings API Readi (Core). The SensorThings API service needs to pass all the conformance tests defined in this section.

A.2     SensorThings API Filtering Extension Tests

This section contains the conformance classes for the SensorThings API filtering extension. That means a SensorThings API service that allows clients to further filter data with query options needs to pass the conformance tests defined in this section.

A.3     SensorThings API Create-Update-Delete Extension Tests

This section contains the conformance classes for the SensorThings API create-update-delete extension. That means a SensorThings API service that allows clients to create/update/delete entities needs to pass the conformance tests defined in this section.

A.4     SensorThings API Batch Request Extension Tests

This section contains the conformance classes for the SensorThings API batch request extension. That means a SensorThings API service that allows clients to send a single HTTP request that groups multiple requests needs to pass the conformance tests defined in this section.

A.5     SensorThings API MultipleDatastream Tests

This section contains the conformance classes for the SensorThings API MultiDatastream extension. That means a SensorThings API service that allows clients to group a collection of observations’ results into an array (i.e., a complex result type) needs to pass the conformance tests defined in this section.

A.6     SensorThings API Data Array Extension

This section contains the conformance classe for the SensorThings API data array extension. That means a SensorThings API service that allows clients to request the compact data array encoding defined in this specification needs to pass the conformance tests defined in this section.

A.7     SensorThings API Observation Creation via MQTT Extension Tests

This section contains the conformance class for the SensorThings API Observation creation extension. That means a SensorThings API service that allows clients to create Observations via MQTT needs to pass the conformance tests defined in this section.

A.8     SensorThings API Receiving Updates via MQTT Extension Tests

This section contains the conformance class for the SensorThings API receiving updates extension. That means a SensorThings API service that allows clients to receive notifications regarding updates of entities via MQTT needs to pass the conformance tests defined in this section.

Annex B - Revision history

Annex : Bibliography

[1] The GeoJSON Format Specification, January 15, 2015. Available Online: https://datatracker.ietf.org/doc/draft-butler-geojson/

[2] ITU-T Y.2060 Overview of the Internet of Things, 2012. Available Online: https://www.itu.int/rec/T-REC-Y.2060-201206-I

[3] OGC and ISO 19156:2001, OGC 10-004r3 and ISO 19156:2011(E), OGC Abstract Specification: Geographic information — Observations and Measurements. Available Online: http://portal.opengeospatial.org/files/?artifact_id=41579

[4] OGC 12-000, OGC® SensorML: Model and XML Encoding Standard. Available Online: http://www.opengeospatial.org/standards/sensorml

[5] RFC 5023, The Atom Publishing Protocol. Available Online: https://www.ietf.org/rfc/rfc5023.txt

[6] RFC 6902, JavaScript Object Notation (JSON) Patch. Available Online: https://www.ietf.org/rfc/rfc6902.txt

[1] www.opengeospatial.org/cite

[2] The two terms of IoT and WoT are frequently used interchangeably.

[3] In some cases, the Sensor in this data model can also be seen as the Procedure (method, algorithm, or instrument) defined in [OGC 10-004r3 and ISO 19156:2011].