Characteristics and Constraints

Characteristics Classes

Characteristics Classes describe abstract concepts that must be made specific when they are used. For example, the Enumeration Characteristic represents the concept "one of multiple predefined values". In order to use the Characteristic, an instance of it must be specified in the corresponding Aspect Model, that determines which values are valid for the respective Property.

The following diagram shows the Characteristics Classes defined in the scope of the Semantic Aspect Meta Model.

characteristics classes

Characteristic

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Characteristic

Base class of all characteristics. This Characteristics Class can also be instantiated directly (i.e., without creating a subclass).

See declaring characteristics for usage in an Aspect Model.

Attributes Description Required

samm:preferredName

Human readable name in a specific language

samm:description

Human readable description in a specific language

samm:dataType

Reference to a scalar or complex (Entity) data type. See Section "Type System" in the Aspect Meta Model

Trait

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Trait

The Trait is used to add one or more Constraints to another Characteristic, which is referred to as the "base Characteristic". A Trait itself has no samm:dataType, because it inherits the type of its samm-c:baseCharacteristic.

See declaring constraints for usage in an Aspect Model.

Attributes Description Required

samm-c:baseCharacteristic

The Characterstic that is being constrained

samm-c:constraint

A Constraint that is applicable to the base Characteristic. This attribute may be used multiple times, to add multiple Constraints to the base Characteristic.

Quantifiable

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Quantifiable

A value which can be quantified and may have a unit, e.g., the number of bolts required for a processing step or the expected torque with which these bolts should be tightened.

See declaring characteristics for usage in an Aspect Model.

Attributes Description Required

samm-c:unit

Reference to a Unit as defined in the Unit catalog

Measurement

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Measurement

A measurement is a numeric value with an associated unit and quantity kind.

See declaring characteristics for usage in an Aspect Model.

Attributes Description Required

samm-c:unit

Reference to a Unit as defined in the Unit catalog

Enumeration

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Enumeration

An enumeration represents a list of possible values.

See declaring enumerations for usage in an Aspect Model.

Attributes Description Required

samm-c:values

List of possible values. The dataType of each of the values must match the dataType of the Enumeration.

State

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#State

A state is subclass of Enumeration with a default value.

See declaring state for usage in an Aspect Model.

Attributes Description Required

samm-c:defaultValue

The default value for the state

Duration

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Duration

A time duration.

Attributes Description Required

samm-c:unit

Reference to a Unit as defined in the Unit catalog. The referenced unit or its referenceUnit must have the quantityKind unit:time. Currently, the following units can therefore be used: unit:centipoisePerBar unit:commonYear unit:day unit:henryPerKiloohm unit:henryPerOhm unit:hour unit:kilosecond unit:microhenryPerKiloohm unit:microhenryPerOhm unit:microsecond unit:millihenryPerKiloohm unit:millihenryPerOhm unit:millipascalSecondPerBar unit:millisecond unit:minuteUnitOfTime unit:month unit:nanosecond unit:pascalSecondPerBar unit:picosecond unit:poisePerBar unit:poisePerPascal unit:reciprocalMinute unit:secondUnitOfTime unit:shake unit:siderealYear unit:tropicalYear unit:week unit:year

Collection

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Collection

A group of values which may be either of a scalar or Entity type. The values may be duplicated and are not ordered (i.e., bag semantics).

See declaring collections for usage in an Aspect Model.

Attributes Description Required

samm:dataType

Reference to a scalar or complex (Entity) data type. See Section "Type System" in the Aspect Meta Model.

samm-c:elementCharacteristic

Reference to a Characteristic which describes the individual elements contained in the Collection.

List

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#List

A subclass of Collection which may contain duplicates and is ordered.

Set

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Set

A subclass of Collection which may not contain duplicates and is unordered.

Sorted Set

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#SortedSet

A subclass of Collection which may not contain duplicates and is ordered.

Time Series

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#TimeSeries

A subclass of Sorted Set containing values with the exact point in time when the values where recorded.

See declaring time series for usage in an Aspect Model.

Attributes Description Required

samm:dataType

Set to samm-e:TimeSeriesEntity. This Entity consists of two Properties, namely samm-e:timestamp and samm-e:value.

As such the structure for time series data is fixed to a collection of key/value pairs with the timestamp being the key and the value being the value.

The samm-e:timestamp property has a fixed Characteristic of samm-c:Timestamp. The Characteristic of the samm-e:value Property is set in the specific Aspect Model giving the value domain specific semantics.

Code

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Code

Describes a Property which contains any kind of code. Note that this Characteristic does not define a samm:dataType, this must therefore be done when instantiating the Characteristic.

Either

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Either

