Aspects

Whenever a Property represents a numeric, scalar value that the result of a measurent of some kind (e.g., using a sensor) and has a well-defined physical unit which is known at modeling time, use the Measurement Characteristic. If the value is numeric and has a physical unit but is not the result of a measurement (e.g., when it is calculated from other values), use the Quantifiable Characteristic.

See the following example that uses Measurement — usage of Quantifiable is analogous.

See section Units for information about the valid values for the samm-c:unit attribute.

The following example shows how a Property is defined that uses the Single Entity Characteristic to specify an Entity as its dataType.

There are four basic predefined types of Collections: Collection, List, Set and Sorted Set. The Collection definitions are shared and are available globally. They determine whether a specific collection is ordered or not and whether a specific collection may contain duplicates or not. In some cases the data type is also set in the shared Collection Characteristic.

These shared Collection Characteristics may not be changed in an Aspect Model, hence it is not allowed to create a subclass of the Collection Characteristic in an Aspect Model. To create a Collection Characteristic for a specific domain, the user should instantiate one of the Collection classes and define the data type or the element Characteristic for the Collection. In this example, the Characteristic resulting from the combination of Code, Length Constraint and Encoding Constraint is not defined inline in the Property, but defined standalone.

Example with the samm-c:elementCharacteristic attribute:

Describes a Property which may have a value from a predefined list of values. Also see Enumeration.

Example with literal xsd:string values:

Example with literal xsd:integer values. Note that for xsd:integer, Turtle’s numeric literal syntax can be used:

Example with literal xsd:int values:

Example with literal xsd:date values:

Example with complex values:

Declaring an Enumeration with a complex value is usally done in order to add a description to the actual value, e.g., the state in the example below, which provides information regarding the meaning of the value. This description only exists in the Aspect Model and is not part of the payload provided by an Aspect at runtime. In order to define that a Property of an Entity is not part of the runtime data, the samm:notInPayload attribute is used.

As described in State Characteristic, State inherits from Enumeration and extends it with the default value attribute.

Example:

The TimeSeries Characteristic is a special kind of Collection. A Time Series is defined as a list of tuples of values with their respective specific point in time when they where recorded. This is, the Time Series is represented by a list of key/value pairs where the key is the time-stamp denoting when the value was recorded and the value is the recorded value. In order to describe these semantics the shared TimeSeries Characteristic is used. This is a subclass of the SortedSet Characteristic and defines that the dataType must be a subclass of the TimeSeriesEntity.

The TimeSeriesEntity is declared as an Abstract Entity. It defines the timestamp Property with the Timestamp Characteristic, which describes values containing timestamps conforming to xsd:dateTime, a date and time with or without time zone. It also defines value as an Abstract Property, i.e., a Property without a Characteristic.

To create a Time Series for a specific domain, the user should instantiate the TimeSeries Collection Characteristic and set the dataType to an Entity which extends the Abstract TimeSeries Entity in order to define the semantics for the value Property in the context of the specific domain. Please see the Declaring Abstract Entities section for information on how to extend an Abstract Entity.

Example:

Describes a Property whose value can have one of two possible types (a disjoint union). This Characteristic is special since it does not directly define a data type. The data type is defined in the two Characteristics which define the left and right value of the disjoint union. Also see Either and Payload mappings to JSON for Characteristics.

Example:

Structured Values are intended to be used for Properties when all of the following conditions are met:

One of the main use cases is complex identifiers that encode context information such as provenance information, version numbers, locations codes and so on. It is unreasonable to split such a value up into separate Properties, because it complicates working with corresponding data. For example, such values could appear in payloads, databases or documents and would have to be converted back and forth, often times manually. On the other hand, properly describing the value and the parts it comprises can be difficult, especially in a machine-readable way.

Therefore, the Structured Value Characteristic can be used to describe the deconstruction of a value into its parts and linking each part to a separate Property definition.

