Characteristics and Constraints
Characteristics Classes
Characteristics Classes describe abstract concepts that need to be made specific when they are used. So for example, the Enumeration Characteristic represents the concept "one of multiple predefined values". In order to use the Characteristic, an instance of it needs to 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.
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 |
---|---|---|
|
Human readable name in a specific language |
|
|
Human readable description in a specific language |
|
|
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 |
---|---|---|
|
The Characterstic that is being constrained |
|
|
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 |
---|---|---|
|
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 |
---|---|---|
|
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 |
---|---|---|
|
List of possible values. The |
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 |
---|---|---|
|
The default value for the state |
Duration
urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Duration
A time duration.
Attributes | Description | Required |
---|---|---|
|
Reference to a Unit as defined in the Unit catalog. The
referenced unit or its referenceUnit must have the quantityKind
|
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 |
---|---|---|
|
Reference to a scalar or complex (Entity) data type. See Section "Type System" in the Aspect Meta Model. |
|
|
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 |
---|---|---|
|
Set to 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 |
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 |
---|---|---|
|
The left side of the Either. The attribute references another Characteristic which describes the value. |
|
|
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 may 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 is deconstructed using a regular expression.
See declaring structured value for usage in an Aspect Model.
Attributes | Description | Required |
---|---|---|
|
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 |
|
|
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.
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
Boolean
urn:samm:org.eclipse.esmf.samm:characteristic:2.1.0#Boolean
Represents a boolean value (i.e., a "flag").
dataType: xsd:boolean
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
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
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
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 |
---|---|---|
|
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 |
---|---|---|
|
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 |
---|---|---|
|
The upper bound of a range |
|
|
The lower bound of a range |
|
|
Defines whether the upper bound of a range is inclusive or
exclusive. Possible values are |
|
|
Defines whether the lower bound of a range is inclusive or
exclusive. Possible values are |
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
andxsd: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 |
---|---|---|
|
Configures the encoding. This may be one of the following: |
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
andrdf: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 |
---|---|---|
|
The maximum length. Must be given as |
|
|
The minimum length. Must be given as |
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 |
---|---|---|
|
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 |
---|---|---|
|
The scaling factor for a fixed point number. Must be given as
|
|
|
The number of integral digits for a fixed point number. Must be given as
|