diff --git a/documentation/IDTA-01001/modules/ROOT/pages/annex/uml-templates.adoc b/documentation/IDTA-01001/modules/ROOT/pages/annex/uml-templates.adoc index ad1c442e8..dc53353e7 100644 --- a/documentation/IDTA-01001/modules/ROOT/pages/annex/uml-templates.adoc +++ b/documentation/IDTA-01001/modules/ROOT/pages/annex/uml-templates.adoc @@ -55,7 +55,7 @@ The following kinds of _Types_ are distinguished: ** _:_ Type is an object type (class); it is realized as composite aggregation (composition), and does not exist independent of its parent ** _ModelReference<\{Referable}>:_ Type is a Reference with _Reference/type=ModelReference_ and is called model reference; the \{Referable} is to be substituted by any referable element (including _Referable_ itself for the most generic case) – the element that is referred to is denoted in the __Key/type__=<\{Referable}> for the last _Key_ in the model reference; for the graphical representation see Annex xref:annex/uml.adoc[] , Figure xref:annex/uml.adoc#image-82-shared-aggregation[Graphical Representation of Shared Aggregation]; for more information on referencing see Clause xref:spec-metamodel/referencing.adoc[]. -** _: Type_ Type is no object type (class) but a data type; it is just a value, see Clause xref:spec-metamodel/datatypes.adoc#primitive-data-types[Primitive Data Types]. +** _:_ Type is no object type (class) but a data type; it is just a value, see Clause xref:spec-metamodel/datatypes.adoc#primitive-data-types[Primitive Data Types] ** _:_ Type is an enumeration, see <> _Card._ is the cardinality (or multiplicity) defining the lower and upper bound of the number of instances of the member element. "\*" denotes an arbitrary infinite number of elements of the corresponding Type. "0..1" means optional. "0..*" or "0..3" etc. means that the list may be either not available (optional) or the list is not empty. @@ -89,7 +89,7 @@ This would be an invalid reference for "ModelReference" because it ref (Submodel)https://example.com/aas/1/1/1234859590, (Property)temperature .... -If class type equal to "ModelReference", the following references would be valid references (using the text serialization as defined in Clause 7.2.3) because "Property" and "File" are Referables and "Submodel" itself is also Referable since all Identifiables are referable: +If class type equal to "ModelReference", the following references would be valid references (using the text serialization as defined in Clause xref:mappings/mappings.adoc#reference-serialization[Text Serialization of Values of Type "Reference"]) because "Property" and "File" are Referables and "Submodel" itself is also Referable since all Identifiables are referable: [listing] .... diff --git a/documentation/IDTA-01001/modules/ROOT/pages/annex/usage-metamodel.adoc b/documentation/IDTA-01001/modules/ROOT/pages/annex/usage-metamodel.adoc index e970671e3..dd1afbe85 100644 --- a/documentation/IDTA-01001/modules/ROOT/pages/annex/usage-metamodel.adoc +++ b/documentation/IDTA-01001/modules/ROOT/pages/annex/usage-metamodel.adoc @@ -18,7 +18,7 @@ Plattform Industrie 4.0; Anna Salari, Publik. Agentur für Kommunikation GmbH, d == Composite I4.0 Components -As described in Clause 4.2.1, there is a class of relationships between assets of different hierarchy levels. +As described in Clause xref:general.adoc#life_cycle_with_type_assets_and_instance_assets[], there is a class of relationships between assets of different hierarchy levels. In this class of relationships, automation equipment is explained as a complex, interrelated graph of automation devices and products, performing intelligent production and self-learning/optimization tasks. Details and examples for composite I4.0 Components can be found in xref:bibliography.adoc#bib13[[13\]]. diff --git a/documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc b/documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc index 9f71c48eb..0f612d0e5 100644 --- a/documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc +++ b/documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc @@ -68,13 +68,14 @@ also abbreviations partly adopted; changes: ** added notes * (Editorial) Adding metamodel element IDs to tables themselves for easier usage (besides grammar defining how to derive them) (https://github.com/admin-shell-io/aas-specs/issues/366[#366]) * Update all metamodel element IDs to V3.1 (https://github.com/admin-shell-io/aas-specs/issues/366[#366]) -* Transfer of chapters on formats Metadata, Paths and Value-Only from Part 2 API to Part 1 Metamodel (https://github.com/admin-shell-io/aas-specs/issues/325[#325]) -* Enhanced documentation or Value-Only serialization (https://github.com/admin-shell-io/aas-specs/issues/371[#371], https://github.com/admin-shell-io/aas-specs/issues/370[#370]) -* (Editorial) Update Chapter on Value-Only Serialization +* Transfer of clauses on formats Metadata, Paths and Value-Only from Part 2 API to Part 1 Metamodel (https://github.com/admin-shell-io/aas-specs/issues/325[#325]) +* (Editorial) Update clause on Value-Only Serialization, improve documentation (https://github.com/admin-shell-io/aas-specs/issues/370[#370], https://github.com/admin-shell-io/aas-specs/issues/371[#371]) ** add table similar to metadata table: which attributes are displayed in Value-Only serialization ** update examples to provide Value-Only serialization for every submodel element (not in the context of a Submodel as before) -** add chapter for Submodel Example (with properties from SMT Technical Data, not Families any longer) +** add clause for Submodel Example (with properties from SMT Technical Data, not Families any longer) +* remove recommendation to use external references for semanticId (https://github.com/admin-shell-io/aas-specs/issues/376[#376]) and related attributes like valueId and isCaseOf (https://github.com/admin-shell-io/aas-specs/issues/396[#396]) ** update Schema for JSON-Value Serialization (https://github.com/admin-shell-io/aas-specs/issues/366[#366]) +* remove clauses on OPC UA and AutomationML mappings (https://github.com/admin-shell-io/aas-specs/issues/373[#373], https://github.com/admin-shell-io/aas-specs/issues/397[#397]) * update explanatory text and notes in the context of AdministrativeInformation (https://github.com/admin-shell-io/aas-specs/issues/331[#331]) * Transfer from .docx to asciidoc (.adoc) and maintenance in GitHub * Transfer of all UML figures to PlantUML (.puml) and maintenance in GitHub, no XMI presenation part of release any longer (https://github.com/admin-shell-io/aas-specs/issues/439[#439]) diff --git a/documentation/IDTA-01001/modules/ROOT/pages/general.adoc b/documentation/IDTA-01001/modules/ROOT/pages/general.adoc index bc5e646b4..47ae695dc 100644 --- a/documentation/IDTA-01001/modules/ROOT/pages/general.adoc +++ b/documentation/IDTA-01001/modules/ROOT/pages/general.adoc @@ -50,7 +50,7 @@ The attribute "derivedFrom" in the metamodel is used to explicitly state a relat Other relationships are not explicitly supported by the metamodel of the Asset Administration Shell, but they can be modelled via the xref:spec-metamodel/submodel-elements.adoc#relationship-element-attributes["RelationshipElement"] submodel element type. ==== -Table <> gives an overview of the different life cycle phases and the role of type assets and instance assets as well as their relationship in these phases. +<> gives an overview of the different life cycle phases and the role of type assets and instance assets as well as their relationship in these phases. This important relationship should be maintained throughout the life of the instance assets. It makes it possible to forward updates from the type assets to the instance assets, either automatically or on demand. @@ -303,7 +303,7 @@ See also DIN SPEC 91406 xref:bibliography.adoc#bib31[[31\]] for further informat === Which Identifiers for Which Elements? Not every identifier is applicable for every element of the UML model representing the Asset Administration Shell. -Table <> therefore gives an overview on the different constraints and recommendations on the various entities, which implement xref:spec-metamodel/common.adoc#identifiable-attributes[Identifiable] or xref:spec-metamodel/common.adoc#has-semantics-attributes[HasSemantics]. +<> therefore gives an overview on the different constraints and recommendations on the various entities, which implement xref:spec-metamodel/common.adoc#identifiable-attributes[Identifiable] or xref:spec-metamodel/common.adoc#has-semantics-attributes[HasSemantics]. See Annex xref:annex/concepts-aas.adoc#how-are-new-identifiers-created[How Are New Identifiers Created?] for more information on how to create new identifiers and best practices for creating URI identifiers. diff --git a/documentation/IDTA-01001/modules/ROOT/pages/mappings/encodings/valueonly.adoc b/documentation/IDTA-01001/modules/ROOT/pages/mappings/encodings/valueonly.adoc index ff75970cc..71ce50c9a 100644 --- a/documentation/IDTA-01001/modules/ROOT/pages/mappings/encodings/valueonly.adoc +++ b/documentation/IDTA-01001/modules/ROOT/pages/mappings/encodings/valueonly.adoc @@ -45,6 +45,10 @@ The following rules shall be adhered to when serializing a submodel, a submodel * A submodel element is considered a leaf submodel element if it does not contain other submodel elements. A leaf submodel element follows the rules for the different submodel elements considered in the serialization, as described below. If it is not a leaf element, the serialization rules must be transitively followed until the value is a leaf submodel element. +* xref:spec-metamodel/referencing.adoc#Reference[Reference] is serialized in format "Normal". +* xref:spec-metamodel/core.adoc#SpecificAssetId[SpecificAssetId] is serialized in format "Normal". +* xref:spec-metamodel/submodel-elements.adoc#SubmodelElement[SubmodelElement]s without a value are not serialized. + * For each submodel element within the submodel, the submodel collection or submodel list: @@ -52,51 +56,59 @@ If it is not a leaf element, the serialization rules must be transitively follow ** xref:spec-metamodel/submodel-elements.adoc#MultiLanguageProperty[MultiLanguageProperty] is serialized as named JSON object with ${MultiLanguageProperty/idShort} as the name of the containing JSON property. The JSON object contains an array of JSON objects for each language of the _MultiLanguageProperty_ with the language as name and the corresponding localized string as value of the respective JSON property. The language name is defined as two chars according to ISO 639-1. -** xref:spec-metamodel/submodel-elements.adoc#Range[Range] is serialized as named JSON object with $\{Range/idShort} as the name of the containing JSON property. + +** xref:spec-metamodel/submodel-elements.adoc#Range[Range] is serialized as named JSON object with ${Range/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named "min". The second is named "max". -Their corresponding values are $\{Range/min} and $\{Range/max}. -** xref:spec-metamodel/submodel-elements.adoc#File[File] and xref:spec-metamodel/submodel-elements.adoc#Blob[Blob] are serialized as named JSON objects with $\{File/idShort} or $\{Blob/idShort}as the name of the containing JSON property. +Their corresponding values are ${Range/min} and ${Range/max}. + +** xref:spec-metamodel/submodel-elements.adoc#File[File] and xref:spec-metamodel/submodel-elements.adoc#Blob[Blob] are serialized as named JSON objects with ${File/idShort} or ${Blob/idShort}as the name of the containing JSON property. The JSON object contains two JSON properties. -The first refers to the content type named $\{File/contentType} resp. -$\{Blob/contentType}. -The latter refers to the value named "value" $\{File/value} resp. -$\{Blob/value}. +The first refers to the content type named ${File/contentType} resp. +${Blob/contentType}. +The latter refers to the value named "value" ${File/value} resp. +${Blob/value}. The resulting ValueOnly object is indistinguishable whether it contains File or Blob attributes. Therefore, the receiver needs to take the type of the target resource into account. Since the receiver knows in advance if a File or a Blob SubmodelElement shall be manipulated, it can parse the transferred Value-Only object accordingly as a File or Blob object. For Blobs the value attribute is optional (in this case a Blob can be distinguished from a File). -** xref:spec-metamodel/submodel-elements.adoc#SubmodelElementCollection[SubmodelElementCollection] is serialized as named JSON object with $\{SubmodelElementCollection/idShort} as the name of the containing JSON property. -The elements contained within the struct are serialized according to their respective type with $\{SubmodelElement/idShort} as the name of the containing JSON property. -** xref:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList] is serialized as a named JSON array with $\{SubmodelElementList/idShort} as the name of the containing JSON property. + +** xref:spec-metamodel/submodel-elements.adoc#SubmodelElementCollection[SubmodelElementCollection] is serialized as named JSON object with ${SubmodelElementCollection/idShort} as the name of the containing JSON property. +The elements contained within the struct are serialized according to their respective type with ${SubmodelElement/idShort} as the name of the containing JSON property. + +** xref:spec-metamodel/submodel-elements.adoc#SubmodelElementList[SubmodelElementList] is serialized as a named JSON array with ${SubmodelElementList/idShort} as the name of the containing JSON property. The elements in the JSON array are the ValueOnly serializations of the elements contained in the SubmodelElementList while preserving the order, i.e. index n in the JSON array is the ValueOnly serialization of the element at index n of the SubmodelElementList. -** xref:spec-metamodel/submodel-elements.adoc#ReferenceElement[ReferenceElement] is serialized as $\{ReferenceElement/idShort}: $\{ReferenceElement/value} where $\{ReferenceElement/value} is the serialization of the _Reference_ class in format "Normal". -** xref:spec-metamodel/submodel-elements.adoc#RelationshipElement[RelationshipElement] is serialized as named JSON object with $\{RelationshipElement/idShort} as the name of the containing JSON property. + +** xref:spec-metamodel/submodel-elements.adoc#ReferenceElement[ReferenceElement] is serialized as ${ReferenceElement/idShort}: ${ReferenceElement/value} where ${ReferenceElement/value} is the serialization of the _Reference_ class in format "Normal" (see above). + +** xref:spec-metamodel/submodel-elements.adoc#RelationshipElement[RelationshipElement] is serialized as named JSON object with ${RelationshipElement/idShort} as the name of the containing JSON property. The JSON object contains two JSON properties. The first is named "first". The second is named "second". -Their corresponding values are $\{RelationshipElement/first} resp. -$\{Relationship/second}. +Their corresponding values are ${RelationshipElement/first} resp. +${Relationship/second}. The values are serialized according to the serialization of a _ReferenceElement_ (see above). + ** xref:spec-metamodel/submodel-elements.adoc#AnnotatedRelationshipElement[AnnotatedRelationshipElement] is serialized according to the serialization of a _RelationshipElement_ (see above). Additionally, a third named JSON object is introduced with "annotations" as the name of the containing JSON property. -The value is $\{AnnotatedRelationshipElement/annotations}. +The value is ${AnnotatedRelationshipElement/annotations}. The values of the array items are serialized depending on the type of the annotation data element. Annotations are optional. -** xref:spec-metamodel/submodel-elements.adoc#Entity[Entity] is serialized as named JSON object with $\{Entity/idShort} as the name of the containing JSON property. + +** xref:spec-metamodel/submodel-elements.adoc#Entity[Entity] is serialized as named JSON object with ${Entity/idShort} as the name of the containing JSON property. The JSON object contains four JSON properties. -The first is named "statements" $\{Entity/statements} and contains an array of the serialized submodel elements according to their respective serialization mentioned in this clause. +The first is named "statements" ${Entity/statements} and contains an array of the serialized submodel elements according to their respective serialization mentioned in this clause. The second is named "globalAssetId" and the third "specificAssetIds". Either a "globalAssetId" value or a "specificAssetIds" value shall exist. The other attributes are optional. -"globalAssetId" corresponds to a _Reference_ (see above). -"SpecificAssetIds" is an array of objects serializing xref:spec-metamodel/core.adoc#SpecificAssetId[SpecificAssetId]. +"SpecificAssetIds" is an array of objects serializing xref:spec-metamodel/core.adoc#SpecificAssetId[SpecificAssetId]. A single _SpecificAssetId_ in the array corresponds to the serialization of the _SpecificAssetId_ class in format "Normal". -The forth property is named "entityType" and contains a string representation of $\{Entity/entityType}. +The forth property is named "entityType" and contains a string representation of ${Entity/entityType}. _Statements_ and the _entityType_ are optional. -** xref:spec-metamodel/submodel-elements.adoc#BasicEventElement[BasicEventElement] is serialized as named JSON object with $\{BasicEventElement/idShort} as the name of the containing JSON property. -The JSON object contains one JSON property named "observed" with the corresponding value of $\{BasicEventElement/observed} as the standard serialization of the _Reference_ class. + +** xref:spec-metamodel/submodel-elements.adoc#BasicEventElement[BasicEventElement] is serialized as named JSON object with ${BasicEventElement/idShort} as the name of the containing JSON property. +The JSON object contains one JSON property named "observed" with the corresponding value of ${BasicEventElement/observed} as the standard serialization of the _Reference_ class. @@ -174,8 +186,7 @@ Note: the examples are written in RDF/Turtle syntax, and only "Hello" and "Hallo |=== -The following types defined by the XSD and RDF specifications are explicitly omitted for serialization - they are not element of _DataTypeDefXsd_ or _DataTypeDefRdf_: - +The following types defined by the XSD and RDF specifications are explicitly omitted for serialization - they are not element of xref:spec-metamodel/datatypes.adoc#DataTypeDefXsd[DataTypeDefXsd] or xref:spec-metamodel/datatypes.adoc#DataTypeDefRdf[DataTypeDefRdf]: xs:language, xs:normalizedString, xs:token, xs:NMTOKEN, xs:Name, xs:NCName, xs:QName, xs:ENTITY, xs:ID, xs:IDREF, xs:NOTATION, xs:IDREFS, xs:ENTITIES, xs:NMTOKENS, rdf:HTML and rdf:XMLLiteral. ==== @@ -284,6 +295,41 @@ The Format "Normal" in comparison to this Value-Only serialization of the proper } ---- +==== Example Value-Only serialization for a SubmodelElementCollection with non-serialized elements + +The following SubmodelElementCollection in simplified notation + +[source,json,linenums] +---- +{ +myCollection: +{ + "prop1": string, + "capability1": Capability, + "operation1": Operation, + "list": SubmodelElementList(typeofElements:Operation) +} +} +---- + +is serialized to + +[source,json,linenums] +---- + "prop1": "value of prop1" +} +---- + +in Format "Value". + +Since Capability and Operation are not part of Value-Only serialization they are omitted. +Also a List containing elements that are omitted is omitted. This is even the case if the SubmodelElementList is mandatory. + +==== +Note: Similar handling is required in case there are access rules disallowing access to specific submodel elements: +The protected elements shall not be serialized. +==== + ==== Examples Value-Only serialization for all submodel element types In the following examples for Value-Only serializations for all submodel element types are given. diff --git a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/datatypes.adoc b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/datatypes.adoc index 8d0d047cf..bd686a98c 100644 --- a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/datatypes.adoc +++ b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/datatypes.adoc @@ -12,7 +12,7 @@ SPDX-License-Identifier: CC-BY-4.0 == Predefined Simple Data Types -The metamodel of the Asset Administration Shell uses some of the predefined simple data types of the link:https://www.w3.org/XML/Core/[XML Schema Definition] (XSD) as its basic data types footnote:[https://www.w3.org/XML/Core/, former https://www.w3.org/TR/xmlschema-2/#built-in-datatypes]. +The metamodel of the Asset Administration Shell uses some of the predefined simple data types of the XML Schema Definition (XSD) as its basic data types. See <> for an overview of the used types. Their definition is outside the scope of this document. diff --git a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/referencing.adoc b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/referencing.adoc index ef7efbb12..7c7aa6f92 100644 --- a/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/referencing.adoc +++ b/documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/referencing.adoc @@ -14,7 +14,7 @@ include::../includes/constraints.adoc[] == Overview Two kinds of references are distinguished: references to external objects or entities (external reference) and references to model elements of the same or another Asset Administration Shell (model reference). -Model references are also used for metamodel inherent relationships like submodels of an Asset Administration Shell (notation see Annex xref:ROOT:annex/concepts-aas.adoc[]). +Model references are also used for metamodel inherent relationships like submodels of an Asset Administration Shell (notation see Annex xref:ROOT:annex/uml-templates.adoc[]). An external reference is a unique identifier. The identifier can be a concatenation of different identifiers, representing e.g. an IRDI-Path. @@ -58,7 +58,7 @@ h|Explanation h|Type h|Card. a| Type of the reference -Denotes whether reference is an external reference or a model reference +Denotes whether the reference is an external reference or a model reference |xref:ReferenceTypes[ReferenceTypes]|1