[Task] HTML Documentation - provide more compact documentation figure

[BirgitBoss]

Is your task related to a problem? Please describe. As a developer of an aspect model I want to provide a comprehensive version for reviewing.

Up to now the HTML documentation only generates the full fledge figure that is often very difficult to read. The figure does not need to contain the complete specification: this is contained in the rest of the document but only gives an overview. (Or add both figures).

Describe the solution you'd like

This diagram (in PlantUML) could also be directly used in the AAS Submodel Template specification with some minor changes with resepct to the stereotypes used. So these should be configurable for Aspect and Collection and Entity.

Describe alternatives you've considered

Additional context Example of an submodel template specificyation overview figure:

Comparison to current representation of the Movement example:

[atextor]

I understand the need for a more compact figure, in particular when it's embedded in the HTML. I would provide two views or types of diagrams: One full diagram that also includes the descriptions (i.e., keep current diagram generation), and one "simplified" to be used in HTML.

Here it makes most sense to inline Properties into Aspects and Entities, but IMO Properties must not directly refer to datatypes, that would invalidate Characteristics as first-class model elements.

I imagine it like this:

(Note that I've also left out the trivial samm-c:Boolean Characteristic here).

For events and operations I probably would add additional sections in the Aspect box:

Maybe we can even inline Constraints into Traits.

[BirgitBoss]

Thank your for the proposal. Since I am reading UML figures like xml instances or JSON payload the diagram suggest to me that I have an object for the SingleEntity (with datatype) and an object for the Entity with x, y, z. This is what I wanted to avoid.

So probably my request is not only a compact diagram but a simplified one because you are right: yours would still contain all relevant information of the SAMM model itself. My proposal just ignores characteristics because for understanding the model the characteristics are not important. They are important for reuse and maintenance of the model.

[BirgitBoss]

The aasx-Package Explorer even supports a compact PlantUML generation that does not include the atomic properties but only Lists (SML) and Entities (SMC) because the models are getting quite large for some use cases: instead of It is also supported to start from any element within the model to create a PlantUML class diagram.

[atextor]

Thank your for the proposal. Since I am reading UML figures like xml instances or JSON payload the diagram suggest to me that I have an object for the SingleEntity (with datatype) and an object for the Entity with x, y, z. This is what I wanted to avoid.

But this is exactly what you have, the SingleEntity is a different thing than the Entity. The Aspect Model diagram represents the Aspect Model, not the data that is described by the model. Those two things can have separate descriptions, separate see references and could even be defined in different namespaces (which is unfortunately not visible in the diagram).

So probably my request is not only a compact diagram but a simplified one because you are right: yours would still contain all relevant information of the SAMM model itself. My proposal just ignores characteristics because for understanding the model the characteristics are not important. They are important for reuse and maintenance of the model.

I disagree, the Characteristics are very important for understanding the model; you could say that they carry the essential semantic information. For example, if there's a Property called maintainer with the effective datatype of xsd:string, and you don't know the Characteristic, you don't know whether the value is supposed to be the name of a person, the name of a company, an email address, a GitHub user handle, etc... this is the information that we create the Aspect Model for in the first place; if we leave this out, we could also just use a JSON schema instead.