4.1. example term

5.1.  Introduction

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.2.  Identifiers

The normative provisions in this standard are denoted by the URI

http://www.opengis.net/spec/sensorthings/2.0

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

6.1.  Who should use the OGC SensorThings API

Organizations that need web-based platforms to manage, store, share, and analyze real-time sensor observation data should use the OGC SensorThings API. The OGC SensorThings API simplifies and accelerates the development of modern location enabled digital monitoring and control applications. Application developers can use this open standard to connect to various sensor devices and create innovative applications without worrying about the daunting heterogeneous protocols of the disparate vendor hardware including gateways and services. Sensor device manufacturers can also use OGC SensorThings API as the API can be embedded within various hardware and software platforms, thus allowing the various sensing devices to effortlessly connect with the OGC Standard-compliant servers around the world.

While the OGC SensorThings API was initially designed with IoT applications in mind, it has proven valuable for many non-IoT use cases as well:

In summary, the OGC SensorThings API is transforming the numerous disjointed networked sensor systems into a fully connected platform where complex tasks can be synchronized and performed. The flexible data model and powerful query capabilities make SensorThings API suitable for any application involving time-series observations, regardless of whether networked sensor devices are involved.

6.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, the OGC SensorThings API offers the following key benefits:

These benefits make the OGC SensorThings API particularly valuable in today’s rapidly evolving digital landscape, where organizations increasingly rely on sensor data for decision-making and automation.

6.3.  SensorThings API Overview

The OGC SensorThings API data model consists of three main parts:

Additionally, SensorThings API supports the following two extensions to the data model:

The core data model allows sensor devices and applications to CREATE, READ, UPDATE, and DELETE (i.e., HTTP POST, GET, PATCH, and DELETE) data and metadata in a SensorThings service. The Sensing part is designed based on the OGC/ISO Observation, Measurements and Samples (OMS) model ( OGC 20-082r4 and ISO 19156:2023).

An Observation is modeled as an act that produces a result whose value is an estimate of a property of a given Feature.

An Observation instance is characterized by its event time (e.g., resultTime and phenonmenonTime), Feature, ObservedProperty, and the procedure used (often a Sensor).

Moreover, Things are also modeled in the SensorThings API. A Thing draws from the same concept as a Host in OMS where a Host is defined as a collection of Observers (defined as Sensor in SensorThings API). Formally, its definition follows the ITU-T definition: “ an object of the physical world (physical things) or the information world (virtual things) that is capable of being identified and integrated into communication networks” [1].

The geographical Locations of Things are useful in almost every application and as a result are included as well. For the Things whose location changed, the HistoricalLocations entities offer the history of the Thing’s locations.

A Thing also can have multiple Datastreams. A Datastream is a collection of Observations grouped by the same ObservedProperty, Sensor and optionally by Feature and ObservingProcedure.

An Observation is an event performed by a Sensor that produces a result whose value is an estimate of an ObservedProperty of any given Feature which may be a proximate or ultimate FeatureofInterest. Details of each above described entity are provided in Clause 7.

6.4.  SensorThings API and Relation to ISO/OGC Observations, Measurements and Samples

Managing and retrieving observations and metadata from IoT sensor systems is one of the most common use cases. As a result, SensorThings API’s sensing part is designed based on the OMS model. OMS defines models for the exchange of information describing observation acts, their results as well as the feature involved in sampling when making observations.

SensorThings API defines nine entities for the IoT sensing applications and several additional entities in various extensions. Table 1 lists each component and its relationship with OMS. SensorThings API uses the term of Sensor to describe the Observer that is used in generating an Observation, instead of using OMS’ term of Observer.

Table 1 — SensorThings API Sensing entities and equivalent concepts in the Observations, Measurements and Samples standard

6.5.  SensorThings API 2.0 changes from 1.1

From the SensorThings API version 1.1 (OGC 18-088) to 2.0 changes have been made to both the data model and the API. The changes to the data model have been summarised in Table 2 and Figure 1.

Table 2 — Changes in the SensorThings API 2.0 data model compared to v1.1

Figure 1 — Sensing Core Changes

6.6.  Relation to OASIS-OData

OData is an API standard for exchanging relational data. It allows for the definition of a consistent REST API on any relational data model. OData specifies how clients can inspect the data model and how they can perform Create, Read, Update and Delete actions. OData comes with a very powerful query language that allows users to compose the response to queries such that only a minimal number of queries is required to fetch needed data, regardless of the use case of the client. The OData specification also defines filtering mechanisms that allows filtering across relations. OData uses JSON-encoding by default, and specifies generic rules for encoding relational data models in JSON.

The OGC SensorThings API v2 interface is not an OData interface and does not claim to be an OData service. It specifies a subset of the OData 4.01 specification, and extends it at the same time with certain features optimized for accessing sensor data. A SensorThings API Server implementation can implement the full OData specification. An OData client can access a SensorThings API service.

7.1.  Introduction

All data model requirements are grouped in the following requirements class:

The OGC SensorThings API v2.0 Core data model is depicted in Figure 2

Figure 2 — UML class diagram of the SensorThings API Core data model

In this section, we define each entity depicted in Figure 2 and its relationships with other entities. Additionally, we also provide examples to model the entities in different contexts.

7.2.  Recurring attributes

