Integrate XML/JSON/RDF adocs in mappings.adoc

documentation/IDTA-01001/modules/ROOT/pages/mappings/formats/json.adoc

@@ -1,14 +1,23 @@
-== JSON
+== Format "Normal" in JSON
 include::../links.adoc[]
 
-https://www.json.org[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).
+JSONfootnote:[see: https://tools.ietf.org/html/rfc8259 or https://www.ecma-international.org/publications/standards/Ecma-404.htm] (JavaScript Object Notation) is a further serialization format that serializes the metamodel of an Asset Administration Shell for import and export scenarios.
+
+Additionally, JSON format is used to describe the payload in the http/REST API for active Asset Administration Shells xref:bibliography.adoc#bib37[[37\]].
+
 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
+Below we explore our particular design of the serialization schema based on
 https://json-schema.org/specification-links.html#2019-09-formerly-known-as-draft-8[JSON schema 2019-09]
 , and explain in detail the rules how we mapped the AAS metamodel to it.
 
+====
+Note 1: the JSON schema (.json files) is maintained in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder {json-folder}[schemas\json]
+====
+
+====
+Note 2: example files can be found in the repository "aas-specs" in the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder {json-examples}[schemas\json\examples]
+====
+
 === Top-Level Structure
 
 The root of our serialization is a JSON object representing the instance of

documentation/IDTA-01001/modules/ROOT/pages/mappings/formats/rdf.adoc

@@ -1,28 +1,36 @@
-== Resource Description Framework
+== Format "Normal" in RDF
 include::../links.adoc[]
 
-The Resource Description Framework (https://www.w3.org/TR/rdf11-primer/[RDF]) 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 Resource Description Framework (RDF) xref:bibliography.adoc#bib32[[32\]] is the 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/<version>/<revision>/`) is not yet equipped with a 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 https://www.w3.org/standards/semanticweb/data[Linked Data].
-Connecting the capabilities of Linked Data with the expressiveness of the Asset Shell is one motivation for the RDF serialization.
+RDF is closely related to web standards, illustrated by the fact that all elements are encoded using (HTTP-)IRIs.
+As a common practice, the provision of additional information at the referenced location of an RDF entity directly allows the interlinking of entitiesfootnote:[Note: entity as a generic term and entity as a specific submodel element subtype need to be distinguished.] based on the web.
+This process – following links in order to discover related information – is called dereferencing a resource and is supported by any browser or web client.
+Connecting distributed data sources through the web in the described manner is referred to by the term "Linked Data".
+Connecting the available resources and capabilities of linked data with the expressiveness of the Asset Administration 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 (https://www.w3.org/TR/rdf-schema/[RDFS]) and the Web Ontology Language (https://www.w3.org/TR/owl2-overview/[OWL]) combine the graph-based syntax of RDF with formal definitions and axioms.
+Vocabularies like RDF Schema (RDFS) and the Web Ontology Language (OWL) 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.
+Combining both features, 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 order to benefit of these abilities, the Asset Administration Shell 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}[rdf-ontology.ttl]) together with the schema ({shacl-schema}[shacl-schema.ttl]) are listed in this {git-repo}[GitHub Repository] in the {rdf-folder}[/schemas/rdf] folder.
 
+====
+Note 1: the RDF scheme/OWL files (.ttl files) are maintained in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder {rdf-folder}[/schemas/rdf]
+====
+
+====
+Note 2: example files can be found n the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder {rdf-examples}[/schemas/rdf/examples]
+====
+
+
 === RDF Mapping Rules
 
 The concepts of the RDF and the derived RDF serialization of the AAS are explained by the mapping rules.

documentation/IDTA-01001/modules/ROOT/pages/mappings/formats/xml.adoc

@@ -1,12 +1,24 @@
-== XML
+== Format "Normal" in  XML
 include::../links.adoc[]
 
-Extensible Markup Language (https://www.w3.org/TR/2008/REC-xml-20081126/[XML]) is a popular serialization format for data exchange and storage.
+The metamodel of an Asset Administration Shell needs to be serialized for import and export scenarios.
+XML is a possible serialization format.
+
+eXtensible Markup Language (XMLfootnote:[see: https://www.w3.org/TR/2008/REC-xml-20081126/]) is very well suited to derive information from an IT system, e.g. to process it manually and then feed it into another IT system.
+XML provides the possibilities of scheme definitions, which can be used to syntactically validate the represented information in each step.
 
 While there are many possibilities to represent a model of an Asset Administration Shell in XML, we provide our "official" XML schema definition (https://www.w3.org/TR/xmlschema-0/[XSD]) to foment interoperability between different tools and systems.
 
 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.
 
+====
+Note 1: the xml schema (.xsd files) is maintained in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder {xml-folder}[schemas\xml]
+====
+
+====
+Note 2: example files can be found in the repository "aas-specs" in the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]]  in folder : {xml-examples}[schemas\xml\examples]
+====
+
 === Top-Level Structure
 
 The root element of our XML is an XML element representing the instance of

documentation/IDTA-01001/modules/ROOT/pages/mappings/links.adoc

@@ -1,7 +1,8 @@
 :git-repo: https://github.com/admin-shell-io/aas-specs/tree/IDTA-01001-3-1_working
 
 // JSON schema links
-:json-examples: {git-repo}/schemas/json/examples
+:json-folder: {git-repo}/schemas/json
+:json-examples: {json-folder}/examples
 
 // RDF schema links
 :rdf-folder: {git-repo}/schemas/rdf

documentation/IDTA-01001/modules/ROOT/pages/mappings/mappings.adoc

@@ -19,6 +19,7 @@ idShortPath.adoc
 ////
 [[part1-mappings]]
 = Mappings (normative)
+include::links.adoc[]
 
 == Technical Data Formats
 
@@ -32,7 +33,7 @@ The Asset Administration Shell supports three widely used formats:
 * RDF
 
 ====
-Note: the mapping specifications and schemata for XML, JSON and RDF are part of https://github.com/admin-shell-io/aas-specs.
+Note: the mapping specifications and schemata for XML, JSON and RDF are part of {git-repo}.
 ====
 
 == Content Format Types
@@ -101,79 +102,8 @@ For references see Clause xref:spec-metamodel/referencing.adoc#referencing-in-aa
 
 ----
 
-== Format "Normal" in  XML
+include::formats/xml.adoc[]
 
-The metamodel of an Asset Administration Shell needs to be serialized for import and export scenarios.
-XML is a possible serialization format.
+include::formats/json.adoc[]
 
-eXtensible Markup Language (XMLfootnote:[see: https://www.w3.org/TR/2008/REC-xml-20081126/]) is very well suited to derive information from an IT system, e.g. to process it manually and then feed it into another IT system.
-XML provides the possibilities of scheme definitions, which can be used to syntactically validate the represented information in each step.
-
-====
-Note 1: the xml schema (.xsd files) is maintained in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder `schemas\xml`
-====
-
-====
-Note 2: the mapping rules of how to derive the xml schema from the technology-neutral metamodel as defined in this specification can be found in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder `schemas\xml\Readme.md#xml-mappingrules`
-====
-
-====
-Note 3: example files can be found in the repository "aas-specs" in the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]]  in folder : `schemas\xml\examples`
-====
-
-== Format "Normal" in JSON
-
-JSONfootnote:[see: https://tools.ietf.org/html/rfc8259 or https://www.ecma-international.org/publications/standards/Ecma-404.htm] (JavaScript Object Notation) is a further serialization format that serializes the metamodel of an Asset Administration Shell for import and export scenarios.
-
-Additionally, JSON format is used to describe the payload in the http/REST API for active Asset Administration Shells xref:bibliography.adoc#bib37[[37\]].
-
-====
-Note 1: the JSON schema (.json files) is maintained in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder `schemas\json`
-====
-
-====
-Note 2: the mapping rules of how to derive the JSON schema from the technology-neutral metamodel as defined in this specification can be found in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in `schemas\json\Readme.md#json-mappingrules`
-====
-
-
-
-====
-Note 3: example files can be found in the repository "aas-specs" in the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder `schemas\json\examples`
-====
-
-== Format "Normal" in RDF
-
-The Resource Description Framework (RDF) xref:bibliography.adoc#bib32[[32\]] is the 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-)IRIs.
-As a common practice, the provision of additional information at the referenced location of an RDF entity directly allows the interlinking of entitiesfootnote:[Note: entity as a generic term and entity as a specific submodel element subtype need to be distinguished.] based on the web.
-This process – following links in order to discover related information – is called dereferencing a resource and is supported by any browser or web client.
-Connecting distributed data sources through the web in the described manner is referred to by the term "Linked Data".
-Connecting the available resources and capabilities of linked data with the expressiveness of the Asset Administration 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) and the Web Ontology Language (OWL) 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 features, 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 Asset Administration Shell requires a clear scheme of its RDF representation.
-
-
-====
-Note 1: the RDF scheme/OWL files (.ttl files) are maintained in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder `schemas\rdf`
-====
-
-
-
-====
-Note 2: the mapping rules of how to derive the RDF schema from the technology-neutral metamodel as defined in this specification can be found in the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in `schemas\rdf\Readme.md#rdf-mappingrules`
-====
-
-
-
-====
-Note 3: example files can be found n the repository "aas-specs" of the GitHub project admin-shell-io xref:bibliography.adoc#bib51[[51\]] in folder `schemas\rdf\examples`
-====
+include::formats/rdf.adoc[]