Added $filters to AAS QL & enhanced Fragment Fieldidentifiers by Martin187187 · Pull Request #532 · admin-shell-io/aas-specs-api

Martin187187 · 2026-02-10T14:52:49Z

implements Add optional FILTER to Query #517
added new Query Language Filter chapter in Query Language chapter.
Enhanced the FieldIdentifier Fragment Definition from just plain string to a BNF specification. => allow non leaf paths and disallow required paths.
updated Json schema & api accordingly.
Addition does not introduce breaking changes because it only adds new optional field
allow multiple filters instead of just 1 in the current security specification

…3-2_working Idta 01002 3 2 working

Updated the description of the $filters option in the Query Language section to clarify the filtering of Submodel elements.

…into filter

Updated query language documentation to include details on filtering out values based on 'HIDE_VALUE' in semanticId.

CLAassistant · 2026-02-10T14:53:05Z

All committers have signed the CLA.

documentation/IDTA-01002-3/modules/ROOT/partials/query-json-schema.json

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc

documentation/IDTA-01002-3/modules/ROOT/partials/bnf/grammar.bnf

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc

documentation/IDTA-01002-3/modules/ROOT/partials/bnf/grammar.bnf

Martin187187 · 2026-03-02T14:38:29Z

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc

        "USEFORMULA": {
          "type": "string"
        },
-        "FRAGMENT": {


There was a significant discrepancy between the security JSON schema and the API JSON schema. In the security specification, the fragment object is nested inside the filter object, but this is not the case in the API schema. I have now updated both documents to use the security version for consistency.

So is it a bug for 3.0.2?

Martin187187 · 2026-03-06T15:27:06Z

blocked by #548

mdanish98 · 2026-03-16T10:39:07Z

Hi @Martin187187 , thanks for addressing the remarks, I will wait for the #548 to be concluded first and then resume the review.

sebbader-sap · 2026-03-29T14:53:19Z

@mdanish98 #548 has been merged.

sebbader-sap · 2026-03-29T14:54:10Z

@Martin187187 is the PR still in "draft" or now in the "ready for review" state?

Martin187187 · 2026-03-29T17:46:12Z

@Martin187187 is the PR still in "draft" or now in the "ready for review" state?

I will have to resolve conflicts caused by the bugfixes. So it is currenlty only a draft.

BirgitBoss · 2026-03-31T10:38:53Z

Do we really add
documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/test/query/test1.json
to the documentation?

BirgitBoss · 2026-03-31T11:02:51Z

documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

+}
+
+----
+a| Selects Nameplate submodels and filters out `AddressInformation.Zipcode` data.


I have the feeling the semantics is opposite to the semantics of Security for FILTER. See example
https://industrialdigitaltwin.io/aas-specifications/IDTA-01004/v3.0.2/annex/text-access-rule-examples.html#_example_with_filter_statement

For Security it means: "filter" but not "Filter out".

The filter in example of Security says: only display those for which the condition is true. "Filter out", i.e. do not return the other specific Asset IDs.
In your example with condition "false" it is the same semantics (do not display any ZIPCODE because condition not true for any ZIPCODE)
but for HIDE_VALUE, the second example below, it is different: only semanticIds with "HIDE_VALUE" would be returned, all others would not be returned: but you explain it the other way around... so just add "$not"?

Could we add a Submodel example and the corresponding Result similar to the table before?

BirgitBoss · 2026-03-31T11:04:04Z

documentation/IDTA-01002-3/modules/ROOT/pages/changelog.adoc

 Major Changes:

