Review terms for "should"/"must" actions for RBS docs & SAMM spec (#250)

* Move the Aspect definition to the top, add the Trait definition.

* add optional/mandatory element information for each element

* replace "shall" with "must" to emphasize the certainty.

* highlight the "should not" phrase

* clarify the "must" term

* add comments and fix typos

* Add minor fixes and remove addressed comments

---------

Co-authored-by: Textor Andreas (BCI/ESW17) <[email protected]>

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,46 +370,45 @@ 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
 [.element-urn]
 --
 {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}
 |===
 

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`,

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

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

documentation/modules/ROOT/pages/namespaces.adoc

@@ -25,7 +25,7 @@ urn:samm:org.eclipse.esmf.samm:<element-type>:<version>#<element-name>
 
 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:*
 

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