Several attributes are used in several classes. They always have the same semantic meaning, regarless of the class they are used in.

7.3.  Thing

The 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]. A Thing is related to the Platform entity as described in Section 4.9.2.1 of [OGC 16-079] in a way that any entity that can be modelled as a Thing MAY be subsequently translated to a Platform and vice versa.

Examples of the use of Thing are:

Table 3 — Attributes of a Thing entity

Table 4 — Direct relation between a Thing entity and other entity types

{
  "@context": "https://example.org/v2.0/$metadata#Things/$entity",
  "@id": "Things(1)",
  "id": 1,
  "name": "Oven",
  "description": "This thing is an oven.",
  "properties": {
    "owner": "Ulrike Schmidt",
    "color": "Black"
  },
  "Locations@navigationLink": "Things(1)/Locations",
  "Datastreams@navigationLink": "Things(1)/Datastreams",
  "HistoricalLocations@navigationLink": "Things(1)/HistoricalLocations"
}

Listing 1 — Example of a Thing entity returned by a HTTP end point.

7.4.  Location

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

Section 7.1.4 of [OGC 20-082r4 and ISO 19156:2023] provides a detailed explanation of observation location. Examples of the use of Location are:

Table 5 — Attributes of a Location entity

Table 6 — Direct relation between a Location entity and other entity types

Table 7 — Non-exhaustive list of code values used for identifying types for the encodingType of the Location and Feature entities

{
  "@context": "https://example.org/v2.0/$metadata#Locations/$entity",
  "@id": "Locations(1)",
  "id": 1,
  "name": "CCIT",
  "description": "Calgary Center for Innvative Technologies",
  "encodingType": "application/geo+json",
  "location": {
    "type": "Feature",
    "geometry":{
      "type": "Point",
      "coordinates": [-114.06,51.05]
    }
  },
  "Things@navigationLink": "Locations(1)/Things",
  "HistoricalLocations@navigationLink": "Locations(1)/HistoricalLocations",
}

Listing 2 — Example of a Location entity using a GeoJSON Feature.

{
  "@context": "https://example.org/v2.0/$metadata#Locations/$entity",
  "@id": "Locations(2)",
  "id": 2,
  "name": "IOSB",
  "description": "Fraunhofer-Institut für Optronik, Systemtechnik und Bildauswertung IOSB",
  "encodingType": "application/geo+json",
  "location": {
    "type": "Point",
    "coordinates": [8.426, 49.015]
  },
  "Things@navigationLink": "Locations(2)/Things",
  "HistoricalLocations@navigationLink": "Locations(2)/HistoricalLocations",
}

Listing 3 — Example of a Location entity using a GeoJSON Geometry.

{
  "@context": "https://example.org/v2.0/$metadata#Locations/$entity",
  "@id": "Locations(3)",
  "id": 3,
  "name": "Hamburg Port",
  "description": "Location at Hamburg Harbor",
  "encodingType": "text/plain",
  "location": "POINT(9.9937 53.5511)",
  "Things@navigationLink": "Locations(3)/Things",
  "HistoricalLocations@navigationLink": "Locations(3)/HistoricalLocations"
}

Listing 4 — Example of a Location entity using WKT.

{
  "@context": "https://example.org/v2.0/$metadata#Locations/$entity",
  "@id": "Locations(4)",
  "id": 4,
  "name": "Weather Station Alpha",
  "description": "Rooftop weather monitoring station",
  "encodingType": "application/vnd.ogc.fg+json",
  "location": {
    "type": "Feature",
    "place": {
      "type": "Point",
      "coordinates": [13.4050, 52.5200]
    },
    "geometry": {
      "type": "Point",
      "coordinates": [13.4050, 52.5200]
    },
    "properties": {
      "floor": 5,
      "building": "Tower A",
      "installation_date": "2023-01-15"
    }
  },
  "Things@navigationLink": "Locations(4)/Things",
  "HistoricalLocations@navigationLink": "Locations(4)/HistoricalLocations"
}

Listing 5 — Example of a Location entity using JSON-FG.

{
  "@context": "https://example.org/v2.0/$metadata#Locations/$entity",
  "@id": "Locations(5)",
  "id": 5,
  "name": "Drone Camera Position",
  "description": "Position and orientation of aerial survey drone",
  "encodingType": "application/geopose+json",
  "location": {
    "position": {
      "lat": 48.8584,
      "lon": 2.2945,
      "h": 300.5
    },
    "quaternion": {
      "x": 0.0,
      "y": 0.0,
      "z": 0.7071,
      "w": 0.7071
    }
  },
  "Things@navigationLink": "Locations(5)/Things",
  "HistoricalLocations@navigationLink": "Locations(5)/HistoricalLocations"
}

Listing 6 — Example of a Location entity using OGC GeoPose.

7.5.  HistoricalLocation

A Thing’s HistoricalLocation entity set provides the times of the current (i.e., last known) and previous locations of the Thing. It can be used to model the path observed by a moving Thing. An example of the use of HistoricalLocation is:

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. Another use case is to track the Location of a Thing, when a permanent network connection is not available. If the Location of a Thing is changed at a later time, when a network connection is available again, then the auto-generated Time of the HistoricalLocation entity would not reflect the time when the Thing was actually at the set Location, but only the time at which the change was sent to the server. To resolve this, the Location of a Thing can also be changed by adding a HistoricalLocation. If the time of a manually created HistoricalLocation is later than the time of all existing HistoricalLocations, then the Location of the Thing is updated to the Location of this manually created HistoricalLocation.

