diff --git a/schemas/json/README.md b/schemas/json/README.md index 3b0e74194..9177bf9c1 100644 --- a/schemas/json/README.md +++ b/schemas/json/README.md @@ -1,236 +1,3 @@ # JSON -[JavaScript Object Notation (JSON)] is a popular serialization format. Beside XML and -RDF, it is an "official" serialization format for models of Asset Administration -Shells (AAS). Since JSON is a very versatile format, there are many ways how we could -map an AAS model to it. In this document, we explore our particular design of the -serialization schema based on [JSON schema 2019-09], and explain in detail the rules how -we mapped the [AAS meta-model] to it. - -[JavaScript Object Notation (JSON)]: https://www.json.org - -[JSON schema 2019-09]: https://json-schema.org/specification-links.html#2019-09-formerly-known-as-draft-8 - -[AAS meta-model]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf - -## Top-Level Structure - -The root of our serialization is a JSON object representing the instance -of [Environment]. This environment contains three aggregations, corresponding to -all [Identifiable] classes: - -* [AssetAdministrationShell]'s, -* [Submodel]'s, and -* [ConceptDescription]'s. - -[Environment]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=80 - -[Identifiable]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=52 - -[AssetAdministrationShell]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=58 - -[Submodel]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=62 - -[ConceptDescription]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=79 - -The JSON properties of the environment correspond to these three aggregations. - -To simplify exploration of the JSON data, identifiable instances are only available at -the level of the environment, and nowhere else. - -## Mapping Rules - -### Classes to JSON definitions - -For each class of the [AAS meta-model], we provide [a definition] in the JSON schema. -The instances of the classes, abstract and concrete alike, are modeled as [JSON objects] -. - -[a definition]: https://json-schema.org/understanding-json-schema/structuring.html#defs - -[JSON objects]: https://json-schema.org/understanding-json-schema/reference/object.html - -### UML properties to JSON properties - -The class properties of the meta-model (attributes and aggregations) correspond directly -to [JSON properties]. - -[JSON properties]: https://json-schema.org/understanding-json-schema/reference/object.html#properties - -Optional attributes, *i.e.*, the attributes with the cardinality ``0..1``, are modeled -as [non-required properties]. - -[non-required properties]: https://json-schema.org/understanding-json-schema/reference/object.html#required-properties - -Aggregations, *i.e.*, the properties with the cardinality ``0..*``, ``1..*`` *etc.*, are -modeled as [JSON arrays]. - -[JSON arrays]: https://json-schema.org/understanding-json-schema/reference/array.html - -We explicitly forbid empty JSON arrays to avoid confusion about properties which have -cardinality ``0..*``. Namely, an empty array is semantically equal to an omitted -attribute (according to the meta-model). Thus, the JSON property representing an -aggregation attribute must be omitted if the aggregation is empty. - -In UML, it is the convention to name associations and aggregations in singular form. The -cardinality is to be taken into account to decide on whether there are none, a single or -several elements in the corresponding association or aggregation. In JSON it is best -practice to use plural form for array in class properties. The singular name is used for -its descriminator (see section on decriminators). Typically the plural name is derived -by just adding an "s" to the name. For example, ``submodelElements`` instead -of ``submodelElement`` in case of [Submodel] class. - -If plural form made no sense for a property, we kept it as-is (*e.g.*, `isCaseOf`). The -full list of exceptions is available [as code in aas-core-meta]. - -[as code in aas-core-meta]: https://github.com/aas-core-works/aas-core-meta/blob/02712deeff530a75fda99aee25961aa4ea38a420/tests/test_v3.py#L1069 - -### Primitive attribute values - -The UML specification uses XSD types. For the [mapping of XSD to JSON types] please -refer to [Part 2 of the series of the Asset Adminsistration Shell]. - -There are the following exceptions: - -[Property]/``value`` and [Range]/``min`` and [Range]/``max`` are mapped to a JSON -string. The type it needs to be converted to by the data consumer is declared -in [Property]/``valueType`` or [Range]/``valueType``, resp. - -Primitive type [BlobType] (group of ``byte``s) is mapped to a JSON string with base64 -encoding. - -Note: in valueOnly Format of [Part 2 of the series of the Asset Adminsistration Shell] -value has the JSON type as declared in [Property]/``valueType`` taking -the [mapping of XSD to JSON types] into account. - -[Part 2 of the series of the Asset Adminsistration Shell]: https://industrialdigitaltwin.org/en/wp-content/uploads/sites/2/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf - -[mapping of XSD to JSON types]: https://industrialdigitaltwin.org/en/wp-content/uploads/sites/2/2023/04/IDTA-01002-3-0_SpecificationAssetAdministrationShell_Part2_API.pdf#page=96 - -[JSON strings]: https://json-schema.org/understanding-json-schema/reference/string.html - -[Property]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=74 - -[Range]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=75 - -[BlobType]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=96 - -[JSON number]: https://www.rfc-editor.org/rfc/rfc4627#section-2.4 - -[JSON boolean]: https://json-schema.org/understanding-json-schema/reference/boolean.html - -[XSD types]: https://www.w3.org/TR/xmlschema-2 - -[5.7.12 Primitive and Simple Data Types]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=96 - -#### Hint: Round-Trip Conversions - -Round-trip conversions XML to JSON to XML or RDF to JSON to RDF may not result in the -original file. - -The result of a model saved as XML is different to the model saved as JSON. For example, -if the user typed in `1` for a boolean UML attribute (e.g. for ``SubmodelElementList`` -/``orderRelevant``) -in the editor, saved the model as JSON and opened it again, she would suddenly -see `true` instead of `1` -(since the JSON library would silently convert `1` to a [JSON boolean] `true`). - -### Inheritance - -The inheritance relationships between the classes are modeled using [allOf composition]. -While JSON schema knows no inheritance, we enforce through ``allOf`` that all the -properties of the parent are defined in the descendants. - -[allOf composition]: https://json-schema.org/understanding-json-schema/reference/combining.html#allof - -### Discriminator - -Many attributes in the meta-model refer to an abstract class. When we de-serialize such -attributes, we need to know the concrete class at runtime, since otherwise the -de-serialization algorithm would not know how to interpret the properties of the object. - -For example, consider the attribute [Submodel] which contains instances -of [SubmodelElement]. When the de-serializer encounters the -property ``submodelElements`` as an array and starts de-serializing its items, how can -it know which constructor to call to parse the item? This necessary nugget of -information is commonly called "discriminator" (*e.g.*, -see [OpenAPI 3 specification on polymorphism]). - -[SubmodelElement]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=63 - -[OpenAPI 3 specification on polymorphism]: https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/ - -We define the discriminator for our serialization as an additional property, `modelType` -, which do not correspond to any attribute in the meta-model. Every class which has one -or more descendants will have the discriminator `modelType` in its definition. - -When a deserializer needs to de-serialize an instance of an abstract class, it can do so -by dispatching the de-serialization to the appropriate de-serialization method based -on `modelType`. - -### Enumerations - -The enumerations of the meta-model are directly mapped -to [enumerated values in JSON schema]. Each enumeration is defined separately, and we do -not in-line enumerations for readability. - -[enumerated values in JSON schema]: https://json-schema.org/understanding-json-schema/reference/generic.html#enumerated-values - -Enumerations which are not directly used in the schema are omitted. For example, subsets -of [KeyTypes] are omitted since only [KeyTypes] is used to define value of an attribute. - -[KeyTypes]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=85 - -### Embedded Data Specifications - -The meta-model defines data specifications in abstract (see -Section [6 Predefined Data Specification Templates]). However, the meta-model omits data -specifications in an [Environment], and data specifications are intentionally -non-identifiable. - -[6 Predefined Data Specification Templates]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=106 - -For practical applications, we need to access them *somehow*. Therefore, the meta-model -mandates to embed them in serializations (see -Section [7.2.5 Embedded Data Specifications]). - -[7.2.5 Embedded Data Specifications]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=114 - -We consequently embed the data specifications by adding `embeddedDataSpecifications` -property to the definition corresponding to [HasDataSpecification], and deliberately -omit the attribute [HasDataSpecification]/``dataSpecification`` in the schema. - -[HasDataSpecification]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=48 - -## Examples - -Examples of the JSON serializations can be found in [schemas/json/examples/](examples) -folder. - -## Background - -### From Manual Transcription ... - -The serialization to and from JSON changed over the course of different versions of the -meta-model. Originally, the schema had been manually designed, where a group of authors -combed "the book" and manually transcribed it to JSON schema. This was obviously -error-prone as it often caused mismatches between other serializations (*e.g.*, XML and -RDF), contained inconsistencies *etc.* - -### ... to Automatic Generation - -We eventually moved over to generate the serialization schemas based on a -single-point-of-truth. The current source is [aas-core-meta], a domain-specific Python -representation of the meta-model. The schemas are generated using [aas-core-codegen], a -translating tool which transpiles aas-core-meta into different schemas and other targets -such as SDKs. - -[aas-core-meta]: https://github.com/aas-core-works/aas-core-meta - -[aas-core-codegen]: https://github.com/aas-core-works/aas-core-codegen - -While this approach reduced the rate of errors significantly, it also imposed certain -limits on our schema design. For example, the classes and enumerations are now -programmatically mapped to JSON definitions, allowing for no exceptions. Where we could -in-line some of them for better readability, we are now forced to stick with the -programmatic definitions. +Refer to the [json.adoc](../documentation/IDTA-01001/modules/ROOT/pages/mappings/formats/json.adoc) for detailed information. \ No newline at end of file diff --git a/schemas/rdf/README.md b/schemas/rdf/README.md index 62701ccaf..9162e553a 100644 --- a/schemas/rdf/README.md +++ b/schemas/rdf/README.md @@ -1,104 +1,3 @@ # Resource Description Framework -The Resource Description Framework ([RDF](https://www.w3.org/TR/rdf11-primer/)) -is recommended standard of the W3C to unambiguously model and present semantic data. RDF -documents are structured in the form of triples, consisting of subjects, relations and -objects. The resulting model is often interpreted as a graph, with the subject and -object elements as the nodes and the relations as the graph edges. - -RDF is closely related to Web standards, illustrated by the fact that all elements are -encoded using (HTTP-)URIs. As a common practice, the provision of additional information -at the referenced location of an RDF entity directly allows the interlinking of entities -based on the Web. This process, the following of links in order to discover related -information, is called dereferencing a resource and is supported by any browser or web -client. As the AAS namespace (`https://admin-shell.io/aas///`) is not -yet equipped with an hosting server, the dereferencing of the AAS entities is not -possible yet. Nevertheless, the current state already allows the connection of -distributed data sources through the Web, a mechanism known -as [Linked Data](https://www.w3.org/standards/semanticweb/data). Connecting the -capabilities of Linked Data with the expressiveness of the Asset Shell is one motivation -for the RDF serialization. - -In addition, RDF is the basis of a wide range of logical inference and reasoning -techniques. Vocabularies like RDF Schema ([RDFS](https://www.w3.org/TR/rdf-schema/)) and -the Web Ontology Language ([OWL](https://www.w3.org/TR/owl2-overview/)) combine the -graph-based syntax of RDF with formal definitions and axioms. This allows automated -reasoners to understand the relation between entities to some extent and draw -conclusions. - -Combining both worlds, the RDF mapping of the Asset Administration Shell can provide the -basis for complex queries and requests. SPARQL, the standard query language for the -Semantic Web, can combine reasoning features with the integration of external data -sources. In order to benefit of these abilities, the AAS requires a clear scheme of its -RDF representation. In the following, the necessary transformation rules are presented, -followed by an illustration of relevant parts of the scheme and an example. The -complete [data model](rdf-ontology.ttl) together with the [schema](shacl-schema.ttl) are -listed in this repository. - -## RDF Mapping Rules - -The concepts of the RDF and the derived RDF serialization of the AAS are explained by -the mapping rules. These rules are implemented by -the [generators](https://github.com/aas-core-works/aas-core-codegen) used to create the -ontology and shacl files based on the independent -project [aas-core-works](https://github.com/aas-core-works/). The main design rules the -following: - -- The default serialization format is Turtle - also for the ontology and the shapes. - However, several equivalent serializations exist for RDF. Among them, the Turtle - syntax is regarded as the most appropriate compromise between readability and - tool-support. Other formats (RDF/XML, JSON-LD, N3, etc.) can be used without any loss - of information. -- [Shape Graphs](./shacl-schema.ttl) represent the validation schema. The data model - itself is an [RDF ontology](./rdf-ontology.ttl). As RDF itself is following the - open-world-assumption, [SHACL](https://www.w3.org/TR/shacl/) constraints are necessary - in order to enable schema validation. Similarly to XSD for XML, the SHACL format can - be used to describe constraints (called shapes) of RDF graphs. -- Every entity is encoded as either an IRI or a Literal. RDF uses IRIs for both entities - and relations. If no IRI is predefined, a globally unique IRI is generated. Primitive - values are encoded as Typed Literals. -- Entities are enhanced with well-known RDF attributes. Interoperability of concepts and - attributes is the main advantage of the RDF mapping. Therefore, applying common - attributes (`rdf:type` (similar to `modelType` discriminator in JSON), `rdfs:label`, - and `rdfs:comment`) enables the usage of standard tools and interfaces. -- Repeating elements are described once and then linked using their IRI identifier. If a - distinct element appears more than one time in the original model but in a different - context, for instance in more than one submodel, the RDF entity represents the - combination of all attributes. -- Multilanguage Strings are split into distinct language strings (`rdf:langString`). - Objects are expected to contain a singular information entity, and the currently - available tools would not recognize the AAS LangString pattern. -- Multiple object values are represented by repeating the property, one for each value - object. -- Abstract AAS classes are modeled in the ontology, nevertheless, using them leads to - validation errors in the shapes. RDF does not contain a concept for abstract classes, - therefore custom checks using SPARQL queries are supplied. - -## Example Overview - -RDF is often regarded as a graph model, as it provides the flexibility to interlink -entities at any stage. In the following, -the [complete example](./examples/Complete_Example.ttl) is originally provided in Turtle -but accompanied with visualizations of the represented graph (see Fig. 1): Attributes -referencing non-literal values are shown as directed links while Literal values are -drawn together with the corresponding entity itself. In order to increase readability, -the namespace declaring sections are omitted. The complete example with all namespaces -can be found in the [example folder](examples). One can see the additionally inserted -triples for `rdf:type`, `rdfs:label`, and `rdfs:comment` as determined by Rule 4. The -first attribute states the instance’ class. The second provides its commonly used name, -for instance based on the idShort attribute. `rdfs:comment` supplies a short description -about the regarded entity, based on the description value. The generally available -tools, for instance the open source tool [Protégé](https://protege.stanford.edu), render -these attributes and display the correct class hierarchy, render the elements with their -labels or supply short explanations based on the comments. - -![Simplified graph of the core classes in the example](../rdf/media/aas-rdf-graph.png) - -___Figure 1: Simplified graph of the core classes in the example___ - -A comprehensive set of generated examples is also provided in the -subfolder [examples/generated](./examples/generated), always containing a complete and a -minimal version of each class. The files have been created using -the [aas-core3.0-testgen](https://github.com/aas-core-works/aas-core3.0-testgen) -project to simplify the maintenance process and to stick directly to the efforts made -at [aas-core-meta](https://github.com/aas-core-works/aas-core-meta). \ No newline at end of file +Refer to the [rdf.adoc](../documentation/IDTA-01001/modules/ROOT/pages/mappings/formats/rdf.adoc) for detailed information. \ No newline at end of file diff --git a/schemas/xml/README.md b/schemas/xml/README.md index 84090b830..c8193405e 100644 --- a/schemas/xml/README.md +++ b/schemas/xml/README.md @@ -1,525 +1,3 @@ # XML -Extensible Markup Language ([XML]) is a popular serialization format for data exchange -and storage. - -[XML]: https://www.w3.org/TR/2008/REC-xml-20081126/ - -While there are many possibilities to represent a model of an Asset Administration Shell -in XML, we provide our "official" XML schema definition ([XSD]) to foment -interoperability between different tools and systems. - -[XSD]: https://www.w3.org/TR/xmlschema-0/ - -Below we explain in more detail how our schema is constructed, point the user to the -examples and finally give some background information on our particular schema design. - -## Top-Level Structure - -The root element of our XML is an XML element representing the instance of [Environment] -. This environment contains three aggregations, corresponding to all [Identifiable] -classes: - -* [AssetAdministrationShell]'s, -* [Submodel]'s, and -* [ConceptDescription]'s. - -[Environment]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=80 - -[Identifiable]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=52 - -[AssetAdministrationShell]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=58 - -[Submodel]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=62 - -[ConceptDescription]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=79 - -To simplify exploration of the XML data, identifiable instances are only available at -the level of the environment, and nowhere else. - -We now continue to see how to serialize the instances and their properties. - -## Mapping Rules - -Building blocks of an XML document include only [XML elements], [XML attributes] -and [text enclosed in an element]. XML elements can nest children elements. Using these -building blocks, we map an AAS model to XML. - -[XML elements]: https://www.w3schools.com/xml/xml_elements.asp - -[XML attributes]: https://www.w3schools.com/xml/xml_attributes.asp - -[text enclosed in an element]: https://www.w3schools.com/xml/xml_elements.asp - -### UML Property to XML Element - -Before we look into how to represent instances of classes, let us start bottom-up and -see first how individual properties are represented. - -We represent each property of a class with an XML element whose name corresponds to the -property in the meta-model. The name is given in camel-case where all abbreviations are -left as capitalized (``dataSpecificationIec61360`` instead -of ``dataSpecificationIEC61360``). - -It is common in UML to use singular form for aggregations, which is the case for the -meta-model. This is, however, in contrast to programming code, where plural form for -sequences is common. Since the naming of XML elements has direct influence on the -programming code, we name the properties in plural form diverging from the name in the -meta-model. For example, ``submodelElements`` instead of ``submodelElement`` in case -of [Submodel/submodelElement] property in the meta-model. - -[Submodel/submodelElement]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=63 - -In cases where plural form made no sense for a property, we kept it as-is in singular -form (*e.g.*, `isCaseOf`). The full list of exceptions is -available [as code in aas-core-meta]. - -[as code in aas-core-meta]: https://github.com/aas-core-works/aas-core-meta/blob/02712deeff530a75fda99aee25961aa4ea38a420/tests/test_v3.py#L1069 - -### Why no XML attributes? - -While some meta-model properties are indeed very apt to be succinctly represented as XML -attributes, we decided *not* to use XML attributes at all for three reasons. - -First, the XML attribute must be a string, and therefore does not allow for structured -data to be represented with it. As the meta-model evolves, we need to be able to -gracefully evolve the schema with as little breakages as possible. An XML attribute puts -a limit in so far that an attribute can only be represented as string. Moreover, as the -schema evolves, making [diff]'s is important to trace the changes. This is much harder -when the attributes switch from an XML attribute to an XML element. - -[diff]: https://en.wikipedia.org/wiki/Diff - -Second, many classes contain a mix of primitive properties and structured properties. If -we allowed XML attributes, the former would be represented as XML attributes, while the -latter would be represented as XML elements. This leads to confusion where the writer is -forced to go back and forth in the specification, and always double-check whether a -property should be represented as an XML attribute or an XML element. - -Third, we automatically generate the schema from a machine-readable meta-model -representation (see Section [Background] below). The mix of XML attributes and elements -would have complicated the code and prolonged the development. - -[Background]: #Background - -We finally decided that the drawbacks outlined above outweighed the advantage in form of -succinct representation. - -### Optional Properties - -If a property has cardinality ``0..1`` or ``0..*`` and is not specified in the instance, -the element is simply omitted. - -### Properties of Simple Data Types - -The property values given in the meta-model as simple data types (see -Section [5.7.12 Primitive and Simple Data Types] of the meta-model) are serialized as -text enclosed in the XML element corresponding to the property. Please see -Section [Why no XML attributes?] on why we do not serialize them as XML attributes. - -[5.7.12 Primitive and Simple Data Types]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=96 - -[Why no XML attributes?]: #why-no-xml-attributes - -The byte arrays (``BlobType`` in meta-model) are serialized as Base64-encoded text. - -Simple type ``rdf:langString`` is serialized as if it were a proper meta-model class -with properties ``language`` and ``text``. See the following -Section [Instances of Classes as Attribute Values] about how to serialize instances of -classes in general as that section directly applies to ``rdf:langString``. - -[Instances of Classes as Attribute Values]: #Instances-of-Classes-as-Attribute-Values - -### Instances of Classes as Property Values - -To serialize instances of meta-model classes as values of properties, we need to nest -them somehow within the XML element corresponding to the property. This is not as -trivial as it seems. - -If the property type is a concrete or abstract class with descendants, the deserializer -needs to know the exact concrete class at the time of de-serialization. However, this -information is obviously missing in the meta-model. For example, the -property [Submodel/submodelElement] tells the deserializer that its items are instances -of [SubmodelElement], but the deserializer does not know which *concrete* -deserialization method to apply to understand the nested XML data: is it [Property] -, [Range] or some other descendant of [SubmodelElement]? - -[Submodel/submodelElement]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=63 - -[SubmodelElement]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=63 - -[Property]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=74 - -[Range]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=75 - -Therefore, the information about the concrete type of the serialized instance must be -encoded somehow in XML when the type in the meta-model is too vague. This nugget of -information is usually called a *discriminator* (*e.g.*, -see [OpenAPI 3 specification on polymorphism]). - -[OpenAPI 3 specification on polymorphism]: https://swagger.io/docs/specification/data-models/inheritance-and-polymorphism/ - -On the other hand, when the meta-model mandates the type of property as a concrete class -without descendants, the deserializer needs no additional information as the -deserialization method is given by the meta-model. There is thus no need to include the -discriminator in the serialization, and a redundant discriminator would only clutter the -XML document. - -We therefore distinguish two serializations of instances: one with discriminator, and -one without, respectively. - -#### Instances Serialized with Discriminator - -We use the XML element named according to the concrete class at the serialization as the -discriminator. The properties of the instance are nested below this discriminator XML -element. - -Let us make an example. The example will be agnostic of the particular meta-model -version, so that it can age well across different versions. We fantasize a meta-model -class `SomeAbstractClass` and assume it has two descendant classes, `SomeConcreteClass` -and `AnotherConcreteClass`. Let us assume yet another class, `YetAnotherClass`, entails -the property `someProperty` of type `SomeAbstractClass`. - -Here is how the XML structure corresponding to `YetAnotherClass/someProperty` would look -like in this fantasized case, where the value is an instance of `SomeConcreteClass`: - -```xml - - - - - - -``` - -If the value is an instance of `AnotherConcreteClass`, the serialization becomes: - -```xml - - - - - - -``` - -The abstract class, `SomeAbstractClass`, does not show up in the serialization at all, -as it is redundant information. - -While this approach is succinct in terms of additional XML elements, but it comes with a -caveat. Namely, if we introduce descendants to `AnotherConcreteClass`, the -property `someProperty` becomes polymorph, and we need to introduce -backwards-incompatible schema changes to allow for the [discriminator]. - -#### Instances Serialized without Discriminator - -If the concrete type of the property at deserialization is unambiguous by the -meta-model, we omit the discriminator to reduce the clutter. The instance is simply -serialized as a sequence of XML elements corresponding to its properties. - -Let us fantasize yet another example, similar to the one in -Section [Instances Serialized with Discriminator]. We will again draw an example such -that it is agnostic of meta-model version for better evolution of this Readme. Assume a -class `SomeClass` with a property `SomeClass/someProperty`. Now imagine the type -of `someProperty` to be the class `AnotherClass`. The class `AnotherClass` has -properties `AnotherClass/anotherProperty` and `AnotherClass/yetAnotherProperty`. The -class `AnotherClass` has no descendants, so the concrete type -of `SomeClass/someProperty` is unambiguous. - -[Instances Serialized with Discriminator]: #Instances-Serialized-with-Discriminator - -Here is how the XML structure would look like: - -```xml - - - - - - - - - -``` - -The type information about `AnotherClass` is omitted, as the type of -the `SomeClass/someProperty` is fixed in the meta-model. - -### Properties as Aggregations - -Many properties in the meta-model do not represent a single value (be it primitive or -structured as a class), but aggregate instances of meta-model classes. For -example, [Submodel/submodelElement] aggregates instances of [SubmodelElement]'s. - -If we just concatenated all the properties of the instances, we would not know which -property belongs to which instance (or such distinction would be complicated). We need a -delimiter! - -Following the approach described in Section [Instances Serialized with Discriminator], -we delimit the instances simply by nesting them beneath the discriminator elements. If -the type of the list items is a concrete class, we nest beneath the discriminator -element regardless. - -For example, here is an XML snippet of an example submodel elements, where the first -element is a [Property], the second one is a [Range] and the third is a [Property]: - -```xml - - - - - - - - - - - - - - - - - - - -``` - -We explicitly forbid empty lists in XML to avoid confusion about properties of -cardinality ``0..*``. Namely, an empty list is semantically equal to an omitted -property (according to the meta-model). Thus, the XML element representing an -aggregation must be omitted if the aggregation is empty. - -The following snippet is therefore invalid: - -```xml - - - - - -``` - -... and should be written as: - -```xml - - - - -``` - -### Order of the Properties - -We fixed the order of the properties to match the meta-model for readability. - -This is reflected in usage of `xs:sequence` throughout the XML schema. - -### Enumerations - -Enumerations are serialized according to the exact values of enumeration literals in the -meta-model as text. - -For example, the enumeration literal [EntityType/CoManagedEntity] is serialized -as ``CoManagedEntity``, while the literal [Direction/input] as ``input``. - -[EntityType/CoManagedEntity]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=70 - -[Direction/input]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=66 - -### Embedded Data Specifications - -There is an abstract definition of data specifications as templates in the meta-model ( -see Section [6 Predefined Data Specification Templates]). This definition does not -specify, though, how to access them from within an [Environment], which is a requirement -for many systems. To address this practical issue, the meta-model indicates that they -should be embedded in serializations (see Section [7.2.5 Embedded Data Specifications]). - -[6 Predefined Data Specification Templates]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=106 - -[7.2.5 Embedded Data Specifications]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=114 - -We therefore add additional XML element, named `embeddedDataSpecifications`, in the XML -representations of [HasDataSpecification] class, and omit `dataSpecification` property -by design. The embedded data specifications are serialized just as all the other classes -of the meta-model, following the procedure outlined above. - -[HasDataSpecification]: https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01001-3-0_SpecificationAssetAdministrationShell_Part1_Metamodel.pdf#page=48 - -### Namespace - -The XML elements representing the AAS model are explicitly required to live in our -namespace. The namespace corresponds to the version of the meta-model. - -For example, the serialization for the meta-model `V3.0RC02` lives in the -namespace `https://admin-shell.io/aas/3/0/RC02`. - -## Structure of the Schema - -XML schemas tend to grow very complex, very quickly. Our schema is no exception. While -we described so far how an XML document looks like for a concrete AAS model, let us -briefly give you an overview of the schema beneath it. - -At this point, we only outline its structure in broad brushes. Please refer to the -actual file [schema/xml/AAS.xsd](AAS.xsd) for more details. - -For each class, we define a `xs:group` which lays out the order (as a -nested `xs:sequence`) and type of the XML elements corresponding to the properties of -the class. The inheritance is dealt by nesting an additional `xs:group` element within -the sequence with the `ref` attribute. - -The individual properties are defined with `xs:element` in the `xs:sequence`. - -For example: - -```xml - - - - - - - - - - - - - - -``` - -For each class, we define a `xs:complexType`, name it with an `_t` prefix and refer the -complex type to the corresponding group. The complex types are necessary so that we can -use them to specify aggregations. - -For example, here is the definition of `submodel_t`: - -```xml - - - - - - -``` - -Here it is used in the definition of the aggregation: - -```xml - - - - - - - - - - - - -``` - -If a class has one or more descendants, we define an `xs:group` with the `_choice` -suffix. This is necessary so that we can enforce a closed set of concrete classes at the -de/serialization. In particular, we want to ensure that the discriminator is given -correctly (see Section [Instances Serialized with Discriminator]). - -Here is an example of a choice: - -```xml - - - - - - - - - -``` - -Here the choice is enforced in another group: - -```xml - - - - - - - - - - - - - -``` - -## Examples - -Examples of the XML serializations can be found in [schemas/xml/examples/](examples) -folder. - -## Background - -### Handwritten Schema - -When we started with the project, the schema had been manually written. One or two -schema designers would sit down, follow the book and translate it into XML schema by -best effort. This allowed for a lot of artistic freedom, but eventually caused problems -due to mismatches with other serializations or internal inconsistencies. Especially as -the meta-model evolved, maintaining the schema and keeping it up-to-date with the -meta-model proved to be difficult. - -### Generated Schema - -While the handwritten schema is arguably elegant, the maintenance is too demanding. -Therefore, we developed a schema generator based on the machine-readable representation -of the meta-model. The generator is provided in [aas-core-codegen] project, while the -meta-model lives in [aas-core-meta]. - -[aas-core-meta]: https://github.com/aas-core-works/aas-core-meta - -[aas-core-codegen]: https://github.com/aas-core-works/aas-core-codegen - -This allowed us to evolve the XML schema more quickly while keeping it in sync with -other serialization schemas and SDKs. However, we had to give up on elegant parts of the -schema, and had to straightjacket the schema into form that can be programmatically -generated. For example, all properties are serialized as XML elements, and we could not -use XML attributes. +Refer to the [xml.adoc](../documentation/IDTA-01001/modules/ROOT/pages/mappings/formats/xml.adoc) for detailed information.