Describes a Property whose value can have one of two possible types (a disjoint union). This Characteristic does not have one explicit samm:dataType, as it can be the datatype of either the left or the right.

See declaring either for usage in an Aspect Model.

Attributes Description Required

samm-c:left

The left side of the Either. The attribute references another Characteristic which describes the value.

samm-c:right

The right side of the Either. The attribute references another Characteristic which describes the value.

Single Entity

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#SingleEntity

Describes a Property whose data type is an Entity. The Entity used as data type could be defined in the same Aspect Model or the shared Entity namespace of the Semantic Aspect Meta Model.

See declaring characteristics for usage in an Aspect Model.

Structured Value

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#StructuredValue

Describes a Property which contains a scalar string-like value space value with a well-defined structure. The Structured Value Characteristic allows the description of the parts of the Property’s value by linking to a separate Property definition for each part. To define the parts, the value must be deconstructed using a regular expression.

See declaring structured value for usage in an Aspect Model.

Attributes Description Required

samm-c:deconstructionRule

The regular expression used to deconstruct the value into parts that are mapped to separate Properties. This regular expression must contain the same number of capture groups as there are Properties given in the elements list. The n​th capture group maps to the n​th Property in the elements list.

samm-c:elements

A list of entries each of which can either be a Property reference or a string literal. The list must contain at least one Property reference.

Concatenating the values of the Properties in the elements list with the string literals in the given order should yield a value that corresponds to the original value that has this Structured Value Characteristic. While the deconstructionRule is used for deconstruction, the string literals in the elements list are used for construction. When the Property using the Structured Value Characteristic also defines an exampleValue, construction and deconstruction of the value are tested when validating the model.

Characteristics Instances

A number of concrete Characteristics are defined in conjunction with the Aspect Meta Model. They can be used as-is as Characteristics for Properties in Aspect Models. The following diagram shows the Characteristics Instances defined in the scope of the Semantic Aspect Meta Model.

characteristics instances

Timestamp

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Timestamp

Describes a Property which contains the date and time with an optional timezone.

dataType: xsd:dateTime

Text

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Text

Describes a Property which contains plain text. This is intended exclusively for human readable strings, not for identifiers, measurement values, etc.

dataType: xsd:string

Multi-Language Text

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#MultiLanguageText

Describes a Property which contains plain text in multiple languages. This is intended exclusively for human readable strings, not for identifiers, measurement values, etc.

dataType: rdf:langString

Language

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Language

Describes a Property containing a language according to ISO 639-1 [iso639], for example "de".

dataType: xsd:string

Locale

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Locale

Describes a Property containing a locale according to IETF BCP 47 [bcp47], for example "de-DE".

dataType: xsd:string

Boolean

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Boolean

Represents a boolean value (i.e., a "flag").

dataType: xsd:boolean

Resource Path

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#ResourcePath

Describes a Property that contains the path to a relative or absolute resource.

dataType: xsd:anyURI

MIME Type

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#MimeType

Describes a Property that contains a MIME type as defined by RFC 2046 [rfc2046], for example "application/json", "application/xls" or "image/png".

dataType: xsd:string

Unit Reference

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#UnitReference

Describes a Property containing a reference to one of the units in the Unit catalog.
See Using Unit Reference for usage in an Aspect Model.

dataType: samm:curie

Reference

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Reference

A reference is a value that refers to a concept such as a resource or a model element. It can be a SAMM meta model identifier, a SAMM model element identifier, a resource URI, or a URI referring to a concept in a different formalism or vocabulary. The value follows the same rules as a samm:see reference.

See declaring Reference for usage in an Aspect Model.

Constraints

Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Constraint

Base class for other constraints that constrain a Characteristic in some way, e.g., the Range Constraint limits the value range for a Property.

The Constraint class has no attributes.

Language Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#LanguageConstraint

Restricts a value to a specific language.

Attributes Description Required

samm-c:languageCode

An ISO 639-1 [iso639] language code for the language of the value of the constrained Property, e.g., "de".

Locale Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#LocaleConstraint

Restricts a value to a specific locale, i.e., a language with additional region information.

Attributes Description Required

samm-c:localeCode

An IETF BCP 47 [bcp47] language code for the locale of the value of the constrained Property, e.g., "de-DE".

Range Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#RangeConstraint

Restricts the value range of a Property. At least one of samm-c:maxValue or samm-c:minValue must be present in a Range Constraint.

Whether the samm-c:maxValue and samm-c:minValue are inclusive or exclusive can be defined using the samm-c:upperBoundDefinition and samm-c:lowerBoundDefinition attributes. When one or both of them are not specified, the corresponding value defaults to inclusive.

