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

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/query-json-schema.json

Martin187187 · 2026-02-11T08:38:04Z

I would really like to remove the following section in the Json Security specification:

"FRAGMENT": {
          "type": "string"
        },
        "FILTER": {
          "$ref": "#/definitions/logicalExpression",
          "additionalProperties": false
        },
        "USEFILTER": {
          "type": "string"
        },

This is redundant because of the newly introduced FILTERLIST:

"FILTERLIST": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/SecurityQueryFilter"
          }
        }

I didnt remove it to not cause any breaking changes.

mdanish98

Hi @Martin187187 ,

thanks a lot for this pull request.

I have reviewed this PR and provided the following review remarks mainly for naming inconsistency. Please note that the naming inconsistency might not be limited to what I pointed out, so please check other files and locations.

mdanish98 · 2026-02-26T05:54:20Z

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

+[source,json]
+----
+{
+  "condition": {


This should be either $condition or $formula depending on the final decision, as pointed out in another comment.

mdanish98 · 2026-02-26T05:56:22Z

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

          "pattern": "^id$"
        },
-        "$condition": {
+        "$formula": {


There are some naming inconsistency:
Here in query-json-schema.json uses $formula (lines 750 & 761)
openapi.yaml still uses $condition (lines 802 & 812)
query-language.adoc also has $condition (e.g., line 690)

We should use either $condition or $formula to be consistent.

I agree that $condition is the better choice, and I will update $formula accordingly. That said, the security layer currently relies on FORMULA, as defined in the specification, which introduces a naming inconsistency.

mdanish98 · 2026-02-26T05:58:51Z

Part2-API-Schemas/openapi.yaml

@@ -784,6 +801,13 @@ components:
          pattern: ^id$
        $condition:


Highlighting the naming inconsistency as explained in the above comment.

mdanish98 · 2026-02-26T05:59:12Z

Part2-API-Schemas/openapi.yaml

+          items:
+            $ref: '#/components/schemas/QueryFilter'
      required:
        - $condition


Highlighting the naming inconsistency as explained in the above comment.

mdanish98 · 2026-02-26T06:02:11Z

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

Please update all JSON examples that use $condition to use $formula. Also, I have noticed that some examples uses condition without a $ prefix, so please consider this also when you search and replace.

I would rather use $condition. I there a reason why you prefer $formula?

No, I don't have any preferences, please use whatever makes sense and aligns with the AAS QL. This remarks is only to make sure whichever we decide, we use it everywhere and not a mix.

I think in Security in ACL it is FORMULA (and CONDITION) whereas in the query language only "condition" is used, there is no $formula, only a $condition in Part 2

mdanish98 · 2026-02-26T06:06:46Z

Also, I am seeing some alerts from GitHub code scanning, please either fix it or dismiss it.

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

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

Martin187187 · 2026-02-26T09:13:52Z

Hi @Martin187187 ,

thanks a lot for this pull request.

I have reviewed this PR and provided the following review remarks mainly for naming inconsistency. Please note that the naming inconsistency might not be limited to what I pointed out, so please check other files and locations.

Thanks alot for your review @mdanish98. I fixed the naming inconsistencies.

documentation/IDTA-01002-3/modules/ROOT/pages/json-grammar.txt

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

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

Martin187187 · 2026-03-02T12:28:16Z

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

I changed a lot here because:

added Fragment Field Identifier that are used to express what to filter (different to normal field identifier

I noticed huge gaps between the json and bnf. I fixed the inconsistencies in the BNF so JSON schema has no breaking changes

Martin187187 · 2026-03-02T12:55:07Z

I’ve updated this PR after identifying several inconsistencies and gaps between the JSON Schema and the BNF.

Specifically:

Aligned the BNF with the JSON Schema to ensure consistent terminology (e.g., avoiding different keywords for the same concept).
Improved and clarified the required logic in the JSON Schema.
Verified the updated schema against existing access rules and queries currently used in BaSyx to ensure compatibility and correctness.

If you’d like to review the test cases or see how I validated the schema, you can find them here:
https://github.com/Martin187187/basyx-go-components/tree/json-schema-tests/internal/common/security/schema_tests

Happy to provide additional test data or walk through the validation approach if needed.

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?

yes it is fixed already

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?

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

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

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

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

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

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

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

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

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

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

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

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

-    "modelStringPattern": {
+    "FieldIdentifier": {
+      "type": "string",
+      "pattern": "^(?:\\$aas#(?:idShort|id|assetInformation\\.assetKind|assetInformation\\.assetType|assetInformation\\.globalAssetId|assetInformation\\.specificAssetIds\\[[0-9]*\\]\\.(?:name|value|externalSubjectId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?)|submodels\\[[0-9]*\\]\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))|\\$sm#(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|id)|\\$sme(?:\\.[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?(?:\\[[0-9]*\\])*(?:\\.[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?(?:\\[[0-9]*\\])*)*)?#(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|value|valueType|language)|\\$cd#(?:idShort|id)|\\$aasdesc#(?:idShort|id|assetKind|assetType|globalAssetId|specificAssetIds\\[[0-9]*\\]\\.(?:name|value|externalSubjectId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?)|endpoints\\[[0-9]*\\]\\.(?:interface|protocolinformation\\.href)|submodelDescriptors\\[[0-9]*\\]\\.(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|id|endpoints\\[[0-9]*\\]\\.(?:interface|protocolinformation\\.href)))|\\$smdesc#(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|id|endpoints\\[[0-9]*\\]\\.(?:interface|protocolinformation\\.href)))$"


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

+    "FragmentFieldIdentifier": {
      "type": "string",
-       "pattern": "^(?:\\$aas#(?:idShort|id|assetInformation\\.assetKind|assetInformation\\.assetType|assetInformation\\.globalAssetId|assetInformation\\.specificAssetIds\\[[0-9]*\\]\\.(?:name|value|externalSubjectId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?)|submodels\\[[0-9]*\\]\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))|\\$sm#(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|id)|\\$sme(?:\\.[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?(?:\\[[0-9]*\\])*(?:\\.[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?(?:\\[[0-9]*\\])*)*)?#(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|value|valueType|language)|\\$cd#(?:idShort|id)|\\$aasdesc#(?:idShort|id|assetKind|assetType|globalAssetId|specificAssetIds\\[[0-9]*\\]\\.(?:name|value|externalSubjectId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?)|endpoints\\[[0-9]*\\]\\.(?:interface|protocolinformation\\.href)|submodelDescriptors\\[[0-9]*\\]\\.(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|id|endpoints\\[[0-9]*\\]\\.(?:interface|protocolinformation\\.href)))|\\$smdesc#(?:semanticId(?:\\.(?:type|keys\\[[0-9]*\\]\\.(?:type|value)))?|idShort|id|endpoints\\[[0-9]*\\]\\.(?:interface|protocolinformation\\.href)))$"
+      "pattern": "^(?:\\$aas#(?:idShort|assetInformation\\.assetType|assetInformation\\.globalAssetId|assetInformation\\.specificAssetIds\\[[0-9]*\\](?:\\.externalSubjectId(?:\\.keys\\[[0-9]*\\])?)?|submodels\\[[0-9]*\\](?:\\.keys\\[[0-9]*\\])?)|\\$sm#(?:semanticId(?:\\.keys\\[[0-9]*\\])?|idShort|id)|\\$sme(?:\\.[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?(?:\\[[0-9]*\\])*(?:\\.[A-Za-z](?:[A-Za-z0-9_-]*[A-Za-z0-9_])?(?:\\[[0-9]*\\])*)*)?(?:#(?:semanticId(?:\\.keys\\[[0-9]*\\])?|idShort|value|valueType|language))?|\\$cd#idShort|\\$aasdesc#(?:idShort|description|displayName|extension|administration|assetKind|assetType|globalAssetId|specificAssetIds\\[[0-9]*\\](?:\\.externalSubjectId(?:\\.keys\\[[0-9]*\\])?)?|endpoints\\[[0-9]*\\]|submodelDescriptors\\[[0-9]*\\](?:\\.(?:semanticId(?:\\.keys\\[[0-9]*\\])?|idShort|endpoints\\[[0-9]*\\]))?)|\\$smdesc#(?:semanticId(?:\\.keys\\[[0-9]*\\])?|idShort|endpoints\\[[0-9]*\\]))$"


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

-    <FragmentObject> <ws>
+    ( ( "FORMULA:" <ws> <logicalExpression> <ws> ) | ( <UseFormula> <ws> ) ) 
+    ( "FILTER:" <ws> <SecurityQueryFilter> )? 
+    ( "FILTERLIST:" <ws> ( <SecurityQueryFilter> <ws> )* )?


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

          "$ref": "#/definitions/SecurityQueryFilter",
          "additionalProperties": false
+        },
+        "FILTERLIST": {


Martin187187

I resolved all conflicts. This is ready for final review now

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

Martin187187 · 2026-04-07T12:35:09Z

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

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


yes it is fixed already

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

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

Martin187187 · 2026-04-07T13:38:38Z

For review you can use https://regex101.com/ to verify regex changes and https://bnfplayground.pauliankline.com/ for bnf changes

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 AI 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

github-advanced-security AI found potential problems Feb 11, 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

github-advanced-security AI found potential problems Feb 11, 2026

View reviewed changes

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc Fixed Show fixed Hide fixed

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

sebbader-sap requested a review from mdanish98 February 12, 2026 08:14

mdanish98 requested changes Feb 26, 2026

View reviewed changes

github-advanced-security AI found potential problems Feb 26, 2026

View reviewed changes

documentation/IDTA-01002-3/modules/ROOT/pages/schema.adoc Fixed Show fixed Hide fixed

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

Martin187187 added the requires workstream approval label Mar 2, 2026

Martin187187 mentioned this pull request Mar 2, 2026

Add optional FILTER to Query #517

Open

1 task

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

View reviewed changes

Martin187187 commented Mar 2, 2026

View reviewed changes

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

View reviewed changes

Martin187187 mentioned this pull request Mar 2, 2026

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

Open

github-advanced-security AI 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 Fixed Show fixed Hide fixed

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