Table 8 — Attributes of a HistoricalLocation entity

Table 9 — Direct relation between a HistoricalLocation entity and other entity types

{
  "@context": "https://example.org/v2.0/$metadata#HistoricalLocations/$entity",
  "@id": "HistoricalLocations(1)",
  "id": 1,
  "time": "2020-03-20T16:35:23.383586Z",
  "Thing@navigationLink": "HistoricalLocations(1)/Thing",
  "Locations@navigationLink": "HistoricalLocations(1)/Locations"
}

Listing 7 — Example of a HistoricalLocation entity returned by a HTTP end point.

7.6.  Datastream

A Datastream groups a collection of Observations into a time series measuring the same ObservedProperties by the same Sensor for the same Thing and the same FeatureOfInterest. Examples of Datastreams could be:

A Datastream can both have a Proximate- and an UltimateFeatureOfInterest. The UltimateFeatureOfInterest is the broadest domain feature that the Observations in the Datastream can be said to represent. The ProximateFeatureOfInterest is a more precise specification of a part of the Ultimate Feature. An individual Observation can also have a ProximateFeatureOfInterest, which would, in most cases, be a sample with a limited set of Observations taken on it.

For example, in water quality the Ultimate FeatureOfInterest could be a river, while the ProximateFeatureOfInterest is a section of the river, or a specific point in the river where measurements or samples are taken. If samples are taken, these samples are the ProximateFeatureOfInterest linked directly to the Observations taken on them.

Table 10 — Attributes of a Datastream entity

TM_Period is by default encoded as a complex type with a start (mandatory) and end (mandatory) attributes of type TM_Instant.

Table 11 — Direct relation between a Datastream entity and other entity types

The resultType defines the result types for specialized single and multi observations based on the JSON encoding of the SWE Common Data Model (OGC 08-094r1 and OGC 17-011r2, or, once released: OGC 24-014). The result of an Observation may be a single simple number or String, or it may contain a complex JSON structure holding multiple values for multiple ObservedProperties. The exact definition for this result structure, and which unit of measurement and which ObservedProperty pertains to each value in the result structure is exactly described by this resultType Object.

The resultType contains references to the ObservedProperty or ObservedProperties of the Observations in the Datastream. When a change is made to the resultType, the server MUST ensure the ObservedProperties linked to the Datastream match the references used in the the definition attribute(s) of the resultType, and create or remove relations as needed. If the resultType contains references to non-existing ObservedProperties the request must be rejected with a Bad Request error. The values of the definition fields in the resultType must be valid entity-ids ( @id) of ObservedProperties. The structure of the resultType must not be changed once a Datastream has Observations, since the existing Observations would not fit the new structure.

In most cases each Observation holds a single numeric result value, measured by a single Sensor. In this case the resultType is of the SWE-Common class Quantity (though a number could also be a Count) and thus must have the fields type, definition, label, and uom.

{
  "name": "Oven temperature",
  "description": "This is a datastream measuring the air temperature in an oven.",
  "resultType": {
    "type": "Quantity",
    "label": "Temperature",
    "definition": "ObservedProperties(1)",
    "uom": { "code": "Cel", "label": "degree Celsius", "symbol": "°C" }
  }
}

Listing 8 — A Datastream example measuring a scalar Observation

{
  "result": 25.1,
  "phenomenonTime":  {
    "start": "2021-13-14T15:16:00Z"
  }
}

Listing 9 — An Observation for the Datastream defined in the example above

Another common type of result is a value from a key list. An example would be an Observation of the current weather as Fair or Overcast, or the geological dating of a rock sample to be Jurassic. In the latter case, the code space that defines the values could be the Sweet ontology. In this example the resultType is a Category and thus must have the fields type, definition, label, and codeSpace.

{
  "name": "Sample Dating",
  "description": "This is a datastream containing the geological datings of rock samples.",
  "resultType": {
    "type": "Category",
    "label": "Period",
    "definition": "ObservedProperties(2)",
    "codeSpace": "http://sweetontology.net/stateTimeGeologic/"
  }
}

Listing 10 — A Datastream example for Observations with category values from a predefined code space

{
  "result": "Jurassic",
  "phenomenonTime":  {
    "start": "2021-13-14T15:16:00Z"
  }
}

Listing 11 — An Observation for a Datastream defined in the example above

In some cases, a (composite) Sensor generates multiple values that should be kept together. This can be achieved with a DataRecord resultType. In the below example, a temperature and pressure value are stored as a pair, per Observation. The resultType has the SWE-Common class DataRecord, which is a composite class that contains sub-entries. The mandatory fields of a DataRecord are type and fields:

Since there are two distinct definition fields in the resultType, this Datastream must be linked to two ObservedProperties that match the two definitions.