The values for maxValue and minValue must be given in the same effective dataType that the constrained Characteristic uses.
Attributes Description Required

samm-c:maxValue

The upper bound of a range

samm-c:minValue

The lower bound of a range

samm-c:upperBoundDefinition

Defines whether the upper bound of a range is inclusive or exclusive. Possible values are samm-c:AT_MOST and samm-c:LESS_THAN

samm-c:lowerBoundDefinition

Defines whether the lower bound of a range is inclusive or exclusive. Possible values are samm-c:AT_LEAST and samm-c:GREATER_THAN

When either the samm-c:minValue or the samm-c:maxValue is not given, the Range is defined as having an open lower or upper boundary.
The AT_LEAST and AT_MOST values for lowerBoundDefinition and upperBoundDefinition define that the values for minValue and maxValue are inclusive. The LESS_THAN and GREATER_THAN values for the lowerBoundDefinition and upperBoundDefinition define that the values for minValue and maxValue are exclusive.

This Constraint can be used to restrict Characteristics with one of two kinds of data types:

  • Characteristics that have a numeric data type; in this case the Constraint restricts the range of the value. The scalar data types that can be restricted are: xsd:double, xsd:float, xsd:decimal, xsd:integer, xsd:byte, xsd:short, xsd:int, xsd:long, xsd:unsignedByte, xsd:unsignedShort, xsd:unsignedInt, xsd:unsignedLong, xsd:positiveInteger , xsd:nonPositiveInteger, xsd:negativeInteger and xsd:nonNegativeInteger.

  • Characteristics that have a time and date data type; in this case the Constraint restricts the scalar data types: xsd:date,xsd:time, xsd:dateTime, xsd:dateTimeStamp, xsd:gYear, xsd:gMonth, xsd:gMonthDay, xsd:duration, xsd:yearMonthDuration, xsd:dayTimeDuration.

Encoding Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#EncodingConstraint

Restricts the encoding of a Property.

Attributes Description Required

samm:value

Configures the encoding. This must be one of the following: samm:US-ASCII, samm:ISO-8859-1, samm:UTF-8, samm:UTF-16, samm:UTF-16BE or samm:UTF-16LE.

The default encoding for values with a string-like value space is UTF-8, therefore using an Encoding Constraint with a samm:value of samm:UTF-8 is only necessary when a Property’s encoding is changed during an Aspect Model version increase from some other encoding to UTF-8 to indicate that the other encoding is not any longer used.

Length Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#LengthConstraint

This Constraint can be used to restrict two types of Characteristics:

  • Characteristics that have a string-like value space; in this case the Constraint restricts the length of the (string-) value. The scalar data types that can be restricted are: xsd:string, xsd:date, xsd:time, xsd:dateTime, xsd:dateTimeStamp, xsd:gYear, xsd:gMonth, xsd:gMonthDay, xsd:duration, xsd:yearMonthDuration, xsd:dayTimeDuration, xsd:hexBinary, xsd:base64Binary, xsd:anyURI, samm:curie and rdf:langString.

  • Collection Characteristics (Collection, Set, Sorted Set, List). In this case the Constraint restricts the number of elements in the collection.

At least one of samm-c:maxValue or samm-c:minValue must be present in a Length Constraint.

Attributes Description Required

samm-c:maxValue

The maximum length. Must be given as xsd:nonNegativeInteger.

samm-c:minValue

The minimum length. Must be given as xsd:nonNegativeInteger.

When using the samm-c:minValue parameter in Length Constraint, it is crucial to consider the following: Creating a Model with a Set/Sorted Set based on a finite Base Characteristic (Boolean or Enumeration) and adding Length Constraint, the samm-c:minValue must not exceed the total number of elements in the Base Characteristic. Models with such conditions are not recognized as invalid, but no valid payloads can exist for them.

Regular Expression Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#RegularExpressionConstraint

Restricts a string value to a regular expression as defined by XQuery 1.0 and XPath 2.0 Functions and Operators [xpath-functions].

Attributes Description Required

samm:value

The regular expression

Fixed Point Constraint

urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#FixedPointConstraint

Defines the scaling factor as well as the amount of integral numbers for a fixed point number. The constraint may only be used in conjunction with Characteristics which use the xsd:decimal data type.

Attributes Description Required

samm-c:scale

The scaling factor for a fixed point number. E.g., if a fixedpoint number is 123.04, the scaling factor is 2 (the number of digits after the decimal point). Must be given as xsd:positiveInteger.

samm-c:integer

The number of integral digits for a fixed point number. E.g., if a fixedpoint number is 123.04, the integer factor is 3 (the number of digits before the decimal point). Must be given as xsd:positiveInteger.