Skip to content

Commit

Permalink
Minor Changes (#494)
Browse files Browse the repository at this point in the history 
* remove footnote, seems wrong
remove link, only use link to xmlschema-2

* correct link, was wrong Annex

* grammar

* fix Type Type

* update Clause 7.2.3 with correct link

* correct change log: OPC UA and AutomationML not mentioned any longer

* no update of explanation for external ref for semanticId etc.

* use clause instead of chapter

* merge two similar entries on Value-Only Serialization

* add link instead of old clause number

* remove Table, automatically added

* formatting $\ to $

* add serialization for other elements: Referene and specificAssetId
+ correct globalAssetIds
#401

* #402
Value-Only for List of Operations or Capabilities
  • Loading branch information
@BirgitBoss
BirgitBoss authored Dec 13, 2024
1 parent a1a9205 commit 0d8fd80
Show file tree
Hide file tree
Showing 7 changed files with 83 additions and 36 deletions.
4 changes: 2 additions & 2 deletions documentation/IDTA-01001/modules/ROOT/pages/annex/uml-templates.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ The following kinds of _Types_ are distinguished:

** _<Class>:_ 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[].
** _<Primitive>: 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].
** _<Primitive>:_ 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]
** _<Enumeration>:_ Type is an enumeration, see <<template-for-enumerations>>

_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.
Expand Down Expand Up @@ -89,7 +89,7 @@ This would be an invalid reference for "ModelReference<Submodel>" because it ref
(Submodel)https://example.com/aas/1/1/1234859590, (Property)temperature
....

If class type equal to "ModelReference<Referable>", 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<Referable>", 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]
....
Expand Down
2 changes: 1 addition & 1 deletion documentation/IDTA-01001/modules/ROOT/pages/annex/usage-metamodel.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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\]].
Expand Down
9 changes: 5 additions & 4 deletions documentation/IDTA-01001/modules/ROOT/pages/changelog.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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])
Expand Down
4 changes: 2 additions & 2 deletions documentation/IDTA-01001/modules/ROOT/pages/general.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<table-life-cycle-phases-and-roles-of-type-and-instance-assets>> 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.
<<table-life-cycle-phases-and-roles-of-type-and-instance-assets>> 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.
Expand Down Expand Up @@ -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 <<table-elements-with-allowed-identifying-values>> 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].
<<table-elements-with-allowed-identifying-values>> 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.

Expand Down
94 changes: 70 additions & 24 deletions documentation/IDTA-01001/modules/ROOT/pages/mappings/encodings/valueonly.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -45,58 +45,70 @@ 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:


** xref:spec-metamodel/submodel-elements.adoc#Property[Property] is serialized as ${Property/idShort}: ${Property/value} where ${Property/value} is the JSON serialization of the respective property’s value in accordance with the data type to value mapping (see table after this section).
** 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.



Expand Down Expand Up @@ -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.

====
Expand Down Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion documentation/IDTA-01001/modules/ROOT/pages/spec-metamodel/datatypes.adoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<table-simple-data-types>> for an overview of the used types.
Their definition is outside the scope of this document.

Expand Down
Loading

0 comments on commit 0d8fd80

Please sign in to comment.