From 34237ad5c55545a153328df2eb01feb41f58dd43 Mon Sep 17 00:00:00 2001 From: Andreas Textor Date: Tue, 13 Aug 2024 09:37:27 +0200 Subject: [PATCH] Add ADR for namespace packages (#306) --- .../decisions/0009-namespace-packages.md | 143 ++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 documentation/decisions/0009-namespace-packages.md diff --git a/documentation/decisions/0009-namespace-packages.md b/documentation/decisions/0009-namespace-packages.md new file mode 100644 index 0000000..a29985c --- /dev/null +++ b/documentation/decisions/0009-namespace-packages.md @@ -0,0 +1,143 @@ +# Namespace packages + +## Context and Problem Statement + +Occasionally sets of Aspect Model need to be processed as a units. Uses cases include sending and +receiving Aspects Models using tools such as email or chats or APIs that allow download or upload of +Aspect Models. In order to enable tools to process such sets of Aspect Models in a consistent way, +this document describes a format called _Aspect Model namespace package_, or _namespace package_ for +short. The name is chosen to indicate that such a package contains a set of namespace files (see +[ADR-0007](0007-model-resolution.md) for an explanation of this term). + +The goals for the format are: + +* Enable simple and straightforward exchange of sets of aspect model files. +* Enable reasonable interoperability with existing tools and conventions. + +Non-goals of the format are: + +* Establish a generic container format that can contain arbitrary content. +* Establish a self-contained publishing format that contains meta data beyond regular aspect model + file content (e.g., provenance meta data). +* Include mechanisms for authenticity such as digital signatures or certificates. +* Include mechanisms for content verification such as checksums. + +The above points can and should be achieved using different means - depending on the used +distribution channels - and need no reinvention. + +## Namespace Package Specification + +A namespace package has the following properties: + +* It is a file in ZIP format. +* Its standard file extension is `.zip`. This means: + * When creating a new namespace package file, the file extension should be `.zip`. + * Reading namespace packages files with other file extensions is allowed. Use cases for this are + discussed in section [Interoperability](#interoperability). +* A _models root_ is determined for the content of the ZIP file: + * If a directory `aspect-models` exists in `/` of the ZIP file, it is the models root. + * Otherwise, the directories in `/` of the ZIP are traversed non-recursively in lexicographically + sorted order (by en-US locale) and the first subdirectory of any of them that is called + `aspect-models` is the models root. + * Otherwise, if no such directory exists, `/` of the ZIP file is the models root. +* The namespace package ZIP file contains aspect model files with `.ttl` file extension that are + organized in the directory structure _models root_/_namespace main part_/_namespace version + part_/AspectModelFile.ttl, where _namespace main part_ and _namespace version part_ correspond to + the namespace of the content of the `.ttl` file. There are no further restrictions, i.e., there can + be arbitrary many namespace main part directories, arbitrary many namespace version directories + and arbitrary many, arbitrarily named `.ttl` files inside. +* Any other directory or file in the ZIP file is ignored. + +## Interoperability + +By not strictly requiring a specific file extension and ignoring unknown contents of the namespace +package file, it is possible to create files that are at the same time valid namespace packages and +valid files according to some other ZIP-based file format. + +_The following examples are non-normative._ + +### Example 1: Overlay Namespace Package with Java .jar file + +Since the `.jar` format used to distribute Java artifacts is also based on the ZIP format, it is +possible to create a `.jar` file - which may or may not contain Java class files - that is at the +same time a valid namespace package. Uses for this technique include: +* Distributing namespace packages using existing Java architecture and services such as Maven + Central or Artifactory. +* Allowing to declare a dependency of a Java project to an Aspect Model namespace package using + standard Java/Maven tooling. +* Publishing Java-based software that comes with Aspect Models describing its domain; the executable + `.jar` file can both be executed and opened as a namespace package. + +A `.jar` file can contain resources organized in arbitrary directory structures, so a `.jar`-based +namespace package could use either the `.jar`'s root as models root, or use a separate +`aspect-models` directory. + +### Example 2: Overlay Namespace Package with Asset Administration Shell .aasx file + +The Asset Administration Shell +[.aasx](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01005-3-0_SpecificationAssetAdministrationShell_Part5_AASXPackageFileFormat.pdf) +format is based on [Office Open XML](https://en.wikipedia.org/wiki/Office_Open_XML) (also +standardized as ECMA-376 and ISO/IEC 29500), which is also based on the ZIP format. Apart from +structure and files mandated by OOXML, the directory structure in `.aasx` files always includes an +`aasx` directory, and below that, custom structures of directories and files are allowed that can be +referenced from within `File` submodel elements, as long as corresponding relationships are +described in the OOXML's XML descriptors. This allows creation of an `.aasx` file that bundles +aspect model files which are referenced from within a contained AAS submodel or submodel template +and that is at the same time a valid Aspect Model namespace package. The contents of the `.aasx` +file could therefore look like this: + +``` +/ +├─ _rels +│ └─ .rels +├─ aasx +│ ├─ _rels +│ │ └─ data.xml.rels +│ ├─ aasx-origin +│ ├─ data.xml +│ └─ aspect-models +│ ├─ com.example.ex1 +│ │ └─ 1.0.0 +│ │ ├─ MyAspect.ttl +│ │ └─ AnotherFile.ttl +│ └─ com.example.ex2 +│ └─ 1.0.0 +│ └─ MyOtherAspect.ttl +└─ [Content_Types].xml +``` + +The OOXML file `[Content_Types].xml` could register the MIME type for `.ttl` as follows: + +```xml + + + + + + + +``` + +The model elements (Asset Administration Shells or Submodels) defined in `data.xml` can then contain +`File` submodel elements that refer to the aspect model files: + +```xml + + + MyAspect + + ExternalReference + + + GlobalReference + urn:samm:com.example.ex1:1.0.0#MyAspect + + + + /aasx/aspect-models/com.example.ex1/1.0.0/MyAspect.ttl + text/turtle + + +``` + +With this setup, the `.aasx` file itself is also a valid namespace package.