Aspects

General

Notes

  • As mentioned in the Introduction, Aspect Models are described in RDF Turtle [turtle]. The aspect specification will therefore assume basic familiarity with Turtle.

  • For the definition of the different Model elements please refer to the Meta Model Elements.

Naming rules

The naming of Model Elements follows the naming Java naming conventions for classes, properties and methods.

  • The names of Aspects, Entities, Events, Constraints and Characteristics follow the naming conventions for Java classes, i.e. UpperCamelCase.

  • The names of Properties, Operations and Units follow the naming conventions of Java methods, i.e. lowerCamelCase.

RDF/Turtle formatting rules

  • Each Aspect Model is defined in a separate TTL (Turtle) file.

  • The Turtle file containing an Aspect Model must have the same name as the Aspect.

  • Aspect Model files must be UTF-8 encoded and should not contain a byte order mark.

  • There should be one empty line between model element definitions.

  • Indentation should be done with three spaces.

  • There should be a space before every separating semicolon.

  • There should be padding spaces inside RDF lists and anonymous nodes (i.e. inside brackets and square brackets)

Attributes that all model elements have

Every model element (Aspects, Properties, Characteristics, Entities, Operations) has the following attributes:

Attributes Description Required

samm:preferredName

Human readable name in a specific language. This attribute may be defined multiple times for different languages but only once for a specific language. There should be at least one preferredName defined with an "en" language tag.

samm:description

Human readable description in a specific language. This attribute may be defined multiple times for different languages but only once for a specific language. There should be at least one description defined with an "en" language tag.

samm:see

A reference to a related element in an external taxonomy, ontology or other standards document. The datatype is xsd:anyURI. This attribute may be defined multiple times.

Although both samm:preferredName and samm:description should be set at least once in every model element, in the following examples we will mostly leave them out to improve readability.

Declaring model elements

Using Namespaces

An Aspect Model file should start with the SAMM prefix definitions. The empty namespace ":" should be used as local namespace, i.e. the versioned namespace in which the Aspect and its elements are defined. Other customer or domain specific namespaces can be defined additionally. However, the samm-* namespaces are reserved for the meta model. Third party locations can be referred via other namespaces (e.g., "xsd:"). See Namespaces and Versions for more details on the topic.

@prefix : <urn:samm:com.mycompany.myapplication:1.0.0#> .
@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#> .
@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#> .
@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.1.0#> .
@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.1.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

Declaring Namespaces

A Namespace defines the scope in which other model elements, including Aspects, are declared. Explicit declarations of Namespaces are not required, they exist implicitly by declaring model elements in them. However, the explicit declaration of a Namespace is useful if you want to assign human-readable names or descriptions to it.

@prefix : urn:samm:com.mycompany.myapplication:1.0.0# .
@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#> .

# The colon denotes the namespace as defined in the first @prefix declaration above.
: a samm:Namespace ;
   samm:preferredName "..."@en ;
   samm:description "..."@en .

Declaring Aspects

An Aspect is defined by marking its identifier with a samm:Aspect and additional attributes. Note that the a is just a syntactic shortcut for rdf:type. In addition to the general attributes, every Aspect Model element has the following attributes:

Attributes Description Required

samm:properties

The list of Properties of this Aspect. Leaving out this attribute completely is equivalent to having it present with an empty list as value.

samm:operations

The list of Operations of this Aspect. Leaving out this attribute completely is equivalent to having it present with an empty list as value.

samm:events

The list of Events of this Aspect.

  • Aspects follow the naming conventions for Java classes, i.e. UpperCamelCase.

  • Each Aspect Model must be defined in its own file. The file name must be the same as the Aspect’s name.

  • The hierarchical namespace part in the Aspect’s URN can be freely chosen.

The definition of an Aspect should therefore have the following structure in TTL syntax; note though that unused namespaces can be left out:

@prefix : <urn:samm:com.mycompany.myapplication:1.0.0#> .
@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#> .
@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#> .
@prefix samm-e: <urn:samm:org.eclipse.esmf.samm:entity:2.1.0#> .
@prefix unit: <urn:samm:org.eclipse.esmf.samm:unit:2.1.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

