How to create a Submodel template Specification V1.1

This document is an enabler for the IDTA specification series of Submodel template specifications. Each part of the mentioned series specifies the contents of a Submodel template (SMT) for the Asset Administration Shell (AAS). The Asset Administration Shell is described in [1], [2], [3] and [6]. First exemplary Submodel contents were described in [4] and [8], while the actual format of this document was derived by the "Administration Shell in Practice" [5].

The IEC working group IEC TC65 WG24 publishes the AAS as an international standard [7]. Figure 1 illustrates the AAS and Submodel template guiding the creation of Submodels. SubmodelElements and Submodel template elements may reference entries in concept repositories. The creators of Submodel template specification are designated as the Asset Administration Shell responsibles.

Figure 2 illustrates two the Asset Administration Shell user applications, to use the interoperable Submodel information.

From the viewpoint of the meta model [6], a Submodel template is a Submodel with kind = Template.

This document facilitates the creation of Submodel template for the Asset Administration Shell. These Submodel templates will allow the Asset Administration Shell responsibles to create and provide standardized models, which represent certain aspects of an asset. Specifically, this document describes how Submodel template specifications for Submodel templates shall be created in order to maintain a set of common features and structures. For this purpose, different workflows are described.

The Submodel template comprises machine-readable information, such as AASX package files, but also human-readable information. The latter can be described in the form of a Submodel template specification.

The scope of this document is to provide a uniform human readable and machine-readable way of a Submodel template. It describes the possible workflows and necessary working steps to create a Submodel template. It allows multiple Submodel template teams to work in parallel on different Submodel templates, while maintaining a common structure and required features. Different human stakeholders shall be able to understand information and services associated with the particular Submodel template and realized Submodel instances.

Not scope of this document is the IDTA process for registering Submodel template; this is described by [R1].

Stakeholders for reading and applying this document are, among others:

The following abbreviations are used in this document:

For some terms, a special notation is used, in order to distinguish them from English text. Defined in [6], these include:

Bibliography items are designated as references such as [1], resources are designated as reference such as [R1].

This document currently targets meta model version V3.0. Meta model version V3.1 is upcoming, and the contents described in this document will hold true, as well. Submodels (SM), SubmodelElementCollections (SMC) and SubmodelElementLists (SML) are used frequently as means of hierarchical structuring SubmodelElements.

No further general information is given, yet.

The creation of a SMT specification has multiple deliveries (see General), including the human-readable part of SMT, currently a word processor document. This human-readable part is called SMT document. This document describes also, how this document can be described by markup elements (AsciiDoc).

The deliverables shall include human and machine-readable AASX files and may also include samples and more (see Table 3).

For the structure of the content for the human-readable part of SMT, the SMT document, a template is available at IDTA office.

The IDTA document number is retrieved from the IDTA office. The number for SMT starts at the 02000 number range (the 01000 - 01999 number range is reserved for meta models). It is possible to apply to the IDTA office to reserve a range of document numbers, e.g. for future extensions of the subject matter described.

The administrative information of Identifiables in the AAS entities comprises of two attributes: version and revision [6]. The version and revision are also indicated by the IDTA document number (e.g. IDTA 4711-1-0 stands für the SMT IDTA 4711 version 1 revision 0). For the SMT, this is seen as semantic versioning:

In this section, multiple possible workflows are described. Any workflow might be executed by an architect, however, reviews within the SMT team and with possible domain experts are considered essential. The workflow and the achieved results shall comply with the IDTA Process Description [R1].

For the "(6) Review" phase of the process [R1] and for publication by IDTA, the following artifacts are mandatory/ optional (see Table 3).

The following sections describe multiple workflows which can be utilized to create a SMT specification. Each of these workflows is allowed to be used. However, in order to maintain quality of the SMT specifications and to streamline the set of specifications for the future, the following recommendations are stated by the IDTA:

The document driven workflow is rather simple and can be executed with limited invocation of advanced tools. It is suitable for rather simple Submodels. Figure 4 demonstrates the workflow.

The specification document is in the center of activities. The following working steps can be distinguished:

The model-based workflow is suitable for complex subject matters and working teams looking deeply into particular aspects and capabilities of the resulting AASX model. Figure 5 demonstrates the workflow.

The SMT model is at the center of activities. The following working steps can be distinguished:

The semantic based workflow is especially suitable for complex subject matters with no existing semantic definitions available for the subject under consideration. In the case of the semantic definition of a Submodel this also includes structural information. The workflow can also be applied in cases there is already a semantic definition available for the Submodel but in a different machine-readable format. Figure 6 demonstrates the workflow.

The semantic definition of the Submodel itself is in the center of activities. A semantic definition of a Submodel is typically a model itself, in short such a model is sometimes called a semantic model. The following working steps can be distinguished:

