docs(terms): add cross-spec terminology matrix (IDTA-01002/01004)#689
Open
aorzelskiGH wants to merge 1 commit intoIDTA-01001-3-2_Workingfrom
Open
docs(terms): add cross-spec terminology matrix (IDTA-01002/01004)#689aorzelskiGH wants to merge 1 commit intoIDTA-01001-3-2_Workingfrom
aorzelskiGH wants to merge 1 commit intoIDTA-01001-3-2_Workingfrom
Conversation
Introduce a small, normative table at the end of the Terms section that relates every top-level AAS entity to its API resource / path segment and its Query / Access-Rule FieldIdentifier prefix. The table covers AssetAdministrationShell, Submodel, SubmodelElement, ConceptDescription and the corresponding Descriptors, and fixes the case convention once for all three specs ($aas / $sm / $sme / $cd / $aasdesc / $smdesc). Refs: Review Finding T-09 Made-with: Cursor
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
|
|
||
| [#cross-spec-terminology] | ||
| == Terminology Across IDTA-01001, IDTA-01002 and IDTA-01004 | ||
|
|
| |=== | ||
| | Metamodel Class | API Resource / Path Segment | Query / Access-Rule Prefix | Example | ||
|
|
||
| | AssetAdministrationShell |
| | `$aas` | ||
| | `$aas("https://example.com/aas/1")` | ||
|
|
||
| | Submodel |
| | `$sm` | ||
| | `$sm("https://example.com/sm/1")` | ||
|
|
||
| | SubmodelElement |
| | `$sme` | ||
| | `$sme("https://example.com/sm/1").path.to.element` | ||
|
|
||
| | ConceptDescription |
| | `$cd` | ||
| | `$cd("https://example.com/cd/1")` | ||
|
|
||
| | AssetAdministrationShellDescriptor |
| | `$aasdesc` | ||
| | `$aasdesc("https://example.com/aas/1")` | ||
|
|
||
| | SubmodelDescriptor |
| | `$smdesc` | ||
| | `$smdesc("https://example.com/sm/1")` | ||
| |=== | ||
|
|
BirgitBoss
reviewed
Apr 20, 2026
Collaborator
BirgitBoss
left a comment
BirgitBoss
left a comment
There was a problem hiding this comment.
so far in Part 1 the terms "AssetAdministrationShellDescriptor" and "SubmodelDescriptor" were not introduced
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Add a normative cross-specification terminology matrix at the end of the "Terms, Definitions and Abbreviations" section. The table maps every top-level AAS entity to its API resource / path segment (IDTA-01002) and its Query / Access-Rule FieldIdentifier prefix (IDTA-01002 Query Language and IDTA-01004 Access Rule Model).
Problem
The three specifications use different surface forms for the same concept:
AssetAdministrationShell,Submodel, ...)./shells,/submodels, ...).$aas,$sm,$sme,$cd,$aasdesc,$smdesc).Readers who only work with one spec keep producing small inconsistencies (e.g.
$aasDescvs.$aasdesc, "Shell" vs. "AAS"), and new editors have to rediscover the mapping each review cycle.Solution
Add a single cross-reference table to the Metamodel's Terms section. The API and Security specs can reference this table instead of duplicating the mapping. The table also states that prefixes are lower-case and that variants like
$aasDescMUST be rejected by parsers.Affected files
documentation/IDTA-01001/modules/ROOT/pages/terms-definitions-and-abbreviations.adocReview notes
Refs: Review Finding T-09