:MyAspect a samm:Aspect ;
   samm:preferredName "My Aspect"@en ;
   samm:preferredName "Mein Aspekt"@de ;
   samm:description "This Aspect is an example."@en ;
   samm:description "Dieser Aspekt ist ein Beispiel."@de ;
   samm:properties ( :myProperty :anotherProperty ) ;
   # In this example, there are no operations or events.
   samm:operations ( ) ;
   samm:events ( ) .

Declaring Properties

In addition to the attributes that all model elements have, Properties have the following attributes:

Attributes Description Required

samm:characteristic

The Characteristic describing this Property.

samm:exampleValue

An exemplary value the Property can take on that helps to understand the intended meaning of the property better. This can only be set for Properties with scalar data types (e.g., xsd:string or xsd:float, but not Entities). The data type of the samm:exampleValue must be convertible to the effective data type of the Property’s Characteristic. For example, if the Characteristic’s samm:dataType is xsd:int, xsd:short is also a valid type for the samm:exampleValue. Refer to section Implicit Conversions for more details.

Example:

:materialNumber a samm:Property ;
   samm:preferredName "Material number"@en ;
   samm:description "A material number"@en ;
   samm:exampleValue "ABC123456-000" ;
   samm:characteristic samm-c:Text .

Declaring Characteristics

The attributes for Characteristics are described in detail in section Characteristics.

The dataType attribute may be omitted when creating a subclass of a Characteristic. The dataType attribute must be set when creating an instance of a Characteristic, except when the dataType attribute has been set in the class or one of the super-classes. When the dataType has been set in a superclass, the dataType may be set to a subclass of the dataType from one of the Characteristic superclasses. This allows the definition of generic Characteristics such as Collections, where all the semantics are fixed, except for the data type. For a Collection for example it is possible to define whether the collection is sorted or not and this definition can be then reused with different data types to define different collections.

Example:

:MachineState a samm-c:State ;
   samm:dataType xsd:string ;
   samm-c:defaultValue "STANDBY" ;
   samm-c:values ( "RUNNING" "STANDBY" "OFF" ) .

Declaring Quantifiables and Measurements

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.

:ToolTemperature a samm-c:Measurement ;
   samm:dataType xsd:float ;
   samm-c:unit unit:degreeCelsius .

:drillHeadTemperature a samm:Property ;
   samm:characteristic :ToolTemperature .

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

Declaring Single Entity

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

:AccelerationVector a samm:Entity ;
   samm:properties ( :x :y :z ) .

# Definition of Properties x, y and z for the Entity here
# ...

:acceleration a samm:Property ;
   samm:characteristic [
      a samm-c:SingleEntity ;
      samm:dataType :AccelerationVector
   ] .

Declaring Collections

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 a scalar data type:

:NumberList a samm-c:List ;
   samm:dataType xsd:float .

Example with a custom Entity as data type:

:MyEntity a samm:Entity ;
   samm:properties ( ) ;
   # ...
   .

:MyEntityList a samm-c:List ;
   samm:dataType :MyEntity .
The data type for the elements of a Collection can either be defined in the usual manner using the samm:dataType attribute (see the examples above) or by defining a Characteristic for the Collection elements using the samm-c:elementCharacteristic attribute, see the example below. It is recommended to explicitly create a Characteristic for the Collection elements instead of only defining the data type, since it allows to completely express the semantics of the elements.

Example with the samm-c:elementCharacteristic attribute:

:numbers a samm:Property ;
   samm:characteristic :NumberList .

:NumberList a samm-c:List ;
   samm-c:elementCharacteristic [
      a samm-c:Trait ;
      samm-c:baseCharacteristic :Number ;
      samm-c:constraint [
         a samm-c:RangeConstraint ;
         samm:description "Limits the range of the individual numbers in the list from 5 to 10."@en ;
         samm-c:minValue "5"^^xsd:nonNegativeInteger ;
         samm-c:maxValue "10"^^xsd:nonNegativeInteger ;
      ] ;
   ] .

