Package File Format for the Asset Administration Shell (AASX) (normative)

General

Some use cases make it necessary to exchange the full or partial structure of the Asset Administration Shell with or without associated values and/or to make the information persistent (e.g. store it on a file server). In this case, a file format must be defined that can hold and store this information. Therefore, a package file format for the Asset Administration Shell (AASX) is defined based on the following requirements:

  • generic package file format to include the Asset Administration Shell structure, data, and other related files,

  • main use cases are the exchange between organizations/partners and storage/persistence of the Asset Administration Shells’ information,

  • the package format shall be usable by everyone without any legal restrictions or royalties; the format should preferably be based on an international standard with high guarantees of future maintainability,

  • existence of APIs to create, read, and write packages of this format,

  • provision of digital signatures and encryption capabilities,

  • policies for authenticity and integration of package files[1].

The following process in Figure 1 is defined for creating and consuming AASX packages.

aasx package gen and use
Figure 1. Process for Generating and Consuming AASX Packages

The process starts by serializing the existing AAS (e.g. D1 and E1) into files (according to the serialization mechanisms described in this document), as well as exporting other supplementary files (i.e. files mentioned in the structure of the AAS, such as manuals, CAD files, etc.). All these files will be packaged together into the AASX ZIP file format and will be followed by several security steps that define the policies for modifiability, encryption, and digital signing of the files inside the AASX. The final AASX can then be transported from the AASX producer (in this case partner A) to the AASX consumer (partner B) via digital media such as e-mail, USB stick, etc. The consumer first needs to validate and verify the incoming AASX, unpack the contained files, and import them to generate the new AAS in the consumer environment. The process will be explained in detail in the following subsections.

Conventions for the Asset Administration Shell Package File Format (AASX)

The Asset Administration Shell Package (AASX) format is derived from the Open Package Conventions standards, consequently inheriting its characteristics.Nevertheless, some conventions are defined for the AASX:

  • package format and rules according to ISO/IEC 29500-2:2012; any derivate format from this standard (such as the AASX format) requires the definition of a logical model, a physical model, and a security model; the specific conventions are described in the next subsections.

  • file extension for the AASX format .aasx,

  • MIME-type for the AASX format: application/asset-administration-shell-package[2],

  • icon for the AASX[3],

  • identification of the AASX format by the file extension and content (MIME) type, which can be identified content-wise when reading the first relationship file /_rels/.rels (as defined in Open Packaging Conventions) and looking for a relationship type http://admin-shell.io/aasx/relationships/aasx-origin (which is the entry point for the logical model of the Asset Administration Shell),

  • note that the following paths and filenames in the package are already reserved by the Open Packaging Conventions specification and shall therefore not be used for any derivative format: /[Content_Types].xml; /_rels/.rels; /<file_path>/_rels/<filename>.rels (where <filename> is a file in the package that is source of relationships and <file_path> is the path to that file),

  • the AASX format does not have to be opened in any existing Office Open XML / Open Packaging Conventions compatible Office application (e.g. Microsoft Office, LibreOffice), because the required relationships and files for the different office "models" may not be present (e.g. http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument for "docx" document).

The following relationship path is deprecated: http://www.admin-shell.io/aasx/relationships

ECMA-376 Relationships

Figure 2 defines a set of relationship types (URIs) and the corresponding source files as a part of the logical model for the AASX format.In addition (not shown in Figure 2), a specific relationship instance also has a unique ID and a target resource (URI of a target file inside or outside the package).

aasx rels
Figure 2. Relationship Types for AASX Packages (Logical Model)

The relationship types for thumbnail, core-properties, digital-signatures (origin, signature and certificate) are defined by Open Packaging Conventions.The other relationship types were specifically defined to support the AASX package format.

The following name spaces are defined:

Namespace Value

<rel>

http://schema.openxmlformats.org/package/2006/relationships

<rel_aas>

http://admin-shell.io/aasx/relationships

and

(<<Deprecated>>) http://www.admin-shell.io/aasx/relationships

Each relationship type[4] as denoted in Figure 2 is described in the following.

Relationship Type

Source File of Relationship Type:

--

Namespace:

<rel>
Relationship Type Card. Description

metadata/thumbnail

0..1

Required to define a thumbnail for that package (e.g. picture of the administrated device).

