Skip to content

Restructure documentation #811

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Restructure documentation #811

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d0131f0
Update documentation:
Yauhenikapl Sep 8, 2025
60d5f49
Refine developer guide: improve headings, align terminology, and upda…
Yauhenikapl Sep 13, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions documentation/developer-guide/antora.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
name: esmf-developer-guide
title: ESMF SDK Developer Guide
title: JAVA SDK & SAMM CLI
version: 'master'
start_page: ROOT:index.adoc
nav:
- modules/tooling-guide/nav.adoc
- modules/static-metaclasses/nav.adoc
- modules/static-metaclasses/nav.adoc
6 changes: 3 additions & 3 deletions documentation/developer-guide/modules/ROOT/pages/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
= ESMF SDK Developer Guide
= JAVA SDK

The ESMF SDK Developer Guide helps you to get up-and-running with the ESMF SDK developed within the
The JAVA SDK Developer Guide helps you to get up-and-running with the ESMF SDK developed within the
Eclipse Semantic Modeling Framework (ESMF). It covers all possible scenarios, no matter whether you
are planning to build a solution with the SDK, model your Aspect data, implement your own customized
Aspect or want to integrate existing assets and systems.
Aspect or want to integrate existing assets and systems.
10 changes: 8 additions & 2 deletions documentation/developer-guide/modules/tooling-guide/nav.adoc
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Now that we have a dedicated top-level section on Java APIs, the content of the current "Using Java Static Meta Classes" section (i.e. everything in documentation/modules/static-metaclasses) should be moved here.

  1. Create a new page modules/tooling-guide/pages/java-static-meta-classes.adoc that contains the contents of modules/static-metaclasses/pages/*.adoc (in the order index, basic-usage, advanced-usage). Header levels might need to be adjusted.
  2. Add page-aliases to the new .adoc to make sure that links don't break when people try to use bookmarks
  3. Add a corresponding entry here in nav.adoc
  4. Remove the static-metaclasses module

Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
* xref:samm-cli.adoc[SAMM CLI]
* xref:java-aspect-tooling.adoc[Java APIs for Aspect Models]
* xref:maven-plugin.adoc[Maven Plugin]
* Java APIs for Aspect Models
xref:java-aspect-tooling.adoc[Getting Started & Loading]
xref:java-model-creation.adoc[Creating & Modifying Models]
xref:java-validation.adoc[Validation]
xref:java-code-generation.adoc[Code Generation]
xref:java-documentation-generation.adoc[Documentation Generation]
xref:java-aas-mapping.adoc[AAS Integration]
* xref:error-codes.adoc[Error Codes and Validation Results]
* xref:best-practices.adoc[Best Practices]
* xref:bamm-migration.adoc[Migration from BAMM]
* xref:bamm-migration.adoc[Migration from BAMM]
138 changes: 138 additions & 0 deletions documentation/developer-guide/modules/tooling-guide/pages/java-aas-mapping.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,138 @@
:page-partial:

[[mapping-aas]]
= Mapping Aspect Models to Asset Administration Shell (AAS) Submodel Templates
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section should be moved to an own top-level topic (outside of the Java APIs section), because it is not Java-specific.


The Asset Administration Shell (AAS) and its
https://www.plattform-i40.de/IP/Redaktion/EN/Standardartikel/specification-administrationshell.html[information
model] is a widely recognized standard developed by the https://industrialdigitaltwin.org[Industrial
Digital Twin Association (IDTA)] to express and handle Digital Twins. Central element of the AAS is
the concept of Submodels, which describe certain aspects of a Digital Twin.

The SAMM Aspect Meta Model allows to specify aspects of a digital twin and its semantics. The AAS
Generator module provides mapping implementations to derive AAS Submodels from SAMM Aspect Models.
On the one hand, this allows to integrate SAMM models in AAS environments and on the other hand it
allows AAS submodels to be described with rich semantics, as it is possible with SAMM.

[[details-mapping-aas]]
== Details of the Mapping Concept

In the following section, the mapping rules applied by the generator are explained. The rules apply
to https://eclipse-esmf.github.io/samm-specification/2.0.0/index.html[SAMM v2.0.0] and
https://www.plattform-i40.de/IP/Redaktion/EN/Downloads/Publikation/Details_of_the_Asset_Administration_Shell_Part1_V3.html[AAS
Specification Part 1 V3.0RC01].

[cols="1,1,2"]
|===
| SAMM | AAS | Comment

| **samm:Aspect** | aas:Submodel with kind=Template | Empty Asset and AssetAdministrationShell entries are added to the output file

| samm:name | aas:Submodel.idShort |

| samm:preferredName | aas:Submodel.displayName |

| samm:description | aas:Submodel.description |

| samm:property | see **samm:Property** |

| samm:operation | see **samm:Operation** |

| samm:Aspect.urn | aas:Submodel.semanticId |

| **samm:Property** | aas:Property, aas:SubmodelElementCollection | The AAS type is derived from the type of the SAMM Characteristic specifying the SAMM property. Depending on the type it is decided what the resulting AAS element will be. In case of an Entity it will result in a SubmodelElementCollection. It will also be a SubmodelElementCollection if the SAMM Characteristic is of a Collection type (see the https://eclipse-esmf.github.io/samm-specification/2.0.0/characteristics.html[Characteristics taxonomy]). In all other cases an aas:Property will be generated

| samm:Property.name | aas:Property.idShort |

| samm:Property.urn | aas:ConceptDescription.identification.id, aas:Property.semanticId|

| samm:Property.preferredName | aas:Property.displayName |

| samm:Property.description | aas:Property.description | Note: Also mapped to aas:DataSpecificationIEC61360.definition of the aas:ConceptDescription of this property

| samm:Property.exampleValue |aas:Property.value |

| samm:Characteristic.dataType | aas:Property.valueType |

| **samm:Operation** | Operation | in/out parameters are not used in SAMM so the mapping only generates input variables and output variables in AAS

| xref:samm-specification:ROOT:characteristics.adoc#characteristic-characteristic[**samm-c:Characteristic**] | aas:SubmodelElement, aas:ConceptDescription | Characteristics in SAMM define the semantics of a property, which includes there types as well as links to further definitions (standards, dictionaries, etc), a natural language description and name in different languages. Type and description are separated in AAS, which is why there is not a one-to-one mapping of a Characteristic to one element in AAS but rather Characteristics are used in the mapping of Properties, first, to guide the generation process and, second, to capture semantics in ConceptDescriptions of properties with data specification "DataSpecificationIEC61360" of the AAS.

| xref:samm-specification:ROOT:characteristics.adoc#collection-characteristic[**samm-c:Collection**] | aas:SubmodelElementList, aas:ConceptDescription | The general remarks to Characteristics apply also to Collection type Characteristics. However, properties referencing Collections are mapped to SubmodelElementLists. Specific properties of collections are mapped. samm:Set is unique, samm:SortedSet is unique and sorted, samm:List is sorted.

| xref:samm-specification:ROOT:characteristics.adoc#quantifiable-characteristic[**samm-c:Quantifiable**] | aas:SubmodelElement, aas:ConceptDescription | The general remarks to Characteristics apply also to Quantifiable type Characteristics. Quantifiables (also Duration and Measurement) reference a unit, which is added to the ConceptDescription corresponding the mapped Characteristic.

| xref:samm-specification:ROOT:characteristics.adoc#either-characteristic[**samm-c:Either**] | aas:SubmodelElement, aas:ConceptDescription | The general remarks to Characteristics apply also to Either. However, the Either characteristic has two distinct entries of which one is to be selected. This concept is not present in AAS. Thus, both entries will be written to a Submodel template, where one has to be ignored.

| xref:samm-specification:ROOT:characteristics.adoc#trait-characteristic[**samm-c:Trait**] | aas:SubmodelElement, aas:ConceptDescription | The general remarks to Characteristics apply also to Trait. However, the constraint of a trait will be ignored and only the base type will be evaluated, which will act as the characteristic of a property.

| xref:samm-specification:ROOT:characteristics.adoc#code-characteristic[**samm-c:Code**] | aas:SubmodelElement, aas:ConceptDescription | Similar to plain Characteristic.

| xref:samm-specification:ROOT:characteristics.adoc#structured-value-characteristic[**samm-c:StructuredValue**] | aas:SubmodelElement, aas:ConceptDescription | The general remarks to Characteristics apply also to StructuredValue. However, AAS has no concpet like deconstruction rule. Thus, the deconstruction rule and the sub properties of the deconstruction entity will be ignored and only the Characteristic is mapped.

| xref:samm-specification:ROOT:characteristics.adoc#enumeration-characteristic[**samm-c:Enumeration**] | aas:SubmodelElement, aas:ConceptDescription | The general remarks to Characteristics apply also to Enumerations. Additionally, the values of an Enumeration are mapped to a valueList of a DataSpecificationIEC61360.

| xref:samm-specification:ROOT:characteristics.adoc#state-characteristic[**samm-c:State**] | aas:SubmodelElement, aas:ConceptDescription | Same as Enumeration.

| xref:samm-specification:ROOT:characteristics.adoc#MultiLanguageText[samm-c:MultiLanguageText] | aas:MultiLanguageProperty | if a MultiLanguageText is used in SAMM it is mapped to the MultiLanguageProperty in AAS.
|===

== Known Limitations
The AAS Generator implements a base set of features, which are mapped from SAMM to AAS.
However, there are still limitations:

* Predefined entity mapping (FileResource would be mapped to aas:File)
* samm-c:Either is mapped to aas:SubmodelElementCollection with two entries for left and right side
* Recursive optional properties of SAMM model are not included in output but dropped straight away

== Translate Aspect Model to AAS

The following code demonstrates how the API to translate an Aspect Model into one of the valid AAS
formats (JSON, XML, AASX) is used:

++++
<details>
<summary>Show used imports</summary>
++++
[source,java,indent=0,subs="+macros,+quotes"]
----
include::example$GenerateAas.java[tags=imports]
----
++++
</details>
++++

[source,java,indent=0,subs="+macros,+quotes"]
----
include::example$GenerateAas.java[tags=generate]
----

To include the translator artifact, use the following dependencies:

include::esmf-developer-guide:ROOT:partial$esmf-aspect-model-aas-generator-artifact.adoc[]

[[translate-aas-to-aspect-model]]
== Translate AAS to Aspect Model

It is also possible to translate AAS Submodel Templates to Aspect Models using a best-effort. The
following example shows how the API to translate an AAS environment containing one or more Submodel
Templates to Aspect Models:

++++
<details>
<summary>Show used imports</summary>
++++
[source,java,indent=0,subs="+macros,+quotes"]
----
include::example$GenerateAspectFromAas.java[tags=imports]
----
++++
</details>
++++

[source,java,indent=0,subs="+macros,+quotes"]
----
include::example$GenerateAspectFromAas.java[tags=generate]
----

To include the translator artifact, use the same same dependencies as shown above in section <<translate-aas-to-aspect-model>>.
Loading
Loading