:Number a samm:Characteristic ;
   samm:dataType xsd:nonNegativeInteger .

Declaring Enumerations

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

Example with literal xsd:string values:

:Status a samm-c:Enumeration ;
   samm:dataType xsd:string ;
   samm-c:values ( "Complete" "In Progress" "Created" ) .

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

:PrimesBelowTwenty a samm-c:Enumeration ;
   samm:dataType xsd:integer ;
   samm-c:values ( 2 3 5 7 11 13 17 19 ) .

Example with literal xsd:int values:

:ValidOffsets a samm-c:Enumeration ;
   samm:dataType xsd:int ;
   samm-c:values ( "-1"^^xsd:int "1"^^xsd:int ) .

Example with literal xsd:date values:

:MaintenanceDates a samm-c:Enumeration ;
   samm:dataType xsd:date ;
   samm-c:values ( "2010-01-01"^^xsd:date "2012-05-07"^^xsd:date "2018-03-08"^^xsd:date ) .

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.

samm:notInPayload cannot be used in Abstract Entities, but the setting for a specific property is inherited when Entities are extended.
:Results a samm-c:Enumeration ;
   samm:dataType :Result ;
   samm-c:values ( :Success :Failed ) .

:Result a samm:Entity ;
   samm:properties ( :status [ samm:property :description; samm:notInPayload "true"^^xsd:boolean ] ) .

:Success a :Result ;
   :status "SUCCESS" ;
   :description "The process completed successfully." .

:Failed a :Result ;
   :status "FAILURE" ;
   :description "The process did not complete successfully." .
If the Property is part of the runtime data (like status in the example), it is directly referenced. Writing samm:notInPayload false is not allowed.

Declaring State

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

Example:

:MachineState a samm-c:State ;
   samm:dataType xsd:string ;
   samm-c:defaultValue "STANDBY" ;
   samm-c:values ( "RUNNING" "STANDBY" "OFF" ) .

Declaring Time Series

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:

:MachineStateTimeSeries a samm-c:TimeSeries ;
   samm:dataType :MachineStateTimeSeriesEntity .

:MachineStateTimeSeriesEntity a samm:Entity ;
   samm:extends samm-e:TimeSeriesEntity ;
   samm:properties ( :machineState ) .

:machineState a samm:Property ;
   samm:characteristic :MachineState .

:MachineState a samm-c:State ;
   samm:dataType xsd:string ;
   samm-c:defaultValue "STANDBY" ;
   samm-c:values ( "RUNNING" "STANDBY" "OFF" ) .
An Aspect should only have one Collection at root level. When modeling an Aspect with two or more collections at root level which contain related data, consider creating the model so that the related data is explicitly linked and contained in a single Collection. When modeling an Aspect with two or more collections at root level which contain unrelated data, consider creating separate Aspects each containing a single Collection.

Declaring Either

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:

:speedProperty a samm:Property ;
  samm:characteristic :Result .

:Result a samm-c:Either ;
  samm-c:left :ErrorMessage ;
  samm-c:right :SpeedValue .

:ErrorMessage a samm-c:SingleEntity ;
  samm:dataType :ErrorEntity .

:SpeedValue a samm-c:Quantifiable ;
  samm:dataType xsd:integer .

:ErrorEntity a samm:Entity ;
   samm:properties ( :errorCode :errorDescription ) .

Declaring Structured Value

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

  • The value has a scalar, string-like value space

  • The value has a well-known structure consisting of different, separate parts

  • The parts can and should be described in more detail

  • The Property should not be decomposed/deconstructed into an Entity with separate Properties for each part

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.

Name Example Value Deconstruction Rule Elements

ISO 8601 date

"2019-09-27"^^xsd:date

(\d{4})-(\d{2})-(\d{2})

( :year "-" :month "-" :day )

Email Address

"user4711@example.com"

()@([\w\.-]\.\w{2,4})

( :username "@" :host )

Hex-encoded color

"0xAC03BE"

0x([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})([0-9A-Fa-f]{2})

