diff --git a/documentation/modules/ROOT/pages/characteristics.adoc b/documentation/modules/ROOT/pages/characteristics.adoc index 019d603a..0a3f1e03 100644 --- a/documentation/modules/ROOT/pages/characteristics.adoc +++ b/documentation/modules/ROOT/pages/characteristics.adoc @@ -1,5 +1,5 @@ //// -Copyright (c) 2020 Robert Bosch Manufacturing Solutions GmbH +Copyright (c) 2023 Robert Bosch Manufacturing Solutions GmbH See the AUTHORS file(s) distributed with this work for additional information regarding authorship. @@ -16,9 +16,9 @@ SPDX-License-Identifier: MPL-2.0 [[characteristics-classes]] == 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 +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 @@ -295,7 +295,7 @@ See xref:modeling-guidelines.adoc#declaring-either[declaring either] for usage i {samm-c}SingleEntity -- -Describes a Property whose data type is an Entity. The Entity used as data type may be defined in +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 {meta-model-full-name}. See xref:modeling-guidelines.adoc#declaring-characteristics[declaring characteristics] for usage in an Aspect Model. @@ -310,7 +310,7 @@ See xref:modeling-guidelines.adoc#declaring-characteristics[declaring characteri Describes a Property which contains a scalar xref:datatypes.adoc#data-types[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. +define the parts, the value must be deconstructed using a regular expression. See xref:modeling-guidelines.adoc#declaring-structured-value[declaring structured value] for usage in an Aspect Model. @@ -370,22 +370,23 @@ dataType: `xref:datatypes.adoc#data-types[xsd:string]` -- {samm-c}MultiLanguageText -- - +// From the diagram, readers would aspect to read from left to right, so the MultiLanguageText box should appear to the right of the Text box, as Timestamp box is described first. 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: `xref:datatypes.adoc#data-types[rdf:langString]` -[[boolean-characteristic]] -=== Boolean +[[language-characteristic]] +=== Language [.element-urn] -- -{samm-c}Boolean +{samm-c}Language -- -Represents a boolean value (i.e., a "flag"). +Describes a Property containing a language according to ISO 639-1 +xref:samm-specification:appendix:bibliography.adoc#iso639[[iso639\]], for example "de". -dataType: `xref:datatypes.adoc#data-types[xsd:boolean]` +dataType: `xref:datatypes.adoc#data-types[xsd:string]` [[locale-characteristic]] === Locale @@ -393,23 +394,21 @@ dataType: `xref:datatypes.adoc#data-types[xsd:boolean]` -- {samm-c}Locale -- - Describes a Property containing a locale according to IETF BCP 47 xref:samm-specification:appendix:bibliography.adoc#bcp47[[bcp47\]], for example "de-DE". dataType: `xref:datatypes.adoc#data-types[xsd:string]` -[[language-characteristic]] -=== Language +[[boolean-characteristic]] +=== Boolean [.element-urn] -- -{samm-c}Language +{samm-c}Boolean -- -Describes a Property containing a language according to ISO 639-1 -xref:samm-specification:appendix:bibliography.adoc#iso639[[iso639\]], for example "de". +Represents a boolean value (i.e., a "flag"). -dataType: `xref:datatypes.adoc#data-types[xsd:string]` +dataType: `xref:datatypes.adoc#data-types[xsd:boolean]` [[resource-path-characteristic]] === Resource Path @@ -539,7 +538,7 @@ Constraint restricts the range of the value. The scalar data types that can be r `xsd:long`, `xsd:unsignedByte`, `xsd:unsignedShort`, `xsd:unsignedInt`, `xsd:unsignedLong`, `xsd:positiveInteger` , `xsd:nonPositiveInteger`, `xsd:negativeInteger` and `xsd:nonNegativeInteger`. -* Characteristics that have a xref:datatypes.adoc#data-types[time and date data type];. In this case +* Characteristics that have a xref:datatypes.adoc#data-types[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`. @@ -556,7 +555,7 @@ Restricts the encoding of a Property. [width="100%", options="header", cols="30,60,10"] |=== | Attributes | Description | Required -| `samm:value` | Configures the encoding. This may be one of the following: `samm:US-ASCII`, +| `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`. | {ok} |=== diff --git a/documentation/modules/ROOT/pages/datatypes.adoc b/documentation/modules/ROOT/pages/datatypes.adoc index 77f38d31..9f194fc1 100644 --- a/documentation/modules/ROOT/pages/datatypes.adoc +++ b/documentation/modules/ROOT/pages/datatypes.adoc @@ -27,7 +27,7 @@ boolean, number for all numeric types, JSON object for Entities and string for e The following figure shows the type hierarchy, in which arrows are interpreted as "is a subtype of and can therefore be cast to". The types `anyType` and `anySimpleType` are "special" types of the -XSD type hierarchy and should not be directly used. +XSD type hierarchy and _should not_ be directly used. NOTE: All data types inheriting from `anySimpleType` are called _scalar_, i.e. every allowed data type except `samm:Entity` is scalar. @@ -89,7 +89,7 @@ definition in the respective standards and an informative description of their v |=== The following types defined by the XSD and RDF specifications, respectively, are considered -unsuitable in Aspect Models and should not be used: +unsuitable in Aspect Models and _should not_ be used: `xsd:language`, `xsd:normalizedString`, `xsd:token`, `xsd:NMTOKEN`, `xsd:Name`, `xsd:NCName`, `xsd:QName`, `xsd:ENTITY`, `xsd:ID`, `xsd:IDREF`, `xsd:NOTATION`, `xsd:IDREFS`, `xsd:ENTITIES`, diff --git a/documentation/modules/ROOT/pages/meta-model-elements.adoc b/documentation/modules/ROOT/pages/meta-model-elements.adoc index a2e0b46f..b1a36591 100644 --- a/documentation/modules/ROOT/pages/meta-model-elements.adoc +++ b/documentation/modules/ROOT/pages/meta-model-elements.adoc @@ -1,7 +1,7 @@ //// -Copyright (c) 2020 Robert Bosch Manufacturing Solutions GmbH +Copyright (c) 2023 Robert Bosch Manufacturing Solutions GmbH -See the AUTHORS file(s) distributed with this work for additional information regarding authorship. +See the AUTHORS file(s) distributed with this work for additional information regarding authorship. This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/ @@ -18,18 +18,34 @@ be built. The following diagram shows the basic building blocks: image::aspect-meta-model.svg[width=100%] +* An _Aspect_ is the root element of each Aspect Model and has a number of Properties, Events, and + Operations. +This element is mandatory and _must_ appear exactly once per model. +It has any number of Properties, Operations and Events ([0..n]). + * A _Property_ represents a named value. +This element is optional and can appear multiple times in a model ([0..n]). +One Property has exactly one Characteristic. -* An _Abstract Entity_ is a logical encapsulation of a shared concept. It has a number of Properties. An _Abstract Entity_ can extend another _Abstract Entity_. +* An _Abstract Entity_ is a logical encapsulation of a shared concept. It has any number of +Properties ([0..n]). An _Abstract Entity_ can extend another _Abstract Entity_ ([0..1]). This +element is optional and can appear multiple times in a model ([0..n]). -* An _Entity_ is a logical encapsulation of multiple values. It has a number of Properties. An _Entity_ can extend either another _Entity_ or an _Abstract Entity_. +* An _Entity_ is a logical encapsulation of multiple values. It has any number of Properties +([0..n]). An _Entity_ can extend either another _Entity_ ([0..1]) or an _Abstract Entity_ ([0..1]). +This element is optional and can appear multiple times in a model ([0..n]). * A _Characteristic_ describes a Property's meaning in the context of the Aspect with information such as its data type, if it is a collection, that a string value is to be interpreted as one of a fixed number of valid states or that a numeric value has an associated physical unit. +This element is mandatory. It _must_ appear once per Property. -* A _Constraint_ represents a limitation that is applied to another Characteristic (for example on the +* A _Trait_ is used to add one or more constraints to a Characteristic ([1..n]), which is referred to + as the "base Characteristic". + +* A _Constraint_ represents a limitation that is applied to a Characteristic (for example on the numeric value range or the maximum length of string). +This element is optional and can appear multiple times per Characteristic ([0..n]). Characteristics, Constraints and element descriptions, are _not part of the data_ an Aspect sends, but only exist in its model. A number of commonly used Characteristics and Constraints are @@ -39,21 +55,25 @@ xref:characteristics.adoc#characteristics[Characteristics] for more information. * An _Operation_ represents an action that can be triggered on the Aspect. Depending on the Aspect, this can, but does not have to, trigger an action on the asset that is represented by the Digital Twin, for example switching a part of a machine on or off. +This element is optional and can appear multiple times per Aspect ([0..n]). +One Operation has any number of input Properties ([0..n]) and at most one output Property ([0..1]). * An _Event_ is a model element that represents a single occurence where the timing is important. Assets can for instance emit events to notify other assets in case of special occurences. +This element is optional and can appear multiple times per Aspect ([0..n]). +One Event has any number of parameter Properties ([0..n]). -* An _Aspect_ is the root element of each Aspect Model and has a number of Properties, Events, and - Operations. +* _xref:characteristics.adoc#quantifiable-characteristic[Quantifiable]_ is the Characteristic that + makes use of a Unit. Other Characteristics that are derived from Quantifiable have a Unit as well. * A _Unit_ refers to a physical unit, such as _metre_ or _degree celsius_. A catalog of units are predefined in the scope of the {meta-model-full-name}, see section xref:units.adoc[Units] for an -in-depth description. +in-depth description. A custom Unit can be added to a Characteristic, when the Characteristic is +defined as Quantifiable class. It _must_ appear exactly once per Quantifiable Characteristic. * A _Quantity Kind_ describes the kind a Unit refers to, such as _length_ or _temperature_. +This attribute is optional and can appear multiple times per Unit ([0..n]). -* _xref:characteristics.adoc#quantifiable-characteristic[Quantifiable]_ is the Characteristic that - makes use of a Unit. Other Characteristics that are derived from Quantifiable have a Unit as well. NOTE: See the sections xref:modeling-guidelines.adoc#attributes-that-all-model-elements-have[Attributes diff --git a/documentation/modules/ROOT/pages/modeling-guidelines.adoc b/documentation/modules/ROOT/pages/modeling-guidelines.adoc index b81d32b2..7fd846d9 100644 --- a/documentation/modules/ROOT/pages/modeling-guidelines.adoc +++ b/documentation/modules/ROOT/pages/modeling-guidelines.adoc @@ -1,5 +1,5 @@ //// -Copyright (c) 2020 Robert Bosch Manufacturing Solutions GmbH +Copyright (c) 2023 Robert Bosch Manufacturing Solutions GmbH See the AUTHORS file(s) distributed with this work for additional information regarding authorship. @@ -290,7 +290,7 @@ 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 +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. NOTE: `samm:notInPayload` cannot be used in Abstract Entities, but the setting for a specific property @@ -385,7 +385,7 @@ for Properties when all of the following conditions are met: One of the main use cases is complex identifiers that encode context information such as provenance information, version numbers, locations codes and so on. It is unreasonable to split such a value up -into separate Properties, because it complicates working with corresponding data: For example, such +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. @@ -470,9 +470,9 @@ Constraint as a `samm-c:constraint` to the Trait: include::example$constrained-numberlist.ttl[tags=content] ---- -Another more complex example is given below: The Property `someIdentifier` is defined that uses a +Another more complex example is given below. The Property `someIdentifier` is defined that uses a xref:characteristics.adoc#code-characteristic[Code] instance using a dataType of `xsd:string`, -combined with two Constraints: An xref:characteristics.adoc#encoding-constraint[Encoding Constraint] +combined with two Constraints: an xref:characteristics.adoc#encoding-constraint[Encoding Constraint] that restricts the value space to US-ASCII and a xref:characteristics.adoc#length-constraint[Length Constraint] that limits the string to 80 characters. @@ -565,7 +565,7 @@ include::example$aspect-sample.ttl[tags=abstract-entity-declaration] 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 +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: @@ -576,7 +576,7 @@ include::example$abstract-property-sample.ttl[tags=abstract-entity-with-abstract ---- 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 +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 @@ -726,7 +726,7 @@ NOTE: The value for the `samm:payloadName` attribute must be of type `xsd:string include::example$payload-name-sample.ttl[tags=payload-name-declaration] ---- -CAUTION: A Property may not be marked as not being included in the payload using `samm:notInPayload +CAUTION: 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`. NOTE: It is also useful to know that the payload name definition is inherited from parent Entity diff --git a/documentation/modules/ROOT/pages/namespaces.adoc b/documentation/modules/ROOT/pages/namespaces.adoc index 1dd82b50..ddb9dfbe 100644 --- a/documentation/modules/ROOT/pages/namespaces.adoc +++ b/documentation/modules/ROOT/pages/namespaces.adoc @@ -25,7 +25,7 @@ urn:samm:org.eclipse.esmf.samm::# where the variable parts are interpreted as follows: -* *element-type* -- a selector describing the kind of thing the URN describes, must be one of: +* *element-type* -- a selector describing the kind of thing the URN describes, _must_ be one of: ** `meta-model` - For meta model elements ** `characteristic` - For Characteristics and Constraints that are defined in the scope of the meta model ** `entity` - For Entities that are defined inside the scope of the meta model @@ -87,13 +87,13 @@ xref:samm-specification:appendix:bibliography.adoc#turtle[[turtle\]] and https://www.w3.org/TR/sparql11-query/#QSynIRI[PREFIX] in SPARQL xref:samm-specification:appendix:bibliography.adoc#sparql[[sparql\]]): -* The prefix "samm" shall be used for the URN `{samm}` -* The prefix "samm-c" shall be used for the URN `{samm-c}` -* The prefix "samm-e" shall be used for the URN `{samm-e}` -* The prefix "unit" shall be used for the URN `{unit}` -* The empty prefix (":" in RDF/Turtle) shall be used for the URN prefix of the current model scope, i.e. +* The prefix "samm" _must_ be used for the URN `{samm}` +* The prefix "samm-c" _must_ be used for the URN `{samm-c}` +* The prefix "samm-e" _must_ be used for the URN `{samm-e}` +* The prefix "unit" _must_ be used for the URN `{unit}` +* The empty prefix (":" in RDF/Turtle) _must_ be used for the URN prefix of the current model scope, i.e. everything up to and including the `#` of the model elements that are being defined -* For other elements, use prefixes that do not contain the string `samm`. +* For other elements, use prefixes that _must not_ contain the string `samm`. *Example of Aspect Model description in RDF/Turtle, with prefix declarations and usage:* diff --git a/documentation/modules/appendix/pages/model-evolution.adoc b/documentation/modules/appendix/pages/model-evolution.adoc index cc67b6d8..5752fc3f 100644 --- a/documentation/modules/appendix/pages/model-evolution.adoc +++ b/documentation/modules/appendix/pages/model-evolution.adoc @@ -221,7 +221,7 @@ Renaming the Property in the last step is a change made to demonstrate dealing w Alternatively, the modeler could rename the Property but still keep this change a safe change by specifying a xref:ROOT:modeling-guidelines.adoc#payload-names[samm:payloadName] ⑥ that corresponds to the effective payload name of the Property in the previous version of the Aspect Model (i.e., -1.0.2). In this scenario, since the change is a safe changes, the version is increased to 1.0.3 +1.0.2). In this scenario, since the change is a safe change, the version is increased to 1.0.3 instead of 1.1.0. |====