eclipse-esmf / esmf-semantic-aspect-meta-model

Formal and textual specification of the Semantic Aspect Meta Model (SAMM)
https://eclipse-esmf.github.io/samm-specification/snapshot/index.html
Mozilla Public License 2.0
46 stars 9 forks source link

[Task] Do not force strict naming conventions #270

Open BirgitBoss opened 7 months ago

BirgitBoss commented 7 months ago

SAMM documentation contains also naming convention for aspects, properties etc. (https://eclipse-esmf.github.io/samm-specification/2.1.0/modeling-guidelines.html#naming-rules) However, in other model formats other rules are allowed and followed. For example, in Asset AdministrationShell (see e.g. https://github.com/admin-shell-io/aas-specs/issues/295). So, if converting existing submodel templates to SAMM many names need to be changed. Even worse: ValueOnly-Format might not be identical any longer when names are changed. This means in practice that for the JSON payload the CLI of ESMF cannot be used any longer.

1) the formulation is not "must" or "shall" but "follows": use clear semantics whether these rules must be followed or are just recommendations (should or may)

2) for naming just define regular expression of allowed characters. Tooling like Aspect Model Editor may on request support different naming conventions to be followed when modelling with SAMM. Put naming convetions to "Best practice" chapter of documentation.

Information: In AAS the following names are all valid: ^[a-zA-Z][a-zA-Z0-9-]*[a-zA-Z0-9]+$

atextor commented 6 months ago

I agree with the point that the wording in the spec is not sufficiently explicit, i.e., "must" or "shall" must be used. However, the strict naming rules for identifiers are intentional. For every technical use of an Aspect Model, such as Java Code generation or generation of OpenAPI specifications, the tools must be able to rely on a naming scheme, which can then deterministically be converted to other naming schemes (such as spinal-case or snake_case) and vice versa. For example:

This would not be possible with arbitrary naming conventions.

For JSON payload/ValueOnly the samm:payloadName may always be used if compatibility with a different naming schema in the JSON is necessary:

:MyAspect a samm:Aspect ;
  samm:properties ( [ samm:property :myProperty ; samm:payloadName "my_property" ] ) .

:myProperty a samm:Property ;
  samm:characteristic samm-c:Text .

leads to the payload structure

{
  "my_property": "..."
}