( "0x" :red :green :blue )

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 \.

:StructuredValueTest a samm:Aspect ;
   samm:properties ( :date ) ;
   samm:operations () .

:date a samm:Property ;
   samm:exampleValue "2019-09-27"^^xsd:date ;
   samm:characteristic :StructuredDate .

:StructuredDate a samm-c:StructuredValue ;
   samm:dataType xsd:date ;
   samm-c:deconstructionRule "(\\d{4})-(\\d{2})-(\\d{2})" ;
   samm-c:elements ( :year "-" :month "-" :day ) .

:year a samm:Property ;
   samm:characteristic :Year .

:month a samm:Property ;
   samm:characteristic :Month .

:day a samm:Property ;
   samm:characteristic :Day .

:Year a samm:Characteristic ;
   samm:dataType xsd:int .

:Month a samm:Characteristic ;
   samm:dataType xsd:int .

:Day a samm:Characteristic ;
   samm:dataType xsd:int .
Technically, samm-c:elements would not be required just to parse corresponding payload; the regular expression given in the samm-c:deconstructionRule would be sufficient. However, the elements fields serves two purposes: Firstly, it concisely describes how the meaning of the deconstruction rule corresponds with the named fields; secondly, it is used for validation: When a samm:exampleValue is given (like in the example), the Aspect Model validator can automatically check if it can be deconstructed using the deconstruction rule and reconstructed using the elements, i.e., that the deconstruction rule actually does what the model author intended.

Declaring Reference

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.

:TestProperty a samm:Property ;
    samm:characteristic samm-c:Reference .

Using Unit 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:

:ValueWithDynamicUnit a samm:Aspect ;
  samm:properties ( :value :unit ) ;
  samm:operations ( ) .

:value a samm:Property ;
   samm:exampleValue "2.25"^^xsd:float ;
   samm:characteristic :FloatValue .

:FloatValue a samm:Characteristic ;
   samm:dataType xsd:float .

:unit a samm:Property ;
   samm:characteristic samm-c:UnitReference .

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

{
  "value" : 2.25,
  "unit" : "unit:hectopascal"
}

Declaring Constraints and Traits

Consider the numbers Property that uses an instance of the List Characteristic:

:numbers a samm:Property ;
   samm:characteristic :NumberList .

:NumberList a samm-c:List ;
   samm:dataType xsd:integer .

To add a Length Constraint to the list, replace the use of the Characteristic with a new Trait instance. Set the original Characteristic as the Trait’s samm-c:baseCharacteristic and add the required Constraint as a samm-c:constraint to the Trait:

:numbers a samm:Property ;
   samm:characteristic [
     a samm-c:Trait ;
     samm-c:baseCharacteristic :NumberList ;
     samm-c:constraint [
       a samm-c:LengthConstraint ;
       samm:description "Limits the number list to 10 elements"@en ;
       samm-c:maxValue "10"^^xsd:nonNegativeInteger ;
     ]
   ]  .

:NumberList a samm-c:List ;
   samm:dataType xsd:integer .

Another more complex example is given below. The Property someIdentifier is defined that uses a Code instance using a dataType of xsd:string, combined with two Constraints: an Encoding Constraint that restricts the value space to US-ASCII and a Length Constraint that limits the string to 80 characters.

:someIdentifier a samm:Property ;
   samm:preferredName "Some identifier"@en ;
   samm:description "An ASCII-encoded identifier with a maximum length of 80 characters"@en ;
   samm:characteristic :CodeWithLengthAndAscii .

:CodeWithLengthAndAscii a samm-c:Trait ;
   samm:description "A string code limited to 80 ASCII characters"@en ;
   samm-c:baseCharacteristic [
      a samm-c:Code ;
      samm:description "Denotes some kind of code with a string datatype"@en ;
      samm:dataType xsd:string ;
   ] ;
   samm-c:constraint [
      a samm-c:EncodingConstraint ;
      samm:value samm:US-ASCII ;
      samm:description "Limits the character encoding to US-ASCII"@en ;
   ] ;
   samm-c:constraint [
      a samm-c:LengthConstraint ;
      samm:description "Limits the length to 80 characters"@en ;
      samm-c:maxValue "80"^^xsd:nonNegativeInteger ;
   ] .

An example showing the Regular Expression Constraint is given below:

:timeStampsInJanuary a samm:Property ;
   samm:preferredName "Timestamps in January"@en ;
   samm:description "Contains only timestamps in January of any year"@en ;
   samm:characteristic [
      a samm-c:Trait ;
      samm-c:baseCharacteristic samm-c:Timestamp ;
      samm-c:constraint [
         a samm-c:RegularExpressionConstraint ;
         samm:value "\\d{4}-01-\\d\\dT.*" ;
      ] ;
   ] .
When writing the samm:value, backslashes (\) need to be escaped in order to produce valid RDF/Turtle syntax, i.e. write \\ instead of \.

Declaring Entities

Entities have the following attributes:

Attributes Description Required

samm:properties

The list of Properties which make up the Entity. Leaving out this attribute completely is equivalent to having it present with an empty list as value.

samm:extends

The Entity which is extended by this Entity

Example:

:Error a samm:Entity ;
   samm:properties ( :errorCode :severity ) .

Extending Entities

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

Example:

:Student a samm:Entity ;
    samm:extends :Person ;
    samm:properties ( :studentNumber ) .

:Teacher a samm:Entity ;
    samm:extends :Person ;
    samm:properties ( :employeeNumber ) .

:Person a samm:Entity ;
    samm:properties ( :name :surname ) .

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):

:Person a samm:Entity ;
    samm:properties ( :name [ samm:property :surname ; samm:payloadName "familyName" ] ) .

Declaring Abstract Entities

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:

:VehicleComponent a samm:AbstractEntity ;
    samm:properties ( :typeNumber :manufacturer ) .

:Steeringwheel a samm:Entity ;
   samm:extends :VehicleComponent ;
   samm:properties ( :isMultifunction  ) .

:Seat a samm:Entity ;
   samm:extends :VehicleComponent ;
   samm:properties ( :material ) .

Abstract Entities with Abstract 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:

:Vec2 a samm:AbstractEntity ;
   samm:description "A two-dimensional vector"@en ;
   samm:properties ( :x :y ) .

:x a samm:AbstractProperty ;
   samm:description "The x part of the vector"@en .

:y a samm:AbstractProperty ;
   samm:description "The y part of the vector"@en .

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:

:IntegerNumber a samm:Characteristic ;
   samm:dataType xsd:integer .

:IntVec2 a samm:Entity ;
   samm:extends :Vec2 ;
   samm:properties (
     [ samm:extends :x ; samm:characteristic :IntegerNumber ]
     [ samm:extends :y ; samm:characteristic :IntegerNumber ]
   ) .

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).

Declaring Operations

Operations have the following attributes:

Attributes Description Required

samm:input

A list of references to Properties that describe the input to the operation. The attribute must be present, but the list may be empty.

samm:output

A single reference to a Property that describes the output of the operation.

Example:

:toggle a samm:Operation ;
   samm:preferredName "Toggle"@en ;
   samm:description "Switches the device on or off"@en ;
   samm:input ( :toggleArgument ) ;
   samm:output :toggleResult .

:toggleArgument a samm:Property ;
   samm:preferredName "Toggle argument"@en ;
   samm:description "The argument for the toggling operation"@en ;
   samm:characteristic :ToggleValues .

:ToggleValues a samm-c:Enumeration ;
   samm:preferredName "Toggle values"@en ;
   samm:description "The possible input values for the toggle operation"@en ;
   samm:dataType xsd:string ;
   samm-c:values ( "on" "off" ) .

:toggleResult a samm:Property ;
   samm:preferredName "Toggle result"@en ;
   samm:description "The result of the toggle operation"@en ;
   samm:characteristic :ToggleResult .

:ToggleResult a samm-c:Enumeration ;
   samm:preferredName "Toggle result"@en ;
   samm:description "The possible results of the toggle operation"@en ;
   samm:dataType xsd:string ;
   samm-c:values ( "ok" "denied" "unknown" ) .

Declaring Events

Events have the following attributes:

Attributes Description Required

samm:parameters

The parameters that describe the Event, given as a list of Properties.

Example:

:temperatureUpdated a samm:Event ;
   samm:parameters ( :drillHeadTemperature ) .

:ToolTemperature a samm-c:Measurement ;
   samm:dataType xsd:float ;
   samm-c:unit unit:degreeCelsius .

:drillHeadTemperature a samm:Property ;
   samm:characteristic :ToolTemperature .

Adding external references

The samm:see attribute can be used to add references to related elements in an external taxonomy, ontology or standards document to Aspect Model elements. Values for samm:see must be URIs. The meaning of the reference is informative and implies no semantics such as equality or subsumption in either direction.

In the following example, samm:see adds two references to external well-known vocabularies that have identifiers which are also valid URLs:

:lastName a samm:Property ;
    samm:see <https://schema.org/familyName> ;
    samm:see <http://xmlns.com/foaf/0.1/lastName> ;
    samm:characteristic samm-c:Text .

If an external model element should be referenced that has a unique identifier which is not a URI, but a well-known resolver exists, you can either use the resolver’s URL or a synthetic URN. For example, for the Digital Object Identifier (DOI, [DOI]) 10.1109/NetSys.2017.7903949, you can use as the value for samm:see either the URL https://doi.org/10.1109/NetSys.2017.7903949 or the URN urn:doi:10.1109/NetSys.2017.7903949.

If an external model element should be referenced that has a unique identifier which is not a URI and there is no well-known resolver, use a synthetic URN structure. One example are Object Identifiers as specified by ITU and ISO/IEC (OID) and the mapping to URNs in RFC 3061 [rfc3061], so for example, for the OID 1.3.6.1.4.1.1919.1.1.2, the corresponding samm:see value would be urn:oid:1.3.6.1.4.1.1919.1.1.2:

:filterName a samm:Property ;
    samm:see <urn:oid:1.3.6.1.4.1.1919.1.1.2> ;
    samm:characteristic samm-c:Text .

If an external element should be referenced that has no unique identifier, samm:see should not be used. In this case, refer to the external element in the current model element’s samm:description, for example:

:organizationPerson a samm:Property ;
    samm:description "See ISO/IEC 11179-6:2015(E), section 3.35"@en ;
    samm:characteristic samm-c:Text .

Optional Properties

When Properties are used in Aspects and Entities, they can be marked as optional (not possible for properties of Abstract Entities). This means that a Property’s usage is optional, not the Property itself, which would make reusing a Property more difficult. In the following example, the Property toggleStatus is mandatory and the Property errorMessage is marked as optional in the Aspect. Note how the samm:properties of the Aspect are defined, and how the definition for the toggleStatus Property itself does not differ from that of errorMessage.

@prefix : <urn:samm:com.mycompany.myapplication:1.0.0#> .
@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#> .
@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

:MyAspect a samm:Aspect ;
   samm:properties (
     :toggleStatus
     [ samm:property :errorMessage; samm:optional true ]
   ) ;
   samm:operations ( ) .

:toggleStatus a samm:Property ;
   samm:characteristic samm-c:Boolean .

:errorMessage a samm:Property ;
   samm:characteristic samm-c:Text .
If the Property’s use is optional, it is marked with samm:optional true (like errorMessage in the example). However, if its use is mandatory (like toggleStatus in the example), the Property is directly referenced. Writing samm:optional false is not allowed.
The setting of the samm:optional attribute for a specific property is inherited from parent Entity by the Entities extending it using the Entity extension mechanism (samm:extends).

Declaring Payload Names for Properties

When Properties are used in Aspects and Entities, a runtime payload name can be defined for the Property. This means that in the context of the Aspect or Entity (payload names cannot be defined for Abstract Entities) where the Property is used, the key of that Property in the runtime payload diverges from the Property’s local name. This allows for the separation of the semantic name of the Property and the corresponding key in the runtime payload. In the following example we define a Property errorMessage. In the Aspect it is defined that the corresponding key in the payload is error.

The value for the samm:payloadName attribute must be of type xsd:string.
@prefix : <urn:samm:com.mycompany.myapplication:1.0.0#> .
@prefix samm: <urn:samm:org.eclipse.esmf.samm:meta-model:2.1.0#> .
@prefix samm-c: <urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .


:MyAspect a samm:Aspect ;
   samm:properties (
     [ samm:property :errorMessage; samm:payloadName "error" ]
   ) ;
   samm:operations ( ) .

:errorMessage a samm:Property ;
   samm:characteristic samm-c:Text .
A Property must not be marked as not being included in the payload using samm:notInPayload true and have a payload name declared using samm:payloadName.
It is also useful to know that the payload name definition is inherited from parent Entity by its children when using the Entity extension mechanism (samm:extends).

Syntactic Shortcuts

When Properties use Characteristics classes, i.e. Characteristics that need to be instantiated, and the Characteristic instance is used in only one Property, the Characteristic may also be defined inline. Note that other Aspect Models can not refer to the Characteristic any more, because it no longer has an identifier.

Example: Regular definition of a Property

:numbers a samm:Property ;
   samm:characteristic :NumberList .

:NumberList a samm-c:List ;
   samm:dataType xsd:integer .

Example: Inlining the Characteristic definition

:numbers a samm:Property ;
   samm:characteristic [
      a samm-c:List;
      samm:dataType xsd:integer
   ] .

Localization of Aspect Models

To understand the possibilities for localization of the models and their implications it is important to understand the differences between the data types xsd:string and rdf:langString and/or their respective characteristic counterparts samm-c:Text and samm-c:MultiLanguageText.

To illustrate the differences between them and to give a typical example for localizable string that also needs to be included in the runtime payload, consider this model with a scalar text property:

:Test a samm:Aspect;
    samm:properties ( :text );
    samm:operations ( ).

:text a samm:Property ;
   samm:characteristic samm-c:Text .

The JSON payload for this model would then look like this:

{
  "text" : "My value"
}

Notice how the text is just a raw string, without any information about the language it is written in. When instead the text property is modeled as samm-c:MultiLanguageText (instead of samm-c:Text), the payload would change to include the information about the language and would look like this:

{
  "text" : {
    "en" : "Example multi language string"
  }
}

Another common use case is the use of localized texts strictly for documentation purposes. This means that the multilanguage strings can only be seen when modeling, they are not contained in the runtime payloads.

To illustrate how this is done, consider this example and imagine we would like the descriptions of the possible enumeration values to have localized version of the texts. This goal could be achieved by extending the model to look something like the following example:

:Results a samm-c:Enumeration ;
   samm:dataType :Result ;
   samm-c:values ( :Success :Failed ) .

:Result a samm:Entity ;
   samm:properties ( :status [ samm:property :description ; samm:notInPayload true ] ) .

:status a samm:Property ;
   samm:characteristic samm-c:Text .

:description a samm:Property ;
   samm:characteristic samm-c:MultiLanguageText .

:Success a :Result ;
   :status "SUCCESS" ;
   :description "Der Prozess war erfolgreich."@de .

:Failed a :Result ;
   :status "FAILURE" ;
   :description "Der Prozess ist fehlgeschlagen."@de .

Note the use of the attribute notInPayload in usage of the property, ensuring that the description property will never be included in the runtime payloads.

It is even possible to provide the description in multiple languages. To achieve this, we need to change the type of the description property to the Set Characteristic:

:description a samm:Property ;
  samm:characteristic [
    a samm-c:Set ;
    samm-c:elementCharacteristic samm-c:MultiLanguageText ;
  ] .

:Success a :Result ;
  :status "SUCCESS" ;
  :description (
    "Der Prozess war erfolgreich."@de
    "The process completed successfully."@en
  ) .

Notice how it is now possible to use the description property with multiple texts with different language tags (@de) to achieve the proper localization of the texts for linguistically diverse audiences.