Understand Aspect Models to reveal semantics of data

What is an Aspect Model?

In the previous section Consume an aspect you learned how to consume data from aspects. In this section we will take a look at how the semantics of the data provided by an aspect are described in Aspect Models.

In Bosch Semantic Stack, each aspect is associated with a so-called Aspect Model.

An Aspect Model is a formal (i.e., machine-readable) description of the structure and semantics of the data provided by an aspect. An Aspect Model serves two purposes:

  1. It captures the domain semantics of the part of the digital twin it describes. In this regard, it can be considered an ontology. Information that is usually available explicitly but informally (for example, in a data sheet of a machine) or implicitly (as tacit knowledge) is now made explicit and consistent in a broader scope than a single service or application.

  2. It serves as a contract between data provider and data consumer, similar to a schema description (cf. eg. JSON Schema or XML Schema). In this regard, it predefines exactly which data structures and values may appear in the runtime data. However, unlike a pure schema language, it does also contain the previously mentioned domain semantics, that are not contained in the runtime data but can partly be used for its validation.

Aspect Models can therefore be used for generating both comprehensive documentation of the modeled domain and software artifacts such as runtime data serializers and deserializers and corresponding entity models in various programming languages and frameworks.

Aspect Models in Bosch Semantic Stack are specified using the Semantic Aspect Meta Model (SAMM), a specification provided open source at https://eclipse-esmf.github.io/. They are written in a language called RDF/Turtle: The Resource Description Framework (RDF) is a World Wide Web Consortium (W3C) standard for the description of graph data and the Terse Triple Language (TTL - which reads almost like "turtle", hence the name) is its recommended human-readable syntax.

For working with Aspect Models, there is an ever-growing ecosystem of open source tools. Some of the most important ones are:

  • The Aspect Model Editor is a graphical editor for Aspect Models.

  • The Semantic Aspect Meta Model (SAMM) CLI - see xref:oss:samm-cli.adoc - is a command line interface that can be used to validate Aspect Models and generate artifacts from them, such as documentation and code.

  • The Java tooling is a collection of libraries for the Java language to load, validate, and serialize Aspect Models and generate artifacts from them.

How an aspect’s data corresponds to its Aspect Model

The data returned by the aspect from the Consume an aspect section looks like the following:

{
  "isMoving" : true,
  "position" : {
    "altitude" : 153.0,
    "latitude" : 9.1781,
    "longitude" : 48.80835
  },
  "speed" : 23.5,
  "speedLimitWarning" : "green"
}

The corresponding Aspect Model associated with this data is the file Movement.ttl.

As mentioned above, this model defines both: the structure of the data and its meaning.

Download the ttl file to your local machine or open it in a new browser tab, and let us take a look at this file step by step to see how it relates to the data in detail.

Namespace, model elements, model description

The namespace is compiled for example in this line:

@prefix : <urn:samm:org.eclipse.esmf.examples.movement:1.0.0#> .

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

urn:samm:<namespace>:<version>#<element-name>

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

:Movement a samm:Aspect ;
   samm:preferredName "movement"@en ;
   samm:description "Aspect for movement information"@en ;
   samm:properties ( :isMoving :position :speed :speedLimitWarning ) ;
   samm:operations ( ) ;
   samm:events ( ) .

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 first few lines declare the aspect with its name and human-readable description.

  • The samm:properties line states that this aspect has four properties.

  • The empty brackets for operations and events indicate that there are no operations or events.

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

Part of the data (JSON)

"isMoving" : true

Corresponding part of the Aspect Model

:isMoving a samm:Property ;
   samm:preferredName "is moving"@en ;
   samm:description "Flag indicating whether the asset is currently moving"@en ;
   samm:characteristic samm-c:Boolean .

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

Giving semantics a name: Characteristics

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:

Part of the data (JSON)

"speed" : 23.5

Corresponding part of the Aspect Model

:speed a samm:Property ;
   samm:preferredName "speed"@en ;
   samm:description "speed of vehicle"@en ;
   samm:characteristic :Speed .

:Speed a samm-c:Measurement ;
   samm:preferredName "speed"@en ;
   samm:description "Scalar representation of speed of an object in kilometers per hour."@en ;
   samm:dataType xsd:float ;
   samm-c:unit unit:kilometrePerHour .

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.

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.

Nested structures in the data

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:

Part of the data (JSON)

"position" : {
  "altitude" : 153.0,
  "latitude" : 9.1781,
  "longitude" : 48.80835
}

Corresponding part of the Aspect Model