The thumbnail picture can be shown instead of the package’s icon based on the extension and/or content type.

metadata/core-properties

0..1

There is a schema for describing the package through "core properties," which uses selected Dublin Core metadata elements in addition to some Open Packaging Conventions-specific elements.

The core properties do not describe the Administration Shell, but the package itself. Some elements of the core properties may be similar/equal to elements of the Administration Shell.

Some core properties are: Title, Subject, Creator, Keywords, Description, LastModifiedBy, Revision, LastPrinted, Created, Modified, Category, Identifier, ContentType, Language, Version, ContentStatus.

digital-signature/origin

0..1

Required if you need to sign files and relationships inside the package. Their relationships basically target files that contain the data on signatures (e.g. certificate, digests, etc.).

Note: see Digital Signatures for more information.

aasx-origin

1

This relationship targets an aasx origin file which shall be an empty file or a plain text file containing the text "Intentionally empty"[5].

It is the entry point for all aas specific relationships and files inside the package. The source of the aasx origin relationship must be the package root.

5. This will allow extensions of the AASX package format in future versions of this specification.

Relationship Type

Source File of Relationship Type:

<rel>/digital-signature/origin

Namespace:

<rel>
Relationship Type Card. Description

digital-signature/signature

1..*

Required if you need to sign files and relationships inside the package. Their relationships basically target files that contain the data on signatures (e.g. certificate, digests, …).

Note: see Digital Signatures for more information.

Relationship Type

Source File of Relationship Type:

<rel>/digital-signature/signature

Namespace:

<rel>
Relationship Type Card. Description

digital-signature/certificate

0..1

Required if you need to sign files and relationships inside the package. Their relationships basically target files that contain the data on signatures (e.g. certificate, digests, …).

Note: see Digital Signatures for more information.

Relationship Type

Source File of Relationship Type:

<rel_aas>/aasx-origin

Namespace:

<rel_aas>
Relationship Type Mandatory Description

aas-spec

1..*

Targets the file that contains the structure/specification of one or more identifiable elements (such as AAS, Submodel or ConceptDescription).

Different formats of the same information can be contained in the container.

Typical formats contained are XML and/or JSON.

Relationship Type

Source File of Relationship Type:

<rel_aas>/aas-spec

Namespace:

<rel_aas>
Relationship Type Mandatory Description

aas-suppl

0..1

Targets any additional file, which is referenced from within the data of an AAS via a relative URI reference in the File submodel element.

Note 1: the internal relative paths shall be relative to the parent directory of the _rels folder (see ISO/IEC 29500-2).

Note 2: blobs as defined via submodel Element Blob are not stored as supplemental files within the package.

Note 3: not every File element inside the specification of a Submodel may target a file stored within the same AASX package. Only a relative URI reference shall be interpreted as a reference to a supplementary file within the AASX package. The path within the .rels file of the Open Package Conventions container can be a relative or absolute Open Package Conventions path.

The source of any aasx-suppl relationship must be the file containing the AAS structure/specification. If the information is available in several formats, the relationships need to be defined for each of the files.

File Structure and File Name Conventions

Using the ECMA-376 relationships (see ECMA-376 Relationships) allows to locate files within the AASX package independently of the file name. For example, one package producer might store an aas-spec file in /aasx/device.xml, the other one in /asset-admin-shell/productX123.xml, but both use the same relationship type to target that file. To have a more consistent approach, the following conventions are defined for naming files inside the AASX package:

  • aasx/ shall be the common folder for all files containing AASX package specific information,

  • aasx/aasx-origin shall be the target of the aasx-origin relationship without content (empty file or a plain text file containing the text "Intentionally empty"),

  • aasx/data.<extension> should be the target of the aas-spec relationship, where <extension> is for example "xml" or "json", based on the type of serialization,

  • a serialization of the same data in several serialization formats (for example xml and json) stored in the same AASX package might also exist; they can be stored in parallel using the aforementioned extensions and appropriate ECMA-376 Content Types (MIME type) and require the creation of the appropriate aas-suppl relationships for both of these files, targeting the supplementary files.