{
  "name": "Temperature and Pressure",
  "description": "This is a datastream containing temperature and pressure measurement sets.",
  "resultType": {
    "type": "DataRecord",
    "fields": [
      {
        "name": "temp",
        "type": "Quantity",
        "label": "Air Temperature",
        "definition": "ObservedProperties(1)",
        "uom": { "code": "Cel", "label": "degree Celsius", "symbol": "°C"  }
      },
      {
        "name": "press",
        "type": "Quantity",
        "label": "Air Pressure",
        "definition": "ObservedProperties(3)",
        "uom": { "code": "mbar", "label": "Millibar", "symbol": "mBar"  }
      }
    ]
  }
}

Listing 12 — A Datastream example measuring multiple observedProperties

{
  "result": {
    "temp": 15,
    "press": 1024
  },
  "phenomenonTime": {
    "start": "2021-13-14T15:16:00Z"
  }
}

Listing 13 — An Observation for a Datastream defined in the example above

7.7.  Sensor

A Sensor is an entity that observes a property or phenomenon with the goal of producing an estimate of the value of the property. A Sensor may represent a piece of hardware, but a Sensor may also be a human or an algorithm implemented in sofware.

Table 12 — Attributes of a Sensor entity

Table 13 — Direct relation between a Sensor entity and other entity types

Table 14 — Non-exhaustive list of code values used for identifying types for the encodingType of the Sensor entity

