Understand Aspect Models to reveal semantics of data

The namespace is compiled for example in this line:

Identifiers of elements that are defined on the model level — i.e., Aspects, Properties, Entities, Operations, Characteristics, Events, Units — must use the following schema:

After the declaration of namespaces, the first section of the Aspect Model is the following description:

You can see that every identifier contains a colon: .
If the part before the : is samm, then this term is defined by the Semantic Aspect Meta Model (SAMM), and if it is empty, then this term is defined by the Aspect Model’s author.

The declaration of a property can also contain human-readable names and descriptions, and always makes a statement about the property’s Characteristic:

The Semantic Aspect Meta Model (SAMM) provides a number of built-in Characteristics such as samm-c:Boolean that is used above.

A Characteristic is different from a data type in that it can provide much richer context information, which is sometimes called domain semantics. For example, the Characteristic can determine a value’s physical unit:

For the :speed property, an instance of the Characteristic samm-c:Measurement — called :Speed — is used with a data type of float. While the data type determines how the value is represented, the Characteristic explains the concept the property refers to. As Aspect Models are semantic models, properties never directly refer to data types, but instead always to Characteristics, which in turn specify a data type.

Note that Aspect Models make use of a rich type system adapted from the XML Schema definition, which is why you will see the xsd prefix in many types. In contrast to the types used in JSON (string, number, boolean, object), you can for example distinguish between different numeric types such as float, double, int and long. There are also built-in types for common uses such as dateTime.

Furthermore, the :Speed Characteristic has a reference to the physical unit unit:kilometrePerHour. The Semantic Aspect Meta Model has a built-in catalog of about 1,800 units, based on established open standards. By including this information in the model, the meaning of the value is communicated unambiguously. It can also be used as the basis for value conversions or to enrich UIs.

To express nested structures, SAMM has the concept of Entities.

The position geo coordinate property consists of latitude, longitude, and an optional altitude. The Entity that encapsulates these three properties is introduced, together with a Characteristic that makes use of this Entity in the position property:

The definitions of the properties latitude, longitude, and altitude are not shown here, but they too are defined using samm:Property declarations. All three use a Characteristic that specifies a numeric type as data type; latitude and longitude use a Characteristic that specifies degrees as physical unit, while altitude uses the physical unit meter (above mean sea level).

In the model extract above you can also see how the samm:see attribute can be used to link to relevant external definitions, standards or documents. In this case, the attribute links to the W3C vocabulary for the World Geodetic System (WGS84) that defines in detail how the values of the geo coordinates are to be interpreted. This is not necessarily a URL intended for humans, but could also be any URI pointing to other machine-readable descriptions.

In an Aspect Model, there are different ways to specify which values are valid for a property:

For the speedLimitWarning property, there is a defined set of valid values, so it uses an Enumeration:

In section Consume an aspect we have seen how the JSON-RPC request for an operation call looks like. The operation and its corresponding semantics, such as its inputs and output are expressed in the corresponding Aspect Model. Consider the operation request and response for the temperatureInRange operation on the Temperature aspect:

In order to express this operation in the Temperature Aspect Model, the first step is to include the operation in the Aspect’s samm:operations. Note that the name of the operation is identical to the method called in the JSON-RPC.

The declaration of the operation itself uses samm:input and samm:output to point to Properties describing the respective input arguments and result value. The Aspect’s :temperature Property is reused here as the semantic description of the operation’s result, i.e., a temperature value in degrees celsius.

Note that the operation in the Aspect Model does not formally describe or implement what the operation call does, this needs to be implemented in the aspect.

The second example for operations, the operation setSpeedLevel in the OperatingSpeed aspect, demonstrates how enumeration can be used to define the valid values for inputs and outputs of an operation.

Typically, aspects are implemented as REST APIs using the HTTP protocol. However, aspects can also expose MQTT endpoints. See also Aspect data transports.

For use cases where sharing data via MQTT is needed, you can also add events to Aspect Models.

To keep this getting started guide digestible, we will not demonstrate the usage of MQTT endpoints. However, to learn how to model Events, have a look at the Temperature.ttl Aspect Model. It contains such an Event element.

Note that the details of such events — for example, which data (MQTT package) gets sent at which occurrence or time via an MQTT topic — are to be decided when implementing the event. The SAMM specification does not prescribe any defaults or rules. Thus, events can be adapted to your own implementation needs.