:position a samm:Property ;
   samm:preferredName "position"@en ;
   samm:description "Indicates a position"@en ;
   samm:characteristic :SpatialPositionCharacteristic .

:SpatialPositionCharacteristic a samm-c:SingleEntity ;
   samm:preferredName "spatial position"@en ;
   samm:description "A single geo coordinate with optional altitude"@en ;
   samm:dataType :SpatialPosition .

:SpatialPosition a samm:Entity ;
   samm:preferredName "spatial position"@en ;
   samm:description "Represents latitude, longitude and altitude information in the WGS84 geodetic reference datum"@en ;
   samm:see <https://www.w3.org/2003/01/geo/> ;
   samm:properties (
      :latitude
      :longitude
      [ samm:property :altitude; samm:optional true ]
   ) .

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.

Which values are valid?

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

  • The used data type limits the value range.
    For example, using xsd:short (which represents 16-Bit unsigned integers) limits a numeric value to the range -32768…+32767.

  • The Trait Characteristic is used to add Constraints, such as specific numeric ranges, regular expressions or length limits.

  • Using the Enumeration Characteristic allows to predefine a set of permitted values.

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

Part of the data (JSON)

"speedLimitWarning" : "green"

Corresponding part of the Aspect Model

:speedLimitWarning a samm:Property ;
   samm:preferredName "speed limit warning"@en ;
   samm:description "Indicates if the speed limit is adhered to."@en ;
   samm:characteristic :TrafficLight .

:TrafficLight a samm-c:Enumeration ;
   samm:preferredName "warning level"@en ;
   samm:description "Represents if speed of position change is within specification (green), within tolerance (yellow), or outside specification (red)."@en ;
   samm:dataType xsd:string ;
   samm-c:values ( "green" "yellow" "red" ) .

Modeling operations

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:

Operation request

{
  "jsonrpc": "2.0",
  "method": "temperatureInTimeRange",
  "params": {
    "start": "2023-01-01T04:20:00.00000+2:00",
    "end": "2023-01-01T08:00:00.00000+2:00"
  },
  "id": 1
}

Operation response

{
  "jsonrpc": "2.0",
  "result": 13,
  "id": 1
}

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

:Temperature a samm:Aspect ;
   samm:preferredName "Temperature"@en ;
   samm:description "Provides a single temperature measurement"@en ;
   samm:properties ( :temperature ) ;
   samm:operations ( :temperatureInTimeRange ) ;
   samm:events ( :TemperatureUpdate ) .

The declaration of the operation itself uses bamm:input and bamm: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.

:temperatureInTimeRange a samm:Operation ;
   samm:preferredName "temperature in time range"@en ;
   samm:description "The mean temperate in the given time range"@en ;
   samm:input ( :start :end ) ;
   samm:output :temperature .

:start a samm:Property ;
   samm:preferredName "start"@en ;
   samm:description "The start of a time range"@en ;
   samm:characteristic :PointInTime .

:end a samm:Property ;
   samm:preferredName "end"@en ;
   samm:description "The end of a time range"@en ;
   samm:characteristic :PointInTime .

:PointInTime a samm:Characteristic ;
   samm:preferredName "Point in time"@en ;
   samm:description "A given point in time"@en ;
   samm:dataType xsd:dateTimeStamp .

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.

Modeling events

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.

:TemperatureUpdate a samm:Event ;
   samm:preferredName "Temperature Update"@en ;
   samm:description "Provides updated temperature values"@en ;
   samm:parameters ( :temperature ) .

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.

How to make best use of an Aspect Model?

The previous section has shown how the Aspect Model corresponds to the runtime data. We have seen the basics of how an Aspect Model can capture the semantics of the domain. Regular development tools can be used to consume data from the aspect endpoint, but there are multiple ways to make an aspect truly useful:

  • The Aspect Model documents both: the contract between data provider and consumer and the domain semantics. Use it as documentation of this contract: You can either open the Aspect Model in the Aspect Model Editor or have HTML documentation generated from the model.

  • Make context information from human-readable documentation such as data sheets formally available in the model. Whoever needs to consume the data will have all necessary context directly available. Furthermore, this information is cleanly versioned and maintained in the Aspect Model Catalog.
    The Aspect Model can even be loaded by the data consumer to enrich raw data from the aspect with this context information; the open source tooling provides many helpful instruments for this.

  • Use the Aspect Model as the basis for the implementation of both: data consumer and aspect instance as the data source. + You can use Aspect Model tooling to generate API descriptions and source code; more on this in section Implement your Aspect Model as an API.