The Sensor encodingType allows clients to know how to interpret the metadata 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. Lastly, some sensor datasheets are HTML documents rather than PDFs. Other encodingTypes are permitted (e.g., text/plain). Note that the metadata property may contain either a URL to metadata content (e.g., an https://, ftp://, etc. link to a PDF, SensorML, or HTML document) or the metadata content itself (in the case of text/plain or other encodingTypes that can be represented as valid JSON). It is up to clients to perform string parsing necessary to properly handle metadata content.

{
  "@context": "https://example.org/v2.0/$metadata#Sensors/$entity",
  "@id": "Sensors(1)",
  "id": 1,
  "name": "TMP36",
  "description": "TMP36 - Analog Temperature sensor",
  "encodingType": "application/pdf",
  "metadata": "http://example.org/TMP35_36_37.pdf",
  "Datastreams@navigationLink": "Sensors(1)/Datastreams"
}

Listing 14 — Example of a Sensor entity returned by a HTTP end point.

7.8.  ObservedProperty

An ObservedProperty is a property of a Feature that is being observed by a Sensor, such as temperature, humidity, population count or colour. It should be uniquely identified by its definition, which should point to an external vocabulary by means of a URL, URI or DID.

Table 15 — Attributes of an ObservedProperty entity

Table 16 — Direct relation between an ObservedProperty entity and other entity types

{
  "@context": "https://example.org/v2.0/$metadata#ObservedProperties/$entity",
  "@id": "ObservedProperties(1)",
  "id": 1,
  "name": "DewPoint Temperature",
  "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.",
  "definition": "http://dbpedia.org/page/Dew_point",
  "Datastreams@navigationLink": "ObservedProperties(1)/Datastreams"
}

Listing 15 — Example of an ObservedProperty entity returned by a HTTP end point.

7.9.  Observation

An Observation provides a value for an ObservedProperty of a Feature, as observed by a Sensor. This value can be of any type, as described by the resultType of the Datastream that Observation is associated with.

Table 17 — Attributes of an Observation entity

TM_Object is by default encoded as a complex type with a start (mandatory) and end (optional) attributes of type TM_Instant. This means it can either describe a time instant, when only the start is present, or a time interval with both stand and end are present.

TM_Period is by default encoded as a complex type with a start (mandatory) and end (mandatory) attributes of type TM_Instant. This means it always describes a time interval with fixed starting and ending instants.

Table 18 — Direct relation between an Observation entity and other entity types

An Observation can be directly linked to a Feature, through the relation ProximateFeatureOfInterest. Features linked to an Observation in this way are generally samples, either real, physical ones, like water samples taken from a river, or transient ones, to fix the place that a moving Thing happended to be in, when it made a measurement.

In case the Feature is a domain object, like a river, a building, or a plot of land, the Feature is indirectly linked to the Observation through the UltimateFeatureOfInterest or ProximateFeatureOfInterest relations on the Datastream. It is also possible for all relations to exist, in which case the ProximateFeatureOfInterest of the Observation is a sample of the ProximateFeatureOfInterest of the Datastream, which is, in turn, a part of the UltimateFeatureOfInterest.

A third case is possible, when the target of the observation is (a sub-part of) the Thing itself. For instance, when the Observation is on the battery-level of a drone. In this case neither the ProximateFeatureOfInterest on the Observation, nor the ProximateFeatureOfInterest or UltimateFeatureOfInterest relations on the Datastream need to be set.

{
  "@context": "https://example.org/v2.0/$metadata#Observations/$entity",
  "@id": "Observations(1)",
  "id": 1,
  "phenomenonTime": {
    "start": "2017-11-12T13:00:00Z",
    "end": "2017-11-12T14:00:00Z"
  },
  "resultTime": "2017-11-12T14:00:00Z",
  "result": 12.5,
  "Datastream@navigationLink": "Observations(1)/Datastream",
  "ProximateFeatureOfInterest@navigationLink": "Observations(1)/ProximateFeatureOfInterest"
}

Listing 16 — Example of an Observation entity returned by a HTTP end point.

7.10.  Feature

An Observation assigns a value to a property of a subject by applying an ObservingProcedure. The subject is the Feature that can take the role of ProximateFeatureOfInterest or UltimateFeatureOfInterest of the Observation [ OGC 20-082r4 and ISO 19156:2023]. In cases where estimating the value of a property of interest is not possible directly, a proxy feature MAY be used. Such an application typically requires taking a sample of the UltimateFeatureOfInterest such that this sample, the ProximateFeatureOfInterest, represents an approximation of the domain feature.

Some examples of features are:

Table 19 — Attributes of a Feature entity

Table 20 — Direct relation between a Feature entity and other entity types

{
  "@context": "https://example.org/v2.0/$metadata#Features/$entity",
  "@id": "Features(1)",
  "id": 1,
  "name": "0113700020130227",
  "description": "Water Sample from LA NOYE À DOMMARTIN (80) taken on 2013-02-27 at 10:20:00",
  "encodingType": "application/geo+json",
  "feature": {
    "type": "Point",
    "coordinates": [
      2.38961955,
      49.800951554
    ]
  },
  "FeatureType@navigationLink": "Features(1)/FeatureType",
  "Datastreams@navigationLink": "Features(1)/Datastreams",
  "Observations@navigationLink": "Features(1)/Observations"
}

Listing 17 — Example of a Feature entity using a GeoJSON Geometry.

{
  "@context": "https://example.org/v2.0/$metadata#Features/$entity",
  "@id": "Features(2)",
  "id": 2,
  "name": "City Center Park",
  "description": "A public park located in the heart of the city",
  "encodingType": "application/wkt",
  "feature": "POLYGON((30 10, 40 40, 20 40, 10 20, 30 10))",
  "FeatureType@navigationLink": "Features(2)/FeatureType",
  "Datastreams@navigationLink": "Features(2)/Datastreams",
  "Observations@navigationLink": "Features(2)/Observations"
}

Listing 18 — Example of a Feature entity using WKT Geometry.

7.11.  FeatureType

The type or types of each Feature can be specified using the FeatureType class. The definition attribute of the FeatureType should point to an external registry or code list, that defines the Type.

Table 21 — Attributes of a FeatureType entity

Table 22 — Direct relation between a FeatureType entity and other entity types

{
  "@context": "https://example.org/v2.0/$metadata#FeatureType/$entity",
  "@id": "FeatureType(1)",
  "id": 1,
  "name": "Water Sample",
  "description": "A Sample taken from a river, lake or sea",
  "definition": "https://example.org/water_sample",
  "Features@navigationLink": "FeatureType(1)/Features"
}

Listing 19 — Example of a FeatureType entity.

7.12.  Integrity

For the core model the integrity constraints are summarised in Table 23.

Table 23 — Integrity constraints when changing data

8.1.  Introduction

This section describes the abstract OData API. The abstract OData API can be implemented using various protocols, like HTTP or MQTT version 5.

8.2.  OData Entity Model

Every OData service utilizes an entity model which MAY be distributed over several schemas. The service describes this model through a metadata document accessible by a simple HTTP GET request to the <serviceRoot>/$metadata path. This chapter describes an overview of the types of entities in the metadata document that will be used to describe the SensorThings API data model and its data model extensions. The entities listed below are also used to describe the REST and MQTT bindings of the SensorThings API service.

This section is base on:

The entity model consists of the following elements:

Each Entity has a primary key that is composed of one or more of the declared attributes of the entity type. Which attributes of the Entity Type make up the primary key of the Entity Type is specified in the service metadata document. For the data models specified in this document the primary key is always the field id, though the data type of the field may vary between services. In most cases the primary key field will be server generated at the time an Entity is created, but a service may allow for client-specified primary key fields.

URLs in documents may be absolute or relative. Relative URLs are relative to the context URL in the document, or if there is no context url, relative to the request URL. See https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_RelativeURLs.

Table 24 — Common control annotations

8.3.  Type Mappings

8.4.  OData Common Schema Definition Language

The data model is specified in the metadata document that can be retrieved from the context url. It is described in a machine-readable way using the OData Common Schema Definition Language. See https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html

An example CSDL document describing a service hosting a SensorThings API v2.0 core data model can be found in Annex C. A shortened example with comments can be found in Annex B.

8.5.  Encoding rules for constants

Encoding rules for constants in resource paths and query options are listed in Table 28

Table 28 — Encoding rules for constants in requests

8.6.  URL Patterns

http://example.org/v2.0/Datastreams(5)/Observations?$orderby=ID&$top=10
__________________/____/__________________________/___________________/
         |          |                |                      |
   service root   version      resource path           query options

base/topic/v2.0/Datastreams(5)/Observations?$orderby=ID&$top=10
__________/____/__________________________/___________________/
    |     version            |                      |
root Topic             resource path           query options

<Service Root>/v2.0/Datastreams

<Service Root>/v2.0/Datastreams(4)

<Service Root>/v2.0/Datastreams('xz42df')

<Service Root>/v2.0/Datastreams(4)/name

<Service Root>/v2.0/Datastreams(4)/Thing/name

<Service Root>/v2.0/Datastreams(4)/name/$value

<Service Root>/v2.0/Datastreams(4)/Thing/name/$value

<Service Root>/v2.0/Datastreams(4)/Thing

<Service Root>/v2.0/Observations(42)/Datastream/Thing

<Service Root>/v2.0/Datastreams(4)/Observations

<Service Root>/v2.0/Datastreams(4)/Thing/Locations

<Service Root>/v2.0/Datastreams(4)/Thing/$ref

<Service Root>/v2.0/Datastreams(4)/Observations/$ref

<Service Root>/v2.0/Datastreams(4)/Observations(1)/$ref

<Service Root>/v2.0/Datastreams(4)/Observations(5321)

8.7.  Request Types

To the resources paths above the following request types can be sent:

8.8.  Additional request parameters

Besides the query options, there are a few other request parameters that are used to convey information between client and server.

8.9.  Requesting Data

{
  "@context": "<Service Root>/v2.0/$metadata",
  "value": [
    {
      "name": "Things",
      "url": "<Service Root>/v2.0/Things"
    },
    {
      "name": "Locations",
      "url": "<Service Root>/v2.0/Locations"
    },
    {
      "name": "Datastreams",
      "url": "<Service Root>/v2.0/Datastreams"
    },
    {
      "name": "Sensors",
      "url": "<Service Root>/v2.0/Sensors"
    },
    {
      "name": "Observations",
      "url": "<Service Root>/v2.0/Observations"
    },
    {
      "name": "ObservedProperties",
      "url": "<Service Root>/v2.0/ObservedProperties"
    },
    {
      "name": "Features",
      "url": "<Service Root>/v2.0/Features"
    },
    {
      "name": "FeatureTypes",
      "url": "<Service Root>/v2.0/FeatureTypes"
    }
  ],
  "serverSettings": {
    "conformance": [
        "http://www.opengis.net/spec/sensorthings/2.0/req/datamodel",
        "http://www.opengis.net/spec/sensorthings/2.0/req/resource-path/resource-path-to-entities",
        "http://www.opengis.net/spec/sensorthings/2.0/req/request-data",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-update-delete/create-entity",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-update-delete/link-to-existing-entities",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-update-delete/deep-insert",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-update-delete/deep-insert-status-code",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-update-delete/update-entity",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-update-delete/delete-entity",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-update-delete/historical-location-auto-creation",
        "http://www.opengis.net/spec/sensorthings/2.0/req/create-observations-via-mqtt/observations-creation",
        "http://www.opengis.net/spec/sensorthings/2.0/req/receive-updates-via-mqtt/receive-updates"
    ],
    "functions": [
      "any","cast","ceiling","concat","endswith","floor","floor","geo.distance","geo.intersects","geo.length",
      "indexof","interval","length","now","round","round","startswith","st_contains","st_crosses","st_disjoint",
      "st_equals","st_intersects","st_overlaps","st_relate","st_touches","st_within","substring","substringof",
      "tolower","toupper","trim"
    ],
    "http://www.opengis.net/spec/sensorthings/2.0/req/bindings/mqtt": {
      "endpoints": [
        "mqtt://server.example.com:1833",
        "ws://server.example.com/sensorThings",
      ]
    }
  }
}

{
  "@context": "<Service Root>/v2.0/$metadata#ObservedProperties",
  "@count": 36,
  "value": [
    {
      "@id": "<Service Root>/v2.0/ObservedProperties(1)",
      "id": 1,
      "name": "SO2",
      "definition": "http://dd.eionet.europa.eu/vocabulary/aq/pollutant/1",
      "description": "SO2",
      "properties": {
        "eionetId": 1,
        "owner": "http://dd.eionet.europa.eu",
        "recommendedUnit": "µg/m3"
      },
      "Datastreams@navigationLink": "<Service Root>/v2.0/ObservedProperties(1)/Datastreams"
    },
    {
      "@id": "<Service Root>/v2.0/ObservedProperties(2)",
      "id": 2,
      "name": "PM2.5",
      "definition": "http://dd.eionet.europa.eu/vocabulary/aq/pollutant/6001",
      "description": "PM2.5",
      "properties": {
        "eionetId": 6001,
        "owner": "http://dd.eionet.europa.eu",
        "recommendedUnit": "µg/m3"
      },
      "Datastreams@navigationLink": "<Service Root>/v2.0/ObservedProperties(2)/Datastreams"
    }, { … }, { … }, { … }
  ],
  "@nextLink": "<Service Root>/v2.0/ObservedProperties?$top=5&$skip=5"

}

{
  "@context": "<Service Root>/v2.0/$metadata#Things/$entity",
  "@id": "<Service Root>/v2.0/Things(1)",
  "id": 1,
  "name": "Oven",
  "description": "This thing is an oven.",
  "properties": {
    "owner": "Noah Liang",
    "color": "Black"
  },
  "HistoricalLocations@navigationLink": "<Service Root>/v2.0/Things(1)/HistoricalLocations",
  "Locations@navigationLink": "<Service Root>/v2.0/Things(1)/Locations",
  "Datastreams@navigationLink": "<Service Root>/v2.0/Things(1)/Datastreams"
}

{
  "@context": "<Service Root>/v2.0/$metadata#Edm.String",
  "value": "Oven"
}

Oven

{
  "@context": "<Service Root>/v2.0/$metadata#$ref",
  "@id": "<Service Root>/v2.0/Things(42)"
}

{
  "@context": "http://host/service/$metadata#Collection($ref)",
  "value": [
    { "@id": "<Service Root>/v2.0/Datastreams(10643)" },
    { "@id": "<Service Root>/v2.0/Datastreams(10759)" }
  ]
}

{
  "@context": "<Service Root>/v2.0/$metadata#$ref",
  "@id": "<Service Root>/v2.0/Locations(1)"
}

v2.0/Things?$select=id,name

v2.0/Things?$select=distinct:properties/type

{
    "value": [
        { "properties": { "type": "waterBody" } },
        { "properties": { "type": "station" } },
        { "properties": { "type": "aquifer" } }
    ]
}

v2.0/Things?$expand=Datastreams($expand=ObservedProperty)

v2.0/Datastreams?$expand=Observations($select=result,phenomenonTime;$orderby=phenomenonTime desc;$top=1),ObservedProperty

v2.0/Things?$top=5

v2.0/Observations?$top=5&$orderby=phenomenonTime desc

v2.0/Things?$skip=5

v2.0/Observations?$skip=2&$top=2&$orderby=resultTime

v2.0/Observations?$orderby=result

v2.0/Observations?$orderby=Datastreams/id desc, phenomenonTime

v2.0/Datastreams(42)/Observations?$filter=result gt 5

v2.0/Locations?$filter=st_within(location, geography'POLYGON ((30 10, 10 20, 20 40, 40 40, 30 10))')

v2.0/Observations?$filter=validTime/start lt 2012-12-03T07:16:23Z

v2.0/Observations?$filter=Datastream/name eq 'Temperature'

v2.0/Observations?$filter=Datastream/Thing/name eq 'House 1'

Datastreams?$filter=Observations/any(o: o/result gt properties/threshold and o/phenomenonTime gt 2024-01-01T00:00:00Z)

Things?$filter=Datastreams/any(d1: d1/ObservedProperty/name eq 'NO2') and Datastreams/any(d2: d2/ObservedProperty/name eq 'O3')

8.10.  Modifying Data

{
  "name": "Oven temperature",
  "description": "This is a datastream measuring the air temperature in an oven.",
  "resultType": {
    "type": "Quantity",
    "label": "Oven temperature",
    "definition": "ObservedProperties(1)",
    "uom": { "code": "Cel", "label": "degree Celsius", "symbol": "°C" }
  },
  "Sensor": {"@id": "Sensors(2)"}
}

{
  "description": "This an oven with a temperature datastream.",
  "name": "oven",
  "Locations": [
    {
      "name": "CCIT",
      "description": "Calgary Centre for Innovative Technologies",
      "encodingType": "application/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.",
      "resultType": {
        "type": "Quantity",
        "label": "Oven temperature",
        "definition": "ObservedProperties(1)",
        "uom": { "code": "Cel", "label": "degree Celsius", "symbol": "°C" }
      },
      "Sensor": {
        "name": "DS18B20",
        "description": "DS18B20 is an air temperature sensor…",
        "encodingType": "application/pdf",
        "metadata": "http://datasheets.maxim-ic.com/en/ds/DS18B20.pdf"
      }
    }
  ]
}

{
  "name": "My Updated Oven"
}

{
  "name": "My Updated Oven"
}

{
  "name": "My Updated Oven",
  "Locations": [
    {
      "name": "New Location of my Oven",
      "description": "It fits much better here",
      "encodingType": "application/geo+json",
      "location": {
        "type": "Point",
        "coordinates": [-114.061,51.051]
      }
    },
    {
      "@id": "Locations(1)"
    }
  ]
}

[
  { "op": "test", "path": "/properties/status", "value": "inactive" },
  { "op": "replace", "path": "/properties/status", "value": "active" }
]

replace http://host/service/Datastreams(1)/UltimateFeatureOfInterest/$ref
  {"id": "Feature(2)"}

delete http://host/service/Datastreams(1)/UltimateFeatureOfInterest/$ref

create http://host/service/Feature(1)/FeatureTypes/$ref
  {"id": "FeatureTypes(3)"}

replace http://host/service/Feature(1)/FeatureTypes/$ref
  {"value": [
    {"id": "FeatureTypes(1)"},
    {"id": "FeatureTypes(2)"}
  ]}

delete http://host/service/Feature(1)/FeatureTypes(2)/$ref
delete http://host/service/Feature(1)/FeatureTypes/$ref?$id=../../FeatureTypes(2)

delete http://host/service/Feature(1)/FeatureTypes/$ref

8.11.  Authentication & Authorization

9.1.  Introduction

The HTTP Bindings specify how access the SensorThings API using the HTTP protocol.

9.2.  HTTP Binding Advertisement

To help a client find the HTTP endpoints of a SensorThings service, the endpoints of the service are documented in the serverSettings object of the service documents of all request-response bindings, as described in Clause 8.9.2.2. If the service supports the HTTP interface binding, then the serverSettings object SHALL contain a attribute of type Object, with the name

http://www.opengis.net/spec/sensorthings/2.0/req/binding/http

This Object SHALL contain a attribute named endpoints of type Array. The JSON Array endpoints SHALL hold a list of URL Schemes that can be used to connect to the HTTP service

9.3.  Request / Response

The actions that can be executed on resources, as defined in the Clause 8 are mapped to HTTP Methods as defined in table Table 31.

Table 31 — Mapping of abstract request types to HTTP Methods.

Content for Create, Update, Replace or Execute requests is passed in the body of the HTTP request.

Request parameters (such as prefer, content-type and location) are passed as Headers.

HTTP HEAD and OPTIONS requests are treated as normal GET requests, but don’t return data. If a GET request with the same URL and headers would return an error, the HEAD or OPTION requests also returns this error.

9.4.  Cross Origin Resource Sharing

9.5.  Authentication & Authorization

10.1.  Introduction

The MQTT Bindings specify how to access the SensorThings API using the MQTT 5.0 protocol (OASIS mqtt-v5.0). This binding consists of three parts that can be implemented independently: Clause 10.3, Clause 10.4 and Clause 10.5.

10.2.  MQTT Binding Advertisement

To help a client find the MQTT endpoints of a SensorThings service, the endpoints of the service are documented in the serverSettings object of the service documents of all request-response bindings, as described in Clause 8.9.2.2. If the service supports any MQTT interface bindings, then the serverSettings object SHALL contain a attribute of type Object, with the name

http://www.opengis.net/spec/sensorthings/2.0/req/binding/mqtt

This Object SHALL contain a attribute named endpoints of type Array. The JSON Array endpoints SHALL hold a list of URL Schemes that can be used to connect to the MQTT service

10.3.  Request / Response

MQTT 5.0 formalises a request-response pattern over the MQTT protocol (OASIS mqtt-v5.0, Section 4.10) that allows the use of the REST API over the MQTT protocol. See Figure 3 for a basic overview of the request-response pattern in MQTT 5.0.

MQTT 5.0 also defines User Properties (OASIS mqtt-v5.0, Section 3.3.2.3.7) that can be used to pass application-defined key-value pairs with a published message.

Figure 3 — MQTT 5 request-response pattern

Using the basic request-response pattern, and the User Properties of MQTT 5.0, the abstract API defined in Clause 8 can be implemented over the MQTT protocol.

To minimise the size of the returned payload, by default the json format is used with metadata=none (Clause 8.9.3.11.2).

Topic: v2.0/$request
ResponseTopic: responses/userxyz
CorrelationData: 42
User Properties:
  url: v2.0
  type: read
  accept: */*
Payload: <empty>

Listing 75 — Message requesting the service document

Topic: responses/userxyz
CorrelationData: 42
User Properties:
  content-type: application/json;charset=UTF-8
Payload: <the service document>

Listing 76 — Response message to the previous read request

Topic: v2.0/$request
ResponseTopic: responses/userxyz
CorrelationData: 43
User Properties:
  url: v2.0/Things?$top=1&$orderby=id
  type: read
  accept: */*
Payload: <empty>

Listing 77 — Message requesting the first thing, ordered by id

Topic: responses/userxyz
CorrelationData: 43
User Properties:
  content-type: application/json;charset=UTF-8
Payload:
{
  "value": [
    {
      "id": 1,
      "name": "Oven",
      "description": "This thing is an oven.",
      "properties": {
        "owner": "Ulrike Schmidt",
        "color": "Black"
      }
    }
  ],
  "@nextLink": "v2.0/Things?$top=1&$skip=1&$orderby=id"
}

Listing 78 — Response message to the previous read request

Topic: v2.0/$request
ResponseTopic: responses/userxyz
User Properties:
  url: v2.0/Things
  type: create
  content-type: application/json
  accept: */*
Payload:
{
  "id": 1,
  "name": "Oven",
  "description": "This thing is an oven.",
  "properties": {
    "owner": "Ulrike Schmidt",
    "color": "Black"
  }
}

Listing 79 — Message creating a new thing

Topic: responses/userxyz
User Properties:
  content-type: application/json;charset=UTF-8
  location: v2.0/Things(1)
Payload: <empty>

Listing 80 — Response message to the previous create request

10.4.  Publish / Subscribe

v2.0/Datastreams(4)/Observations

User Properties:
  type: create
Payload:
{
  "id": 123,
  "result": 45,
  "phenonmenonTime": "2015-02-05T17:00:00Z"
}

v2.0/Datastreams(4)/Observations?$select=phenomenonTime,result

v2.0/Datastreams(4)/Observations?$expand=ProximateFeatureOfInterest

10.5.  Simple Create

Since simple clients, like sensors, may not be capable of handling the full MQTT request/reponse pattern, the simple-create pattern allows for a simpler way to create entities. Entities can be created by sending a publish request to the topic of an EntitySet ( Clause 8.6.4, Clause 8.6.9), without service root, and without a preceding slash (/), followed by /create.

Topic: v2.0/Datastreams(4)/Observations/create
Payload:
{
  "result": 42,
  "phenomenonTime": {
    "start": "2017-11-12T13:00:00Z"
  }
}

Listing 84 — Publish message used to create an Observation in Datastream 4.

More advanced clients are adviced to use the MQTT Request/Response pattern to create entities, since it allows the server to return a success or failure response on entity creation.

10.6.  Authentication & Authorization

11.1.  General

The OGC API — Common Bindings specify how to combine the SensorThings API with other OGC APIs.

11.2.  Landing Page

11.3.  Authentication & Authorization