FROST-Server Documentation

Live documentation for the development version.

Custom Entity Linking

In many use-cases the existing links between entity types that the SensorThings API offers are not sufficient to describe the data. A generic way to link between various objects, internal and external is needed. Since the SensorThings API v1.x does not have special fields for links, the links will have to go in the properties field that each entity type has.

To be functional, internal links need:

Furthermore, they need to be formatted in a way that the server can easily detect the links. This makes it possible for the server to generate absolute URLs for these links, and allow searching and expanding of the links.

The SensorThings API uses a special @ notation for internal properties:

We could introduce something similar. When linking to another Entity, add an entry to the properties map like:

"<linkName>.<TargetEntityType>": <Target Entity Id>
"": 45
"": 16
"": "123e4567-e89b-12d3-a456-426655440000"

The server can operate on these, for instance by adding a navigationLink when returning the properties:

Get V1.0/Things(1)
    "Properties" : {
        "building.Thing@Iot.Id": 45,
        "building.Thing@Iot.Navigationlink": ""

When updating or creating entities, if there is a property of the type <linkName>.<TargetEntityType> then the property <linkName>.<TargetEntityType> and all other properties starting with <linkName>.<TargetEntityType>@ will be removed by the server before storing the properties.

Custom entity links to not have to be placed at the root of the properties map, though a server implementation may limit how deep these links may appear.

Expand support

The server can support $expand on these entity links, by including the full target entity next to the link:

GET v1.0/Things(1)?$expand=properties/building.Thing
    "properties" : {
        "": 45,
        "building.Thing": { <expanded Thing> }

As mentioned above, when updating or creating an entity, these server-generated entries will be ignored/removed.

Filter supprt

The server can support $filter on these entity links just like on normal navigation links:

GET v1.0/Things(1)?$filter=properties/building.Thing/name eq 'Building 1'

The behaviour described above can be exposed by a server without the server knowing in advance which links exist. When formatting the results of a request, the server can iterate through the properties, and generate any required navigationLinks and expands. To enable efficient filtering on these properties, the server will need to know which links (may) exist before fetching data from the database. Pre-registering the existing links on the server will also allow the server to announce the existence of those links, and their semantics, to clients. It also makes it possible for the server to generate back-links from the entities that are linked to, but the details for that still need to be specified.

Pre-registered links are announced in the serverSettings part of the server root document.

  "serverSettings": {
    "conformance": [
      "<our register requirement class uri>"
    "<our main requirement class uri>": {
      "registeredLinks": {
        "<sourceType>/properties/<linkName>": {
          "targetType": "<targetType>",
          "description": "A human readable description of the link"

By specifying the full path, links do not have to be top-level entries in the properties object, but can be nested deeper. For example:

"Thing/properties/links/building": {
  "targetType": "Thing",
  "description": "The building a room is part of."

Open issues

Some things are not specified yet and are in need of discussion:

Conformance Class

If a server implements this specification fully, it must register the following URL in the SensorThings (v1.1 and up) index document:

If the server only implements parts, it may register any of the following URLs: