Best Practices

The following best practices, while not mandatory, are highly recommended for optimal performance and to mitigate potential issues, especially when working with Aspect Models at scale.

The name attribute

The name attribute is mandatory for all model elements.

Use camel-case capitalization, as detailed in the naming rules.

For optimal results, consider the following best practices:

In addition to that, there are also best practices for:

Camel case for acronyms

For every part of a name, also for acronyms, strictly apply camel-case capitalization as detailed in the naming rules.

For example:

DON’T DO

mainECU

mainEcu

plantID

plantId

documentURL

documentUrl

Create name attributes where each capital letter can be trusted to trigger the start of a new name part.

That way, for example, automated case conversion will produce meaningful names (e.g., when generating code based on an Aspect Model):

SAMM name Resulting name in generated code (automated case conversion)

documentURL

DOCUMENT_U_R_L

documentUrl

DOCUMENT_URL

Unmistakable abbreviations

Avoid abbreviations that are not sufficiently common. Seemingly obvious abbreviations in one context can be misunderstood in different contexts.

For example:

DON’T DO

temp

Abbreviation unclear; not recommended. (Could mean "temperature" or "temporary".)

Abbreviating “minimum” or “maximum” by min or max is common enough and, therefore, acceptable.

minTemperature
maxSpeed

Using unmistakable abbreviations also applies to Description texts.

No redundant prefix

Do not duplicate information.

Avoid prefixes that repeat a domain (the namespace) an Aspect Model belongs to.

DON’T DO

fooCount
fooId
fooXyz
etc.
 
Complete identifier of such a Property:
urn:samm:foo.myapplication:1.0.0#fooCount

count
id
xyz
etc.
 
Complete identifier of such a Property:
urn:samm:foo.myapplication:1.0.0#count
The complete identifier of a Property is the versioned namespace combined with the element’s name, for example, urn:samm:foo.myapplication:1.0.0#count. So, the foo context (namespace) is already part of count​'s identifier.

No redundant suffix

Do not duplicate information.

Avoid suffixes that repeat the SAMM model element type, such as Aspect, Property, etc.

DON’T DO

MovementAspect
 
Result in TTL file:
:MovementAspect a samm:Aspect ;

Movement
 
Result in TTL file:
:Movement a samm:Aspect ;
To distinguish between, for example, an Entity and a related Characteristic, it is acceptable to add corresponding suffixes.

Meaningful names (reduce technical debt)

Choose meaningful names for your model elements to foster reuseability and avoid technical debt.

That means:

  • Do not simply mirror Property names from data sources like API responses (e.g., JSON).

    • Might be convenient in the short term

    • But makes it difficult to understand and reuse the model in the future

  • Invest the time upfront to choose descriptive names that reflect the purpose and meaning of each element.

Meaningful names improve code readability and maintainability, whereas arbitrary names make understanding and modifying the model harder in the long run.

Regarding meaningfulness, see also the details given for the description attribute at Meaningful: do not just repeat the preferredName.

Payload names for Properties

An expressive Property name can be long.

If you consider a Property’s name too long for the runtime payload, add a payload name.

Do not rename Properties just for the sake of a short runtime payload.

If certain Characteristics are present in a "Collection Aspect"

An Aspect with exactly one Property on root level which holds a Collection Characteristic can be perceived as a "Collection Aspect". Data sets provided by such an Aspect may be very large. This also applies to other Characteristics, i.e., the List, Set, Sorted Set, and Time Series Characteristics.

For a "Collection Aspect", consider the following naming advice for the Property itself and for the corresponding Aspect.

Characteristic held by Property How to name the Property How to name the Aspect

Collection Characteristic

Name the Property items.

Put the Aspect’s name in plural.

List Characteristic

Name the Property items.

Put the Aspect’s name in plural.

Set Characteristic

Name the Property items.

Put the Aspect’s name in plural.

Sorted Set Characteristic

Name the Property items.

Put the Aspect’s name in plural.

Time Series Characteristic

Name the Property items.

Put the Aspect’s name in singular and add a History suffix to it.

The preferredName attribute

The preferredName attribute is available for all model elements.

For more information, refer to Attributes that all model elements have.

For optimal results, consider the following best practices:

In addition to that, there are also best practices for:

Precise and understandable

The preferredName attribute is meant to provide a human-readable name.

Choose a Preferred Name that is precise and easy to understand.

People might encounter the Preferred Name, for example:

  • As a user of an Aspect Model—​in documentation generated from the Aspect Model

  • As a user of a software solution—​in a user interface of an application that was built based on the Aspect Model

Separate words

Should you copy and paste an element’s name to use it as the preferredName, adapt it accordingly.

For example, if the name consists of more than one word, written in camel case, separate it into the respective words.

Examples of Preferred Names derived from the name attributes of the model elements
:plantId a samm:Property ;
   samm:preferredName "plant ID"@en ;

:machineTmperature a samm:Property ;
   samm:preferredName "machine temperature"@en ;

:euTaxonomyDisclosureStatement a samm:Property ;
   samm:preferredName "EU taxonomy disclosure statement"@en ;

:ttlFileName a samm:Property ;
   samm:preferredName "TTL file name"@en ;

No article

While an article and a noun can be combined, they do not automatically belong together.

Therefore, avoid articles in Preferred Names.

DON’T DO

the machine temperature
a machine temperature

machine temperature

Capitalization: as in dictionary

Apply dictionary-style wording.

That means:

  • Do not apply any artificial capitalization.

  • Put the words as they would be listed in a dictionary.

In English, capital letters are reserved for proper nouns.

A term such as "engine control unit":

  • Is not a proper noun. Therefore, following the dictionary, it is written in lowercase: engine control unit.

  • May have an acronym, such as "ECU" for engine control unit.
    If required in a Preferred Name, an acronym ("ECU") remains in capital letters: engine control unit (ECU).

For example:

DON’T DO

Engine Control Unit (ECU)
Engine control unit (ECU)

engine control unit (ECU)

plant Id
Plant ID
Plant Id

plant ID

ttl file name
TTL File Name

TTL file name

EU Taxonomy Disclosure Statement
EU Taxonomy disclosure statement

EU taxonomy disclosure statement

Machine Temperature
Machine temperature

machine temperature

Allow Duplicates
Allow duplicates

allow duplicates

Examples with proper nouns:

DON’T DO

Planned September Batch

planned September batch

Monday Delivery Report

Monday delivery report

For languages other than English, the same practice applies: put the words for the Preferred Name as they would be listed in a dictionary.

For example, in German:

DON’T DO

Maschinen-Temperatur
die Maschinentemperatur

Maschinentemperatur

Erlaube Duplikate

erlaube Duplikate

Rationale: By using words the same way they would be listed in a dictionary, the preferredName attribute is flexible to be used in further applications, for example:

  • To complete an orthographically correct sentence, e.g., in a pop-up message within a user interface.
    (The Preferred Name can be used as-is.)

  • To stand alone, e.g., to appear as a tooltip in a user interface.
    (The Preferred Name can be parsed towards the desired capitalization style—​sentence case or title case.)

Once a Preferred Name is artificially capitalized—​whether in sentence case or title case—​it can’t be reverted (parsed back) to its dictionary form. This is because the applied capitalization obscures proper nouns.

The description attribute

The description attribute is available for all model elements.

For more information, refer to Attributes that all model elements have.

For optimal results, consider the following best practices:

In addition to that, there are also best practices for:

Capitalization: start uppercase

A description consists of at least a few words forming a phrase or a sentence fragment.

Start with an uppercase letter.

For example:

DON’T DO

flag indicating whether the asset is currently moving

Flag indicating whether the asset is currently moving.

represents a single position in space with optional z coordinate

Represents a single position in space with optional z coordinate.

Signifies the Vertical Distance in Reference to a Historic Mean Sea Level as a Vertical Datum

Signifies the vertical distance in reference to a historic mean sea level as a vertical datum.

Punctuation: end with a period

End your description with a period (full stop).

Even though it is just a sentence fragment.

Example model element DON’T DO

Property houseNumber

Number of a building in a street 

Number of a building in a street.

Writing style: comprehensible, concise

Apply a neutral writing style that is easy to understand. This fosters the usability and reuseability of an Aspect Model.

Also, be concise. To get an idea, think of definitions in an IEC/ISO glossary.

Meaningful: do not just repeat the preferredName

Write a meaningful Description. It can consist of only a sentence fragment, or it may be longer—but do not just repeat the Preferred Name for the Description.

Example model element DON’T DO

Property productFamily

Product family.

Set of products sharing similar features.

Regarding meaningfulness, see also the details given for the name attribute at Meaningful names (reduce technical debt).

Unmistakable abbreviations

Use abbreviations sparingly.

Only use very common standard abbreviations; ensure they are not misleading. See also the details provided for the name attribute: Unmistakable abbreviations.

It is acceptable to use editorial abbreviations such as e.g. ("for example") or i.e. ("that is") or etc. ("and so forth").

No brand names

Where possible, avoid brand, product, or company names in Descriptions. This fosters reuseability of shared Aspect Models.

No "Entity", "Property", etc.

SAMM model element terms like Entity, Property, Aspect, etc. do not belong in the Description.

Descriptions must be understandable without knowledge of SAMM.

Rationale: An Aspect Model may be converted to a different output format or modeling language in which SAMM model elements are unknown. Users unfamiliar with SAMM might find the SAMM terminology confusing.

For example:

Example model element

DON’T

DO

Entity Identification

Entity with identification information of the product with part type information, local identifiers, other codes, and the data carrier.

Identification information about the product with part-type information, local identifiers, other codes, and the data carrier.
If you need to mention other Properties etc. in the Description, refer to them by their preferredName.

No "This <preferredName> …​"

Do not start the Description with "This <preferredName> …​" as this duplicates information.

It could even interfere with further usages of the Description, for example, when displayed together with the Preferred Name in a user interface.

Start the Description as if it was a sentence fragment that would complete a sentence like "This model element is a/the …​" or just "This model element …​".

For example:

Example model element DON’T DO

Property materialDemandId
 
Preferred Name: Material Demand ID

The Material Demand ID uniquely identifies the material demand within the business relationship between a customer and its supplier

Uniquely identifies the material demand within the business relationship between a customer and its supplier.

No "The …​"

Avoid starting the Description with an article (where possible).

Example model element DON’T DO

Property altitude

The elevation above sea level zero.

Elevation above sea level zero.

Triple quotes in TTL file

Use the TTL triple quotes operator to mark the Description as a section with line breaks.

This avoids having long Descriptions sitting on just one line. Description sections with line breaks are easier to grasp for human readers when skimming through TTL files.

See also: New sentence, new line.

Example: Use triple quotes
:TrafficLight a samm-c:Enumeration ;
   samm:preferredName "warning level"@en ;
   samm:description """
      Represents speed of position change.
      Within specification, it turns green.
      Within tolerance, it turns yellow.
      Outside specification, it turns red.
      """@en ;
   samm:dataType xsd:string ;
   samm-c:values ( "green" "yellow" "red" ) .

Indentation in TTL file

Indent the Description content given within the triple quotes. See also Triple quotes in TTL file.

Use the three-blank indentation of SAMM Turtle (TTL) files.

Example: Stick to SAMM’s three-blank indentation
:TrafficLight a samm-c:Enumeration ;
   samm:preferredName "warning level"@en ;
   samm:description """
      Represents speed of position change.
      Within specification, it turns green.
      Within tolerance, it turns yellow.
      Outside specification, it turns red.
      """@en ;
   samm:dataType xsd:string ;
   samm-c:values ( "green" "yellow" "red" ) .

New sentence, new line

Stick to the general best practice of starting every sentence on a new line.

With one sentence per line, any changes to a sentence will be treated on sentence level (instead of paragraph level) when working with TTL files and Git.

Markdown where needed

Optionally, use Markdown (CommonMark) to:

Try your Markdown syntax with the CommonMark dingus.

Example: Markdown blockquote syntax for providing several examples and acknowledging the cited source
samm:preferredName "digital representation"@en ;
samm:description """
   Information and services representing an entity from a given viewpoint.
   > EXAMPLE 1: Examples of information are properties (e.g., maximum temperature), actual parameters (e.g., actual velocity), events (e.g., notification of status change), schematics (electrical), and visualization information (2D and 3D drawings).

   > EXAMPLE 2: Examples of services are asset services (for example, providing the history of the configuration data or providing the actual velocity) and asset-related services (for example, providing a simulation).

   > EXAMPLE 3: Examples of viewpoints are mechanical, electrical, or commercial characteristics.

   > SOURCE: IEC 63278-1:2023, editorial changes
   """@en ;

Try it

Use lists (Markdown)

To use lists within the description attribute, use the Markdown list syntax.

Example: Markdown syntax for an ordered list
samm:description """
   Lorem ipsum description text.
   1. Create an ordered list
   2. By using numbers
   3. And dot delimiters
   4. Conformant to the CommonMark specification
   """@en ;

Try it

Example: Markdown syntax for an unordered list
samm:description """
   Lorem ipsum description text.
   * Create an unordered list
   * (Also known as bullet list)
   * By using asterisks
   * Conformant to the CommonMark specification

   After a blank line, some more lorem ipsum description text.
   """@en ;

Try it

Go back to the Markdown where needed overview.

Add notes (Markdown)

To add one or more notes within the description attribute, use the Markdown blockquote syntax.

Use NOTE: as a prefix.
(While not required by Markdown, this practice helps distinguish notes, examples, and sources in Aspect Models.)

When to use? A "note" provides further information that requires extra attention.

Example: Markdown blockquote syntax for adding a note
samm:description """
   Lorem ipsum description text.
   > NOTE: A note detailing further info.
   """@en ;

Try it

Example: Markdown blockquote syntax for adding a note with several sentences
samm:description """
   Lorem ipsum description text.
   > NOTE: The note starts here.
   > On TTL source-code level, write every sentence in a new line.
   > This helps reviewing TTL source code changes (due to line-based diffs by Git).
   > When parsed, for example, to HTML output, the note will be displayed as concurrent text, without line breaks.
   >
   > To force line breaks within a note, add a blank line.
   >
   > Do not be lazy:
   >
   > Explicitly add the > character for each new line of the note.
   """@en ;

Try it

Example: Markdown blockquote syntax for adding several notes
samm:description """
   Lorem ipsum description text.
   > NOTE: A note detailing further info.

   Important: Add a blank line before you add further description text.
   > NOTE: Another note.
   Further description text. Ooops! Without a blank line between note and further description text, text will be interpreted as if still being part of the note.
   """@en ;

Try it

Go back to the Markdown where needed overview.

Provide examples (Markdown)

To provide examples within the description attribute, use the Markdown blockquote syntax.

Use EXAMPLE: as a prefix.
(While not required by Markdown, this practice helps distinguish notes, examples, and sources in Aspect Models.)

When to use? An "example" details one or more specific examples for a definition or explanation that was given before.

Example: Markdown blockquote syntax for providing an example
samm:description """
   Lorem ipsum description text.
   > EXAMPLE: Providing some example.

   After a blank line, some more lorem ipsum description text.
   """@en ;

Try it

Example: Markdown blockquote syntax for providing several examples
samm:description """
   Lorem ipsum description text.
   > EXAMPLE 1: Providing some example.

   > EXAMPLE 2: After a blank line, providing another example for the given description.
   > Another sentence of the example.
   >
   > After a line break, the last example sentence.

   After a blank line, some more lorem ipsum description text.
   """@en ;

Try it

Go back to the Markdown where needed overview.

Acknowledge sources (Markdown)

To indicate the cited sources used within the description attribute, use the Markdown blockquote syntax.

Use SOURCE: as a prefix.
(While not required by Markdown, this practice helps distinguish notes, examples, and sources in Aspect Models.)

When to use? A "source" acknowledges a source that was cited in the Description.

To generally link to related resources for further reference, use the samm:see attribute.
Example: Markdown blockquote syntax for indicating a cited source
samm:description """
   Lorem ipsum description text, citing a source.
   > SOURCE: Indicate source, optionally add [a link](https://www.example.com)
   """@en ;

Try it

Example descriptions acknowledging cited sources
<...>
   samm:preferredName "digital representation"@en ;
   samm:description """
      Information and services representing an entity from a given viewpoint.
      > SOURCE: IEC 63278-1:2023, editorial changes, no examples
      """@en ;
   <...>

<...>
   samm:preferredName "service"@en ;
   samm:description """
      Distinct part of the functionality that is provided by an entity through interfaces.
      > SOURCE: IEC 63278-1:2023; IEC 60050-741:2020, 741-01-28
      """@en ;
   <...>

<...>
   samm:preferredName "system"@en ;
   samm:description """
      Interacting, interrelated, or interdependent elements forming a complex whole.
      > SOURCE: IEC 63278-1:2023; IEC TS 62443-1-1:2009, 3.2.123
      """@en ;
   <...>

Try it – This roughly sketches how the Preferred Name could be parsed and combined with the Description within an output.

Go back to the Markdown where needed overview.

Markdown blockquote summary

The following table indicates how to employ the Markdown blockquote syntax to convey notes, examples, and sources within the description attribute.

Markdown syntax Recommended prefix Example

>

NOTE:

> NOTE: This provides further information that also needs some extra attention, which is why such a piece of information is highlighted as a "note".

>

EXAMPLE:

> EXAMPLE: This details an example for a given definition.

>

SOURCE:

> SOURCE: This acknowledges a source that was cited in the Description—​optionally including a [link](https://www.example.com).

How to use the Markdown blockquote syntax:

  • Explicitly start each line with the > character. (Recommended)

  • To add more content after the blockquote element, add a blank line after the blockquote element. (Required)

All Markdown blockquote elements—​notes, examples, and sources—​can contain URLs in Markdown notation.

Go back to the Markdown where needed overview.

Choosing a Numeric Type

While JSON only distinguishes between number (floating point) and integer, the type hierarchy for Aspect Models provides many more options. There is a distinction between the numeric core types (xsd:integer and the fixed-point type xsd:decimal) and the limited range numbers that correspond to the numeric types as defined in most programming languages (xsd:float and xsd:double as well as the integer types xsd:int, xsd:short etc.).

As an Aspect Model ideally captures as much of the domain semantics as possible, it should not limit itself according to implementation-specific restrictions. In particular, limited range numbers should only be used when the semantics of the numeric range are relevant beyond the implementation of the Aspect. For example, a Property temperature of a sensor could use a limited range type such as xsd:int, when the physical sensor can never provide a value outside of this range, while a Property such as numberOfProducedItems is not logically limited, so it should use xsd:integer.

Choosing a Unit

When trying to refer to a physical unit, please see the Unit Catalog. When searching for the unit, remember that the unit catalog uses British English, e.g., metre instead of meter.

If you’re modeling quantities for which both the metric system and the imperial system provide units, such as meter vs. feet, it is always recommended to use the metric system (preferably SI units like meter or others like kilometer if more common in the domain) – unless there are specific reasons to create the model differently. In any case, it is strongly discouraged to add multiple Properties in the same scope representing the same value but only using different units due to the inherent complexity.

Choosing a Characteristic

The following decision tree helps to find the right Characteristic for a Property.

A common error is using the Text Characteristic for anything resembling a string. Text is intended for values that are meant only for humans, for example, a description of a device that is entered by a user as free text. Values such as identifiers, hostnames, table names, license plate numbers etc. should not use the Text Characteristic.

If you create Characteristics that are not limited to your modeled domain but are generally useful, please consider contributing them so that they can be included in the Semantic Aspect Meta Model’s Characteristic catalog.

characteristics decision tree

Choosing Constraints

Constraints are used to precisely specify limiting conditions of Characteristics. It is recommended to use Constraints thoroughly:

  1. It makes the intent of the respective Property clear for humans reading the model or documentation generated from the model.

  2. It allows tooling to generate code for the Aspect that can take the Constraints into account. Validation code corresponding to the Constraints can be directly inserted, thus reducing manual implementation effort.

The following decision tree helps to find matching Constraints for a Characteristic. Note that multiple Constraints can be combined.

If and only if the value has a string-like value space and does not use UTF-8 as an encoding, use an Encoding Constraint for the Property. This will ensure that consumers of the Aspect will not end up with broken special characters.
constraints decision tree

Reusing Elements

It is generally advisable to reuse definitions of existing model elements that describe the desired semantics. This not only ensures efficiency and maintainability but, more importantly, it explicitly expresses that the model builds upon a set of agreed-upon abstractions. The reuse of existing model element definitions makes it clear that your model talks about the same thing. On the other hand, introducing another definition of an allegedly already existing concept is equivalent to stating that the deliberately newly created definition does indeed mean something different. This is particularly useful when model elements are created for terminology that can have many different meanings in various contexts, such as the term "process".

Entities, Characteristics, Events, Constraints, and Properties are fundamental components of an Aspect. Reusing these elements across different Aspects ensures consistency, reduces redundancy, and simplifies the management and integration of shared attributes and interactions.