Figure 4 shows the overall physical model, i.e. the file structure of an AASX package. The folder "suppl" is empty in this example or not shown. The corresponding files contained in the folder "suppl" would be referenced in the data.xml.rels and data.json.rels files. The file "Thumbnail.png" is referenced in file ".rels" as target for relationship with type "metadata/thumbnail".

Figure 3 shows an example of an AASX package focusing on the specific aasx part including AAS examples. It depicts the content of the AASX package listed in a tree view using the ECMA-376 relationship types defined in Figure 2 and follows the file name conventions as defined above. In this example, it is assumed that the AAS specification files are serialized in XML. The data.xml file in this example contains two Asset Administration Shells, two submodels, and a single concept description. Three files are referenced within the submodels; they are added to the package in the folder suppl. The files can be referenced from both AAS, i.e. from both submodels. The same accounts for the concept description that can be used in both submodels. The submodels can be part of both AAS, if needed.

logical to physical map
Figure 3. Example of Mapping Logical (right) to Physical Model (left)

In addition to the AASX specific files, files common to all ECMA-376 packages – such as relationship parts (*.rels) and the Content Types stream ([Content_Types].xml) – must be contained in an AASX package in its physical representation as a .zip archive. For more information on these files, please refer to the ECMA-376 specification.

aasx file structure
Figure 4. AASX File Structure (Physical Model)

Digital Signatures

A digital signing feature is already provided by the Open Packaging Conventions specification [4].Hence, this signing framework for packages can also be used for AASX packages.To ensure the integrity of the AAS data, all relevant files within the package (aasx-origin file, AAS structure specification file, supplementary files) and the associated relationship parts shall be signed.

Encryption

The Open Packaging Conventions specification (ISO/IEC 29500-2:2012) mentions that "ZIP-based packages shall not include encryption as described in the ZIP specification.Package implementers shall enforce this restriction [M3.9]"[6].However, an Open Packaging Conventions package may be encrypted with other means and some applications, which use this package format as the basis for a more specific format, may use encryption during interchange or DRM for distribution [1].

An example is the Office Document Cryptography Structure (MS-OFFCRYPTO) used by derivate office formats.Some technologies used may be covered by patents from Microsoft and are therefore not recommended for the AASX format.Digital Rights Management (DRM) can also be used to encrypt content elements in a package with specific access rights granted to authorize users (see the implementation in the system.io.packaging namespace [7]).

Regarding encryption and confidentiality, the following rules shall be followed.

  1. Decide if there is a need to include confidential content in a package; if there is no need, it shall not be included.

  2. If encryption is desired for a temporary communication act (e.g. e-mail exchange, etc.) or if an AASX needs to be stored somewhere to be opened later by the same entity, then encryption methods can be used for that specific means (e.g. use BitLocker when storing the AASX in Windows-based systems that support it, use S/MIME for exchanging encrypted e-mails between entities, etc.).

  3. For all other use cases[7] where encryption is required for some or all of the content of the AASX, the following applies.

    • Encryption methods can be used for individual files in the AASX package, if the "encrypted" version replaces the original file in the package, the content type of the encryption format is known, and the content type is listed in the [Content-Type].xml. The relationships as defined in this document remain the same, whether content is encrypted or not. Note that Open Packaging Conventions related files as well as relationship files shall not be encrypted, and digital signing must be performed after encryption. One example of an encryption standard is the Secure MIME (S/MIME), where the encrypted content should be stored in application/pkcs7-mime format as defined in RFC 5652 and the file extension *.p7m should be used.

    • Besides encrypting the content of the package (individual files), it is possible to encrypt the full package (e.g. also using Secure MIME and saving the encrypted package in application/pkcs7-mime file format). In this case, signing of the content of the package must be done before encryption.

1. Role-based policies to access this package are not defined, as this is a feature of the systems that host the AASs (see Part 4 Security of the document series).
2. The current MIME-type is provisory and needs to be requested officially.
3. No official icon for aasx extension available so far.
4. To avoid the long names of the relationship types, the short name is used in the text.
6. The reason might be related to the transparency requirement for the package format as well as license requirements of PKWARE. For ISO/IEC 21320-1 (Document Container File: Core), the following statement applies: “Encryption of individual files and of the central directory is prohibited. Hence, this profile of ZIP_PK is more transparent than its parent format.” [6]
7. A use case could be to encrypt a submodel and only provide the access to the unencrypted data after paying a fee.