CanonicalAAS: Define Ordering Rules and Canonical Representation for AAS

[mhrimaz]

Is your feature request related to a problem? Please describe.
In AAS only at two places we conceptually have ordering :

• SubmodelElementList when the orderRelevant flag is true
• The order of Keys within Reference .

In all other scenarios, ordering has no impact on the meaning of the asset. For example, elements inside a Submodel are conceptually unordered, meaning their sequence does not carry semantic significance.

However, the issue arises because the JSON representation of AAS uses arrays rather than dictionaries for serialization. While this approach is practical and widely supported, it unintentionally suggests that the order of elements in arrays is meaningful. This misunderstanding leads to users and tools, such as Package Explorer, implementing ordering-related features like "Move Up" and "Move Down" for elements inside a Submodel, which is conceptually incorrect.

This creates a situation where users and developers rely on ordering where it is not intended, causing confusion and potential interoperability issues. Addressing this misconception is critical to aligning implementations with the intended AAS concepts.

So if inside the ContactInformations Submodel we have this ordering:

Changing the order shouldn't be important for people. Which I am sure it is not the case:

But if your AAS is in circulation between diferent system, and for some reason they decide to mess around with the ordering of elements (at JSON serialization level), then it will be confusing.

Describe the solution you'd like

The Asset Administration Shell (AAS) doesn’t have a canonical form, which can lead to instability in how data is serialized. Similar to JSON canonicalization, having a standard format for AAS ensures consistent ordering and structure, making debugging easier. It also simplifies version control, such as using Git, by making it clear what has changed between versions. Additionally, a canonical form would help REST APIs provide data in a stable and predictable way, improving compatibility and reliability.

• Clients MUST NOT assume or imply any specific ordering of order-irrelevant elements, such as elements inside a Submodel. This is a common pitfall that can lead to errors when data ordering is not relevant from the perspective of metamodel.
• APIs MAY reorder elements to follow a canonical form where computationally feasible, unless the specific ordering of elements is critical to the meaning or functionality of the AAS.
• We need CanonicalAAS which describe how things should be normalized. Other canonicalization approach might be relevant and be reusable. See canonical XML , canonical JSON and canonical RDF.

Additional context
This is particularly relevant for the IDTA Ontology Workgroup, as ordering in RDF needs special consideration. If we only preserve the order for elements where it matters, round-tripping between JSON/XML and RDF (e.g., for Submodel elements) may result in changes to the order of other elements. If clients assume a specific order for purposes like display or processing, this can lead to interoperability issues. However, if we preserve the order for all elements to ensure a stable round-trip, we deviate from the correct conceptual model, where order should only matter for specific elements.