This workflow is an update of the model-based workflow (see section Model based workflow) using AsciiDoc technology for documentation purposes. Figure 7 demonstrates the workflow. Similar extensions to the document driven or semantic driven workflow can be made. They are not documented separately.

It is recognized that "AsciiDoc is a [R10] suitable plain text markup language for writing technical content". With the use of AsciiDoc combined with GitHub functionality, an open, decentralized and traceable maintenance of the SMT specification becomes possible.

The SMT model is at the center of activities. For the editing of the SMT specification WD, a GitHub repository with dedicated actions is used by all members of the SMT working team. This is already the case for the IDTA GitHub repository for Submodel templates [R11].

The workflow can start with some optional working steps:

This workflow emphasizes the SMT model as a single source of truth for the SMT specification. Figure 8 demonstrates the workflow. Some advantages of the GitHub based AsciiDoc editing (see section Workflow with GitHub based AsciiDoc working draft document) are sacrificed in order to keep all elements of the specification process together and to allow an automatic referencing/ including of all exporting/ generation steps. This leads to a short round-trip time for rendering consistent SMT previews and easy maintainability after publication.

The SMT model is at the center of activities. It contains two Submodels: one Submodel stands for the Submodel template and Submodel template elements. One Submodel stands for the human readable parts of the SMT specification, including also structure, images, figures, header and style files.

The workflow can start with some optional working steps (same as described in section Model based workflow and section Workflow with GitHub based AsciiDoc working draft document):

A SMT dropin is a set of SubmodelElements and associated ConceptDescriptions, which can be used in multiple SMT specifications. The intended purpose is re-use.

A SMT dropin is not a Submodel template on its own, i.e. there is no Submodel guided by a SMT dropin.

A SMT dropin is a logical model (compare SMT model, see Clause Artifacts to be delivered). A SMT dropin is always part of a Submodel, the reason being that the same technology and APIs as for SMT in general can be used.

For defining SMT dropins, the same process is used as for a Submodel template. This document specifies the definition and application of SMT dropins, as well.

Definition of SMT dropins might occur in different organization schemes (depending on the implementation by e.g. IDTA or other consortia dedicated to a specific domain).

The definition and the use of a SMT dropin makes use of the same semanticId. In order to formally distinguish between these two cases, adding of the following supplementalSemanticIds is required (see Table 4, Figure 11, Figure 12):

For the publication of SMT dropins, a dedicated folder is foreseen in the IDTA GitHub repository for Submodel templates [R11]. For each SMT dropin, a sub-folder is foreseen with at least these artifacts (see Artifacts to be delivered, Table 5):

A SMT specification, which takes advantage of a SMT dropin, shall indicate this usage to the reader of the specification.

Certain degrees of flexibility can be achieved by the Submodel template using a SMT dropin definition, if the use of a SMT dropin is indicated by the respective supplementalSemanticId for "use" (see Handling of semanticIds). As an example, in Figure 13 and Figure 14, the root of the contact information was decided to be titled "AddressInformation". The following degrees of flexibility are (see Table 6):

For all other attributes, i.e. other template qualifiers and data specifications defined for the dropin as well as attributes like annotations for AnnotatedRelationshipElement or variables in operations, the value shall be identical to the one defined for the dropin. The same holds if some attributes have a fixed predefined value.

Having an SMT model available, Unified Modeling Language (UML) can be generated easily via the AASX Package Explorer. This is achieved using "File / Export / Export Submodel as UML" [R3].

Precondition is, that cardinalities of the different SubmodelElement are designated via the Qualifier "Multiplicity", according to section Qualifiers controlling the structure. UML can be generated for Submodels of kind = Template or kind = Instance, even with (example) values attached.

Unified Modeling Language (UML) is a highly specified, general-purpose, modeling language in the field of software engineering and is used for many purposes. One purpose is to illustrate the structure of AAS elements given by a SMT (SMT) specification. For this purpose, within such specification, the following provisions are set:

Figure 15 shows the result of export UML to XMI 2.1 format via the AASX Package Explorer. The XMI does not contain the design of a diagram, so this must be done using an UML authoring tool, such as Enterprise Architect. An intended layout can be achieved.

Figure 16 shows the result of exporting UML to PlantUML format via the AASX Package Explorer. The file contents can be copied to the clipboard, as well, and directly pasted to [R7].

The AASX Package Explorer [R3] allows using the plugin AasxPluginGenericForms to assist users in creating Submodel instances based on SMTs (see Figure 17). The plugin displays a visual assistant to easily create a Submodel instance according to a SMT and fill out this instance with data. This allows also non-expert users to provide subject matter information to the AAS.

The different SubmodelElements of a SMT need to be attributed by Qualifers in order to provide enough information for an adequate rendering of generic forms. These Qualifiers are described in section Qualifiers supporting the generic forms functionality.

The SMT might be exported via "File / Export / Export Submodel as options for generic forms" [R3]. This leads to the creation of a file "*.add-options.json", which can be used by other users to automatically generate and fill out Submodels.

