Skip to content

SupplementalSemanticIds in AAS Queries #568

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

Draft
sebbader-sap wants to merge 5 commits into
base: IDTA-01002-3-2_working
Choose a base branch
from
+25 −3
Draft

SupplementalSemanticIds in AAS Queries #568

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
f48ccbe
adding supplemantalSemanticIds to the AAS Query
sebbader-sap Mar 29, 2026
89e3261
Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt
sebbader-sap Mar 30, 2026
5d64481
Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt
sebbader-sap Mar 30, 2026
17963b7
Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt
sebbader-sap Mar 30, 2026
c94085c
Update documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt
sebbader-sap Mar 30, 2026
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
1 change: 1 addition & 0 deletions documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ Minor Changes:
* Editorial fixes in Table 2 of the Query Language specification (https://github.com/admin-shell-io/aas-specs-api/issues/507[#507])
* Removed the `GetAllAssetAdministrationShellDescriptorsByAssetType` operation from the OpenAPI files for the Asset Administration Shell Registry Service Specification, as it was not intended to be included in the first place and is not implemented by any known implementation. (https://github.com/admin-shell-io/aas-specs-api/issues/515[#515])
* Editorial: Remove links to SwaggerHub from the HTTP API section, as the links are maintained in the service specifications and profiles sections. (https://github.com/admin-shell-io/aas-specs-api/issues/475[#475])
* Added `supplemantalSemanticIds` to the AAS Query Language specification (https://github.com/admin-shell-io/aas-specs-api/issues/524[#524])


=== Operation Changes w.r.t. V3.1.2 to V3.2
Expand Down
7 changes: 4 additions & 3 deletions documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,15 +231,16 @@

<FieldIdentifier> ::= "\"" ( <FieldIdentifierAAS> | <FieldIdentifierSM> | <FieldIdentifierSME> | <FieldIdentifierCD> | <FieldIdentifierAasDescriptor> | <FieldIdentifierSmDescriptor> ) "\""
<FieldIdentifierAAS> ::= "$aas#" ( "idShort" | "id" | "assetInformation.assetKind" | "assetInformation.assetType" | "assetInformation.globalAssetId" | "assetInformation." <SpecificAssetIdsClause> | "submodels" ( "[" ( [0-9]* ) "]" ) "." <ReferenceClause> )
<FieldIdentifierSM> ::= "$sm#" ( <SemanticIdClause> | "idShort" | "id" )
<FieldIdentifierSME> ::= "$sme" ( "." <idShortPath> )? "#" ( <SemanticIdClause> | "idShort" | "value" | "valueType" | "language" )
<FieldIdentifierSM> ::= "$sm#" ( <SemanticIdClause> | <SupplementalSemanticIdClause> | "idShort" | "id" )
<FieldIdentifierSME> ::= "$sme" ( "." <idShortPath> )? "#" ( <SemanticIdClause> | <SupplementalSemanticIdClause> | "idShort" | "value" | "valueType" | "language" )
<FieldIdentifierCD> ::= "$cd#" ( "idShort" | "id" ) <ws>
<FieldIdentifierAasDescriptor> ::= "$aasdesc#" ( "idShort" | "id" | "assetKind" | "assetType" | "globalAssetId" | <SpecificAssetIdsClause> | "endpoints" ( "[" ( [0-9]* ) "]" ) "." <EndpointClause> | "submodelDescriptors" ( "[" ( [0-9]* ) "]" ) "." <SmDescriptorClause> )
<FieldIdentifierSmDescriptor> ::= "$smdesc#" <SmDescriptorClause>
<SmDescriptorClause> ::= ( <SemanticIdClause> | "idShort" | "id" | "endpoints" ( "[" ( [0-9]* ) "]" ) "." <EndpointClause> )
<SmDescriptorClause> ::= ( <SemanticIdClause> | <SupplementalSemanticIdClause> | "idShort" | "id" | "endpoints" ( "[" ( [0-9]* ) "]" ) "." <EndpointClause> )
<EndpointClause> ::= "interface" | "protocolinformation.href"
<ReferenceClause> ::= ( "type" | "keys" ( "[" ( [0-9]* ) "]" ) ( ".type" | ".value" ) )
<SemanticIdClause> ::= ( "semanticId" | "semanticId." <ReferenceClause> )
<SupplementalSemanticIdClause> ::= ( "supplementalSemanticIds" | "supplementalSemanticIds" ( "[" ( [0-9]* ) "]" ) "." <ReferenceClause> )
<SpecificAssetIdsClause> ::= ( "specificAssetIds" ( "[" ( [0-9]* ) "]" ) ( ".name" | ".value" | ".externalSubjectId" | ".externalSubjectId." <ReferenceClause> ) )
<idShortPath> ::= ( <idShort> ("[" ( [0-9]* ) "]" )* ( "." <idShortPath> )* )
<idShort> ::= ( ( [a-z] | [A-Z] ) (( [a-z] | [A-Z] | [0-9] | "_" | "-" )* ( [a-z] | [A-Z] | [0-9] | "_" ) )? )
Expand Down
20 changes: 20 additions & 0 deletions documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -132,6 +132,10 @@
| `semanticId.type` | ReferenceType of a semanticId Reference | `$sm#semanticId.type`
| `semanticId.keys[<index>].type` | KeyType of a semanticId Reference | `$sm#semanticId.keys[].type`
| `semanticId.keys[<index>].value` | Value of a key of a semanticId Reference | `$sme#semanticId.keys[].value`
| `supplementalSemanticIds` | Shortcut for supplementalSemanticIds, see Clause xref:references[References] | `$sm#supplementalSemanticIds`
| `supplementalSemanticIds[<index>].type` | ReferenceType of a supplementalSemanticId Reference | `$sm#supplementalSemanticIds[].type`
| `supplementalSemanticIds[<index>].keys[<index>].type` | KeyType of a supplementalSemanticId Reference | `$sm#supplementalSemanticIds[].keys[].type`
| `supplementalSemanticIds[<index>].keys[<index>].value` | Value of a key of a supplementalSemanticId Reference | `$sm#supplementalSemanticIds[].keys[].value`
| `value` | Value of a Submodel Element | `$sme#value`
| `valueType` | ValueType of a Submodel Element | `$sme.someIdShort#valueType`
| `language` | Language of a Multilanguage Property | `$sme#language`
Expand Down Expand Up @@ -163,6 +167,10 @@
| `submodelDescriptors.semanticId.type` | ReferenceType of a semanticId Reference used in a referenced Submodel of an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.semanticId.type`
| `submodelDescriptors.semanticId.keys[<index>].type` | KeyType of a semanticId Reference used in a referenced Submodel of an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.semanticId.keys[].type`
| `submodelDescriptors.semanticId.keys[<index>].value` | Value of a key of a semanticId Reference used in a referenced Submodel of an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.semanticId.keys[].value`
| `submodelDescriptors.supplementalSemanticIds` | Shortcut for supplementalSemanticIds, see Clause xref:references[References] | `$aasdesc#submodelDescriptors.supplementalSemanticIds`
| `submodelDescriptors.supplementalSemanticIds[<index>].type` | ReferenceType of a supplementalSemanticId Reference used in a referenced Submodel of an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.supplementalSemanticIds[].type`
| `submodelDescriptors.supplementalSemanticIds[<index>].keys[<index>].type` | KeyType of a supplementalSemanticId Reference used in a referenced Submodel of an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.supplementalSemanticIds[].keys[].type`
| `submodelDescriptors.supplementalSemanticIds[<index>].keys[<index>].value` | Value of a key of a supplementalSemanticId Reference used in a referenced Submodel of an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.supplementalSemanticIds[].keys[].value`
| `submodelDescriptors.id` | Identifier of a referenced Submodel as available in an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.id`
| `submodelDescriptors.idShort` | idShort of a referenced Submodel as available in an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.idShort`
| `submodelDescriptors.endpoints[<index>].interface` | Endpoint interface of a referenced Submodel as available in an Asset Administration Shell Descriptor | `$aasdesc#submodelDescriptors.endpoints[0].interface`
Expand Down Expand Up @@ -382,7 +390,7 @@
To ease writing, `.keys[0].value` can be left off for References. +

semanticId is defined as the "value" of the first key of the semanticId Reference object.
The following two expressions are equivilant:

Check warning on line 393 in documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

View workflow job for this annotation

GitHub Actions / qodana

Typo 

Typo: In word 'equivilant'

....
<somePath>.semanticId
Expand All @@ -395,6 +403,18 @@
$sme#semanticId $eq "https://example.com/a/semantic/id"
....

This shall also work for supplementalSemanticIds, e.g.:

....
$sme#supplementalSemanticIds $eq "https://example.com/a/supplemental/semantic/id"
Copy link
Copy Markdown
Collaborator

@BirgitBoss BirgitBoss Mar 30, 2026 •
edited
Loading

Choose a reason for hiding this comment

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

it could be
$sme#supplementalSemanticIds $contains "https://example.com/a/supplemental/semantic/id"
since it is a set

$contains is for comparing two string... but so far we do not have set-operations, do we?

Copy link
Copy Markdown
Contributor Author

@sebbader-sap sebbader-sap Mar 30, 2026

Choose a reason for hiding this comment

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

At least I am not aware... Some query languages have an $in operator. But it then would need to have a different order:
"https://example.com/a/supplemental/semantic/id" $in $sme#supplementalSemanticIds
Also pretty big change.

Copy link
Copy Markdown
Contributor Author

@sebbader-sap sebbader-sap Mar 30, 2026

Choose a reason for hiding this comment

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

I thought it was clever to keep it close to $sme#semanticId. Not sure if it really is.

....

Which is equivilant to:
....
$sme#supplementalSemanticIds[0].keys[0].value $eq "https://example.com/a/supplemental/semantic/id"
Copy link
Copy Markdown
Collaborator

@BirgitBoss BirgitBoss Mar 30, 2026

Choose a reason for hiding this comment

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

Then with "contains" it would be

$sme#supplementalSemanticIds[0].keys[0].value $eq "https://example.com/a/supplemental/semantic/id" OR $sme#supplementalSemanticIds[1].keys[0].value $eq "https://example.com/a/supplemental/semantic/id" OR $sme#supplementalSemanticIds[2].keys[0].value $eq "https://example.com/a/supplemental/semantic/id" a.s.o.

In general: how do we know what is the highest number in a list and how long to iterate?

Copy link
Copy Markdown
Contributor Author

@sebbader-sap sebbader-sap Mar 30, 2026

Choose a reason for hiding this comment

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

In general: how do we know what is the highest number in a list and how long to iterate?

Currently: Not at all. But no index indicates "anywhere", so this might work better:
$sme#supplementalSemanticIds[].keys[].value $eq "https://example.com/a/supplemental/semantic/id"

Copy link
Copy Markdown
Collaborator

@BirgitBoss BirgitBoss Mar 31, 2026

Choose a reason for hiding this comment

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

I think the seoncd [] on keys[] should remain keys[0] because then it is already a single semanticId

Copy link
Copy Markdown
Collaborator

@BirgitBoss BirgitBoss Mar 31, 2026

Choose a reason for hiding this comment

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

Suggested change
$sme#supplementalSemanticIds[0].keys[0].value $eq "https://example.com/a/supplemental/semantic/id"
$sme#supplementalSemanticIds[].keys[0].value $eq "https://example.com/a/supplemental/semantic/id"

....


== Match of Elements in Lists

The `$match` operator signals that the following clauses (a) contain at least 1 list of elements with `[]` syntax, and that (b) all conditions shall be evaluated on the same element of this list.
Expand Down
Loading