Skip to content

Commit 34237ad

Browse files
atextoratextor
authored
Add ADR for namespace packages (#306)
1 parent b90b1d7 commit 34237ad

File tree

1 file changed

+143
-0
lines changed

1 file changed

+143
-0
lines changed

‎documentation/decisions/0009-namespace-packages.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# Namespace packages
2+
3+
## Context and Problem Statement
4+
5+
Occasionally sets of Aspect Model need to be processed as a units. Uses cases include sending and
6+
receiving Aspects Models using tools such as email or chats or APIs that allow download or upload of
7+
Aspect Models. In order to enable tools to process such sets of Aspect Models in a consistent way,
8+
this document describes a format called _Aspect Model namespace package_, or _namespace package_ for
9+
short. The name is chosen to indicate that such a package contains a set of namespace files (see
10+
[ADR-0007](0007-model-resolution.md) for an explanation of this term).
11+
12+
The goals for the format are:
13+
14+
* Enable simple and straightforward exchange of sets of aspect model files.
15+
* Enable reasonable interoperability with existing tools and conventions.
16+
17+
Non-goals of the format are:
18+
19+
* Establish a generic container format that can contain arbitrary content.
20+
* Establish a self-contained publishing format that contains meta data beyond regular aspect model
21+
file content (e.g., provenance meta data).
22+
* Include mechanisms for authenticity such as digital signatures or certificates.
23+
* Include mechanisms for content verification such as checksums.
24+
25+
The above points can and should be achieved using different means - depending on the used
26+
distribution channels - and need no reinvention.
27+
28+
## Namespace Package Specification
29+
30+
A namespace package has the following properties:
31+
32+
* It is a file in ZIP format.
33+
* Its standard file extension is `.zip`. This means:
34+
* When creating a new namespace package file, the file extension should be `.zip`.
35+
* Reading namespace packages files with other file extensions is allowed. Use cases for this are
36+
discussed in section [Interoperability](#interoperability).
37+
* A _models root_ is determined for the content of the ZIP file:
38+
* If a directory `aspect-models` exists in `/` of the ZIP file, it is the models root.
39+
* Otherwise, the directories in `/` of the ZIP are traversed non-recursively in lexicographically
40+
sorted order (by en-US locale) and the first subdirectory of any of them that is called
41+
`aspect-models` is the models root.
42+
* Otherwise, if no such directory exists, `/` of the ZIP file is the models root.
43+
* The namespace package ZIP file contains aspect model files with `.ttl` file extension that are
44+
organized in the directory structure _models root_/_namespace main part_/_namespace version
45+
part_/AspectModelFile.ttl, where _namespace main part_ and _namespace version part_ correspond to
46+
the namespace of the content of the `.ttl` file. There are no further restrictions, i.e., there can
47+
be arbitrary many namespace main part directories, arbitrary many namespace version directories
48+
and arbitrary many, arbitrarily named `.ttl` files inside.
49+
* Any other directory or file in the ZIP file is ignored.
50+
51+
## Interoperability
52+
53+
By not strictly requiring a specific file extension and ignoring unknown contents of the namespace
54+
package file, it is possible to create files that are at the same time valid namespace packages and
55+
valid files according to some other ZIP-based file format.
56+
57+
_The following examples are non-normative._
58+
59+
### Example 1: Overlay Namespace Package with Java .jar file
60+
61+
Since the `.jar` format used to distribute Java artifacts is also based on the ZIP format, it is
62+
possible to create a `.jar` file - which may or may not contain Java class files - that is at the
63+
same time a valid namespace package. Uses for this technique include:
64+
* Distributing namespace packages using existing Java architecture and services such as Maven
65+
Central or Artifactory.
66+
* Allowing to declare a dependency of a Java project to an Aspect Model namespace package using
67+
standard Java/Maven tooling.
68+
* Publishing Java-based software that comes with Aspect Models describing its domain; the executable
69+
`.jar` file can both be executed and opened as a namespace package.
70+
71+
A `.jar` file can contain resources organized in arbitrary directory structures, so a `.jar`-based
72+
namespace package could use either the `.jar`'s root as models root, or use a separate
73+
`aspect-models` directory.
74+
75+
### Example 2: Overlay Namespace Package with Asset Administration Shell .aasx file
76+
77+
The Asset Administration Shell
78+
[.aasx](https://industrialdigitaltwin.org/wp-content/uploads/2023/04/IDTA-01005-3-0_SpecificationAssetAdministrationShell_Part5_AASXPackageFileFormat.pdf)
79+
format is based on [Office Open XML](https://en.wikipedia.org/wiki/Office_Open_XML) (also
80+
standardized as ECMA-376 and ISO/IEC 29500), which is also based on the ZIP format. Apart from
81+
structure and files mandated by OOXML, the directory structure in `.aasx` files always includes an
82+
`aasx` directory, and below that, custom structures of directories and files are allowed that can be
83+
referenced from within `File` submodel elements, as long as corresponding relationships are
84+
described in the OOXML's XML descriptors. This allows creation of an `.aasx` file that bundles
85+
aspect model files which are referenced from within a contained AAS submodel or submodel template
86+
and that is at the same time a valid Aspect Model namespace package. The contents of the `.aasx`
87+
file could therefore look like this:
88+
89+
```
90+
/
91+
├─ _rels
92+
│ └─ .rels
93+
├─ aasx
94+
│ ├─ _rels
95+
│ │ └─ data.xml.rels
96+
│ ├─ aasx-origin
97+
│ ├─ data.xml
98+
│ └─ aspect-models
99+
│ ├─ com.example.ex1
100+
│ │ └─ 1.0.0
101+
│ │ ├─ MyAspect.ttl
102+
│ │ └─ AnotherFile.ttl
103+
│ └─ com.example.ex2
104+
│ └─ 1.0.0
105+
│ └─ MyOtherAspect.ttl
106+
└─ [Content_Types].xml
107+
```
108+
109+
The OOXML file `[Content_Types].xml` could register the MIME type for `.ttl` as follows:
110+
111+
```xml
112+
<?xml version="1.0" encoding="utf-8"?>
113+
<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
114+
<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
115+
<Default Extension="ttl" ContentType="text/turtle"/>
116+
<!-- ...other extensions... -->
117+
<Override PartName="/aasx/aasx-origin" ContentType="text/plain"/>
118+
</Types>
119+
```
120+
121+
The model elements (Asset Administration Shells or Submodels) defined in `data.xml` can then contain
122+
`File` submodel elements that refer to the aspect model files:
123+
124+
```xml
125+
<!-- ... -->
126+
<file>
127+
<idShort>MyAspect</idShort>
128+
<semanticId>
129+
<type>ExternalReference</type>
130+
<keys>
131+
<key>
132+
<type>GlobalReference</type>
133+
<value>urn:samm:com.example.ex1:1.0.0#MyAspect</value>
134+
</key>
135+
</keys>
136+
</semanticId>
137+
<value>/aasx/aspect-models/com.example.ex1/1.0.0/MyAspect.ttl</value>
138+
<contentType>text/turtle</contentType>
139+
</file>
140+
<!-- ... -->
141+
```
142+
143+
With this setup, the `.aasx` file itself is also a valid namespace package.

0 commit comments

Comments
 (0)