The following table gives some simple examples to demonstrate the basic applicability of the Characteristic, and after that a complete concrete example is given.

The following code shows the Aspect Model for the first example from the table. Note that when writing the deconstructionRule, backslashes (\) need to be escaped in order to produce valid RDF/Turtle syntax, i.e. write \\ instead of \.

The Reference Characteristic is intended to be used for scenarios where a reference to a concept external to the Aspect Model is required, but the value of the reference (i.e., the identifier of the linked concept) is not known at modeling time yet. Other than that, it is conceptually similar to a samm:see reference.

As explained in the section Declaring Quantifiables and Measurements, some values only make sense when they also have a unit assigned to them. This unit definition is in many cases fixed at design time, does not change thereafter and therefore at runtime (in the JSON payload for example), only the actual value is transported.
There may be scenarios, however, where this permanent fixation on a specific unit might not be sufficient because the unit can only be determined dynamically at runtime, or is a kind of configuration parameter which must be set when the system is being deployed/starting up. In cases like this, a UnitReference characteristic instance can be used to include a dynamic reference to the desired unit from the Unit catalog and this information is then always included in the payload. The runtime payload refers to the unit using its samm:curie, i.e., the unit’s URN’s element name prefixed with unit:.

For example an Aspect with the following model:

can produce a JSON payload that could look something like this:

Declaring that an Entity extends another Entity is done using the samm:extends attribute in the Entity declaration.

Example:

The extending Entities :Student and :Teacher contain the Properties declared in the extended Entity :Person as well as the Properties in their own declarations.

The effective Property names, i.e. the payload name when samm:payloadName is used, or the name of the Property, must be unique across the entire Entity inheritance chain. Otherwise the corresponding runtime payload is ambiguous.

When one of the attributes samm:payloadName, samm:optional or samm:notInPayload is used on a specific property usage, its value is also inherited by the extending Entities. Using the example of samm:payloadName, we could modify the above example to enforce the alternative naming for the surname property in the generated payloads and this change would apply to the Person Entity (directly) and both Student and Teacher Entities (via inheritance):

In contrast to Entities, Abstract Entities cannot directly be instantiated. A Characteristic class may have a type samm:entity or samm:AbstractEntity. But a Characteristic instance cannot have a type samm:AbstractEntity. If there is an instance created from a Characteristic that uses an Abstract Entity as its type, this Characteristic instance’s dataType must be a sub-Entity of the Abstract Entity. The main use case for Abstract Entities is to share Properties across multiple Entities. This can be achieved through inheritance: Abstract Entities can extend other Entities and Abstract Entities and can themselves be extended in a manner not dissimilar to how abstract classes are used in many programming languages.

In the following example, both SteeringWheel and Seat extend the Abstract Entity VehicleComponent. Both inherit the typeNumber and the manufacturer Properties:

When an Abstract Entity needs to be defined with a certain Property, but the modeler using the Abstract Entity (i.e., extending it) should be able to decide the Property’s Characteristic, the Property can be declared a samm:AbstractProperty. An Abstract Property is similar to a Property, with two differences: firstly, it has no samm:Characteristic attribute and secondly, it must only be used in Abstract Entities. Consider the following example of two-dimensional vector which is declared as an Abstract Entity using two Abstract Properties for its x and y values, leaving for the user to decide which Characteristic and hence which data type should be used:

The usage of the Abstract Properties allows to specify the contract (a two-dimensional vector must have x and y Properties), but allows flexible reuse. Only when it is used, one must decide on the Characteristic and with it its effective datatype such as xsd:int, xsd:float or xsd:decimal.

To use the Vec2 Abstract Entity, the Characteristic to bind to the Abstract Properties is declared and then used as follows:

Note that an Abstract Entity can have both samm:Property​s and samm:AbstractProperty​s (both are listed in samm:properties). The properties list of an Entity that extends the Abstract Entity must specify the Characteristic to use for each of the Abstract Properties (and only those).