-* ...
+* new: Enhanced the FieldIdentifier Fragment Definition from just plain string to a BNF specification. Extended the query language and security with field-based filters (`$filters` & `FILTERS` clauses) using field identifier fragments, and aligned the OpenAPI schemas and JSON Schema for queries and security rules accordingly. Addition does not introduce breaking changes because it only adds new optional field (https://github.com/admin-shell-io/aas-specs-api/issues/517[#517])


inconsistent, sometimes it is "$filter", sometimes it is "$filters" or it is "$filters" in JSON but $filter in BNF?

BirgitBoss · 2026-03-31T11:34:51Z

documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

+  "$condition": {
+    "$eq": [
+      {
+        "$field": "$sm#semanticId"


to be identical with BPN is should be $sm#semanticId.keys[].value, semanticId short cut only means $sm#semanticId.keys[0].value

BirgitBoss · 2026-03-31T11:36:38Z

documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

+----
+$sm#semanticId $eq
+  "https://admin-shell.io/idta/nameplate/3/0/Nameplate"
+$filter $sme#value $sm#semanticId.keys[].value $eq "HIDE_VALUE"


Suggested change

$filter $sme#value $sm#semanticId.keys[].value $eq "HIDE_VALUE"

$filter $sme#value

$not ($sm#semanticId.keys[].value $eq "HIDE_VALUE")

BirgitBoss · 2026-03-31T11:37:15Z

documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

+$sm#semanticId $eq
+  "https://admin-shell.io/idta/nameplate/3/0/Nameplate"
+$filter $sme#value $sm#semanticId.keys[].value $eq "HIDE_VALUE"
+$filter $sm#semanticId.keys[] $sm#semanticId.keys[].value $eq "HIDE_VALUE"


$sm#semanticId instead of $sm#semanticId.keys[] because complet semanticId displayed, not only the keys

BirgitBoss · 2026-03-31T11:38:37Z

documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

+----
+$sm#semanticId $eq
+  "https://admin-shell.io/idta/nameplate/3/0/Nameplate"
+$filter $sme.AddressInformation.Zipcode false


Suggested change

$filter $sme.AddressInformation.Zipcode false

$filter $sme.AddressInformation.Zipcode

false

BirgitBoss · 2026-03-31T11:40:22Z

documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

+$sm#semanticId $eq
+  "https://admin-shell.io/idta/nameplate/3/0/Nameplate"
+$filter $sme#value $sm#semanticId.keys[].value $eq "HIDE_VALUE"
+$filter $sm#semanticId.keys[] $sm#semanticId.keys[].value $eq "HIDE_VALUE"


Suggested change

$filter $sm#semanticId.keys[] $sm#semanticId.keys[].value $eq "HIDE_VALUE"

$filter $sm#semanticId

$not( $sm#semanticId.keys[].value $eq "HIDE_VALUE" )

BirgitBoss · 2026-03-31T11:45:45Z

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc

  "description": "This schema contains all classes that are shared between the AAS Query Language and the AAS Access Rule Language.",
+  "$ref": "#/definitions/Root",
  "definitions": {
+    "Root": {


Root seems not to be shared, root completely different for Query and ACL, no?

BirgitBoss · 2026-03-31T11:48:18Z

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc

@@ -1 +1 @@
 ....


probably it would be better to include a .json file for better checks (same in Part 1 vor Value-Only Schema)

BirgitBoss · 2026-03-31T11:52:39Z

documentation/IDTA-01002-3/modules/ROOT/partials/bnf/grammar.bnf

 <grammar> ::= <query> | <AllAccessPermissionRules>

-<query> ::= <selectStatement>? <logicalExpression>
+<query> ::= <selectStatement>? <logicalExpression> ( <ws> "$filter" (<ws> <queryFilterItem> )* )?


in your examples in query-language.adoc you use more than one "$filter" statement (with sinlge queryFilterItem), with implicit semantics "AND", here only one "$filter" statement but several queryFilterItems...

BirgitBoss · 2026-03-31T11:56:06Z

documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adoc

+}
+
+----
+a| Selects Nameplate submodels and filters out `AddressInformation.Zipcode` data.


I would not use the term "select" because there is no $select statement. A query with no $Select statement returns what exactly?

BirgitBoss · 2026-03-31T11:59:38Z

I recommend to add an annex with complete examples like in Security: https://industrialdigitaltwin.io/aas-specifications/IDTA-01004/v3.0.2/annex/text-access-rule-examples.html

BirgitBoss · 2026-03-31T12:07:53Z

documentation/IDTA-01002-3/modules/ROOT/partials/bnf/grammar.bnf

+<Filter> ::= 
+    "FILTER:" <ws> ( <SecurityQueryFilter> <ws> )
+
+<FilterList> ::= 
+    "FILTERLIST:" <ws> ( <SecurityQueryFilter> <ws> )*


What is the difference between a filter and a filter list? in you BNF Example in query-lanauge.adoc there are just two $filter objects in the query, so this is a filterlist?

BirgitBoss · 2026-03-31T12:13:28Z

documentation/IDTA-01002-3/modules/ROOT/partials/bnf/grammar.bnf

+<FieldIdentifierSM> ::= "$sm#" <FieldsSM>
+<FieldIdentifierSME> ::= "$sme" ( "." <idShortPath> )? "#" <FieldsSME>
+<FieldIdentifierCD> ::= "$cd#" <FieldsCD>
+<FieldIdentifierAasDescriptor> ::= "$aasdesc#" <AasDescriptorClause>


why is it here "Clause" and not "FieldsAasDescriptor" ?
Same for SmDescriptorClause

BirgitBoss · 2026-03-31T12:18:53Z

documentation/IDTA-01002-3/modules/ROOT/partials/bnf/grammar.bnf

+<SpecificAssetIdsClauseTail> ::= ".name" | ".value" | <ExternalSubjectIdClause>
+
+<SpecificAssetIdsClauseFragment> ::= <SpecificAssetIdsClauseHead> <SpecificAssetIdsClauseTailFragment>?
+<SpecificAssetIdsClauseTailFragment> ::= <ExternalSubjectIdClauseFragment>


is it because the other two are mandatory that it is not identical to SpecificAssetIdsClause ?

BirgitBoss and others added 19 commits December 12, 2025 15:58

Merge pull request admin-shell-io#520 from admin-shell-io/IDTA-01002-…

4e6cad9

…3-2_working Idta 01002 3 2 working

Change to $filter

3da2f09

Add FILTER to query

67c9424

added fragment fieldidentifier to bnf

5be900e

removed not allowed fragment fieldidentifier paths

6be4034

added query filter description & root can be filtered now

8dc108b

added example & updated bnf & moved filters to own section

ab6cf92

Clarify filtering of Submodel elements in Query Language

00c3547

Updated the description of the $filters option in the Query Language section to clarify the filtering of Submodel elements.

moved example

5604c1e

Merge branch 'filter' of https://github.com/Martin187187/aas-specs-api …

273161e

…into filter

removed duplicated section

221ebd2

added comment

c24ba07

Update description for Nameplate submodels query

93ace6b

Enhance query-language.adoc with filtering details

834e17a

Updated query language documentation to include details on filtering out values based on 'HIDE_VALUE' in semanticId.

added bnf

7ad8efb

update bnf

137b904

update bnf

3168f19

Fix typo in query language documentation

b5e1955

updated api

183b1b1

Martin187187 requested review from BirgitBoss, alexgordtop, aorzelskiGH, danielporta, g1zzm0, mjacoby, sebbader-sap, waltersve and zrgt as code owners February 10, 2026 14:52

github-advanced-security bot found potential problems Feb 10, 2026

View reviewed changes

documentation/IDTA-01002-3/modules/ROOT/partials/query-json-schema.json Fixed Show fixed Hide fixed

documentation/IDTA-01002-3/modules/ROOT/partials/query-json-schema.json Fixed Show fixed Hide fixed

Martin187187 mentioned this pull request Mar 2, 2026

add fragmentfieldidentifiers admin-shell-io/aas-specs-security#54

Draft

update bnf and json schema to be consistent with security spec

16355b9

github-advanced-security bot found potential problems Mar 2, 2026

View reviewed changes

make FILTER optional

a6cc6c7

github-advanced-security bot found potential problems Mar 2, 2026

View reviewed changes

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc Dismissed Show dismissed Hide dismissed

documentation/IDTA-01002-3/modules/ROOT/partials/bnf/grammar.bnf Dismissed Show dismissed Hide dismissed

Martin187187 commented Mar 2, 2026

View reviewed changes

Martin187187 marked this pull request as draft March 6, 2026 15:26

sebbader-sap requested a review from mdanish98 March 29, 2026 14:53

BirgitBoss reviewed Mar 31, 2026

View reviewed changes

BirgitBoss requested changes Mar 31, 2026

View reviewed changes

BirgitBoss reviewed Mar 31, 2026

View reviewed changes

	$filter $sme#value $sm#semanticId.keys[].value $eq "HIDE_VALUE"
	$filter $sme#value
	$not ($sm#semanticId.keys[].value $eq "HIDE_VALUE")

	$filter $sme.AddressInformation.Zipcode false
	$filter $sme.AddressInformation.Zipcode
	false

	$filter $sm#semanticId.keys[] $sm#semanticId.keys[].value $eq "HIDE_VALUE"
	$filter $sm#semanticId
	$not( $sm#semanticId.keys[].value $eq "HIDE_VALUE" )

Conversation

Martin187187 commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

CLAassistant commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Martin187187 commented Mar 6, 2026

Uh oh!

mdanish98 commented Mar 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sebbader-sap commented Mar 29, 2026

Uh oh!

sebbader-sap commented Mar 29, 2026

Uh oh!

Martin187187 commented Mar 29, 2026

Uh oh!

BirgitBoss commented Mar 31, 2026

Uh oh!

BirgitBoss Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BirgitBoss Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BirgitBoss Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BirgitBoss commented Mar 31, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

Martin187187 commented Feb 10, 2026 •

edited

Loading

CLAassistant commented Feb 10, 2026 •

edited

Loading

mdanish98 commented Mar 16, 2026 •

edited

Loading

BirgitBoss Mar 31, 2026 •

edited

Loading

BirgitBoss Mar 31, 2026 •

edited

Loading

BirgitBoss Mar 31, 2026 •

edited

Loading