In order to use a generic forms preset in AASX Package Explorer [R3], the user needs to locate the ".\plugins\AasxPluginGenericForms" folder and copy the respective "*.add-options.json" file into this folder (see Figure 18). After re-start of the application, using "Workspace / Plugins / New Submodel", a new Submodel can be created.

The architect and IDTA office will also check if the Submodel and its generic forms preset can be included into the standard deployment of the AASX Package Explorer.

The SMT document shall provide a set of tables for the Submodels and SubmodelElements, which are specified by the SMT. In the SMT, these AAS elements shall be of kind = Template. The tables are designed to provide an overview of these AAS elements, allowing all stakeholders (see section Stakeholders) to understand the design of the particular SMT.

The described table format is not self-explanatory. Each SMT document shall feature an appendix, explaining the table format (see Annex A). This appendix is provided by the template document of the IDTA.

The SMT document shall feature a separate table for each AAS element, which is specified by the SMT and which hierarchically specifies child AAS elements (consequently named "AAS element with children"). Typically, but not exclusively, these are Submodels and SubmodelElementCollections (see section Meta model version), but can be also Operations or Entities.

Figure 19 shows the format of the heading part of such table. For the different rows, the following provisions are given by Table 7:

Each table for AAS elements with children features multiple row items, one per child of the AAS element. Such row item shall be exactly one table row in the word processor document. In order to accommodate sufficient information for the stakeholders, each cell of the row item might contain multiple information, delimited by line breaks.

Figure 20 shows the format of the individual row items of such table. For the different row items, the following provisions are given by Table 8:

After the table header, before the first row items, two table rows shall be given featuring the respective labels defined in Table 8, as illustrated by Figure 20.

The meta model of the AssetAdministrationShell distinguishes between the templateId and the semanticId of a Submodel. The semanticId references a concept definition (either as a ConceptDescription as defined in the metamodel of the AAS or as a reference to an external dictionary entry like ECLASS). The templateId is the ID of the Submodel itself. It is used if a Submodel shall be referenced. The following holds:

For example, see Figure 21 and Figure 22.

According IEC 63278-1, a SMT element specifies the structure for a SubmodelElement. Especially, it specifies, to which concept repository entry for an information, relation or service or hierarchical structure (so called purpose) the SubmodelElement is related to. For the AASX of SMT, each SMT element is a SubmodelElement with kind = Template and the relation is done via the semanticId of the SubmodelElement.

To express the particular purpose of the structure, attributes shall specify:

These attributes might be specified by dedicated means of ConceptDescriptions (e.g. see the SAMM model [R9]) or by means of Qualifiers [6] (see below).

Furthermore, the AASX Package Explorer [R3] allows usage of the plugin AasxPluginGenericForms to assist users in creating Submodels based on SMTs. For this purpose, further attributes are provided here (see below).

The following Qualifiers may be used, to allow a SMT element to control the generation of instantiated SubmodelElements (see Table 9). These Qualifiers are available as presets for the AASX Package Explorer [R3].

The idShort of each SubmodelElement shall be unique in its namespace, e.g. the containing collection. At the same time, many users want the idShort to be a speaking name. In order to facilitate the automatic generation of speaking names, an addition such as "000" or "00" might be included in the idShort of an SMT element, which cardinality is other than "One". The number of zeros will correspond to the number of digits of a continuous numerical index for idShort.

Example: If a Submodel might describe multiple records, and a single record is described by multiple properties collected in a SubmodelElementCollection (SMC) with parent as Submodel, the application will be as described in Figure 23.

In certain cases, data of SubmodelElements is to be filled out by the user, which goes beyond strict specifications. This data cannot be left empty, because constraints of the meta model might be enforced by AAS frameworks (e.g. for version 3.0 of the meta model [6]). Therefore, the following values for References are foreseen:

For a Submodel template, each Submodel element template is semantically defined by referring to a semanticId, which identifies the semantic definition of that element.

The meta model of the AAS and the AASX PackageExplorer [R3] allows expressing ConceptDescriptions conformant to IEC 61360, e.g., for Properties. Describing such ConceptDescriptions e.g., enables defining units of measure and is therefore important for practical application. The semanticId of a Submodel element template refers to the identifier of such ConceptDescription.

The delivery of the SMT shall include all definitions of ConceptDescriptions which relate directly to the usage of the respective SMT. In particular, the ConceptDescriptions shall include definitions used in the definition tables described in Table row items.

If a concept is not already described by publicly accessible dictionaries, such as ECLASS, IEC CDD or [R4], a new concept repository item needs to be created, that is, a new identifier needs to be reserved for such a concept repository item and the respective ConceptDescription. This can be achieved by starting a standardization process in concept repositories such as ECLASS or IEC CDD. Alternatively, an identifier can be reserved utilizing [R4]. The main site of [R4] describes the registration process for such identifiers.