Skip to content

Commit d810738

Browse files
Martin187187Martin187187
committed
updated filter specification
1 parent 2e70ff0 commit d810738

9 files changed

Lines changed: 286 additions & 60 deletions

File tree

‎Part2-API-Schemas/openapi.yaml‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -625,10 +625,14 @@ components:
625625
type: string
626626
pattern: "^-?(([1-9][0-9][0-9][0-9]+)|(0[0-9][0-9][0-9]))-((0[1-9])|(1[0-2]))-((0[1-9])|([12][0-9])|(3[01]))T(((([01][0-9])|(2[0-3])):[0-5][0-9]:([0-5][0-9])(\\.[0-9]+)?)|24:00:00(\\.0+)?)(Z|\\+00:00|-00:00)$"
627627
type: object
628-
modelStringPattern:
628+
FieldIdentifier:
629629
type: string
630630
pattern: >-
631631
^(?:\$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)))$
632+
FragmentFieldIdentifier:
633+
type: string
634+
pattern: >-
635+
^(?:\$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]*\]))$
632636
MultiLanguagePropertyMetadata:
633637
allOf:
634638
- $ref: "#/components/schemas/SubmodelElementAttributes"
@@ -792,7 +796,22 @@ components:
792796
pattern: ^id$
793797
$condition:
794798
$ref: '#/components/schemas/logicalExpression'
799+
$filters:
800+
type: array
801+
items:
802+
$ref: '#/components/schemas/QueryFilter'
803+
required:
804+
- $condition
805+
additionalProperties: false
806+
QueryFilter:
807+
type: object
808+
properties:
809+
$fragment:
810+
$ref: '#/components/schemas/FragmentFieldIdentifier'
811+
$condition:
812+
$ref: '#/components/schemas/logicalExpression'
795813
required:
814+
- $fragment
796815
- $condition
797816
additionalProperties: false
798817
QueryResultAssetAdministrationShell:
@@ -1054,7 +1073,7 @@ components:
10541073
type: object
10551074
properties:
10561075
$field:
1057-
$ref: '#/components/schemas/modelStringPattern'
1076+
$ref: '#/components/schemas/FieldIdentifier'
10581077
$strVal:
10591078
$ref: '#/components/schemas/standardString'
10601079
$strCast:
@@ -1178,7 +1197,7 @@ components:
11781197
type: object
11791198
properties:
11801199
$field:
1181-
$ref: '#/components/schemas/modelStringPattern'
1200+
$ref: '#/components/schemas/FieldIdentifier'
11821201
$strVal:
11831202
$ref: '#/components/schemas/standardString'
11841203
$numVal:

‎documentation/IDTA-01002-3/modules/ROOT/images/plantuml/query-language-overview.puml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,7 @@ enum SelectField {
8686
}
8787

8888
enum FieldIdentifier {
89-
$strModel
89+
$field
9090
}
9191

9292
enum Value {

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Major Changes:
1616

1717
* New API operations and profiles for signing, including Asset Administration Shell Repository Service Specification - Signature Profile SSP-004, Submodel Repository Service Specification - Signature Profile SSP-003, and Concept Description Repository Service Specification - Signature Profile SSP-004 (https://github.com/admin-shell-io/aas-specs-api/issues/518[#518])
1818
* Add the asynchronous AASX File Server Service Specification (https://github.com/admin-shell-io/aas-specs-api/issues/347[#347])
19-
19+
* Added: Query Filter and FragmentFieldIdentifiers (https://github.com/admin-shell-io/aas-specs-api/issues/517)
2020

2121
Minor Changes:
2222

@@ -27,7 +27,6 @@ Minor Changes:
2727
* 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])
2828
* 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])
2929

30-
3130
=== Operation Changes w.r.t. V3.1.2 to V3.2
3231

3332
[%autowidth,width="100%",cols="40%,15%,45%",options="header",]

‎documentation/IDTA-01002-3/modules/ROOT/pages/http-rest-api/test/query/test1.json‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
11
{
22
"$schema": "../../query-json-schema.json",
33
"select": "id",
4-
"filter": {
5-
"$and":[
6-
{
4+
"$filters": [
5+
{
6+
"$fragment": "$sme#value",
7+
"$condition": {
78
"$eq": [
89
{
9-
"strModel": "$sm.semanticId.keys.value"
10+
"$field": "$sm#semanticId.keys[].value"
1011
},
1112
{
12-
"strVal": "https://example.org/value"
13+
"$strVal": "https://example.org/value"
1314
}
1415
]
15-
},
16-
{}
17-
]
18-
},
16+
}
17+
}
18+
],
1919
"option": {
2020
"sort": {
2121
"id": "asc"

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

Lines changed: 112 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -507,6 +507,113 @@ a|
507507
| Both $match conditions are fulfilled, even though for different SpecificAssetIds. Therefore the OR clause also evaluates to `true` for both items.
508508
|===
509509

510+
== Query Filter
511+
512+
The Query Language supports a `$filters` option that allows clients to reduce the amount of returned data. This can significantly improve response times, as the backend may scan and process fewer data elements. Furthermore, filtering is an important mechanism in the security domain, as it helps restrict access to sensitive information by preventing unnecessary exposure of internal data structures.
513+
514+
`$filters` expressions can be applied to specific metamodel elements of the AAS (e.g., `Submodel`, `Submodel Elements` contained within an `Submodel`, etc.). However, not all elements can be filtered arbitrarily. If a particular metamodel element is mandatory according to the AAS specification, filtering it out would result in invalid or incomplete data structures. Therefore, such filtering operations are prohibited to ensure consistency and correctness of the returned data.
515+
Since a valid Reference requires at least one key, filters that eliminate all keys remain valid but result in the removal of the entire Reference rather than just its keys.
516+
517+
If no `$filters` is specified for a particular metamodel element, that element remains unfiltered. Thus, applying additional filters can only reduce the amount of data returned; it can never increase the amount of data or introduce information that is not already present in the underlying AAS. If multiple filters are specified and apply to overlapping data, they are combined using logical AND semantics.
518+
519+
Filter example with boolean condition
520+
[.table-with-appendix-table]
521+
[width=100%, cols="40%,40%,20%"]
522+
|===
523+
h| Grammar h| JSON Schema h| Comment
524+
a|
525+
[source]
526+
----
527+
$sm#semanticId $eq
528+
"https://admin-shell.io/idta/nameplate/3/0/Nameplate"
529+
$filters
530+
$fragment $sme.AddressInformation.Zipcode
531+
$condition false
532+
----
533+
a|
534+
[source,json]
535+
----
536+
{
537+
"$condition": {
538+
"$eq": [
539+
{
540+
"$field": "$sm#semanticId"
541+
},
542+
{
543+
"$strVal": "https://admin-shell.io/idta/nameplate/3/0/Nameplate"
544+
}
545+
]
546+
},
547+
"$filters": [
548+
{
549+
"$fragment": "$sme.AddressInformation.Zipcode",
550+
"$condition": {
551+
"$boolean": false
552+
}
553+
}
554+
]
555+
}
556+
557+
----
558+
a| Selects Nameplate submodels and filters out `AddressInformation.Zipcode` data.
559+
a|
560+
[source]
561+
----
562+
$sm#semanticId $eq
563+
"https://admin-shell.io/idta/nameplate/3/0/Nameplate"
564+
$filters
565+
$fragment $sme#value
566+
$condition $sm#semanticId.keys[].value $eq "HIDE_VALUE"
567+
$fragment $sm#semanticId.keys[]
568+
$condition $sm#semanticId.keys[].value $eq "HIDE_VALUE"
569+
----
570+
a|
571+
[source,json]
572+
----
573+
{
574+
"$condition": {
575+
"$eq": [
576+
{
577+
"$field": "$sm#semanticId"
578+
},
579+
{
580+
"$strVal": "https://admin-shell.io/idta/nameplate/3/0/Nameplate"
581+
}
582+
]
583+
},
584+
"$filters": [
585+
{
586+
"$fragment": "$sme#value",
587+
"$condition": {
588+
"$eq": [
589+
{
590+
"$field": "$sm#semanticId.keys[].value"
591+
},
592+
{
593+
"$strVal": "HIDE_VALUE"
594+
}
595+
]
596+
}
597+
},
598+
{
599+
"$fragment": "$sm#semanticId.keys[]",
600+
"$condition": {
601+
"$eq": [
602+
{
603+
"$field": "$sm#semanticId.keys[].value"
604+
},
605+
{
606+
"$strVal": "HIDE_VALUE"
607+
}
608+
]
609+
}
610+
}
611+
]
612+
}
613+
614+
----
615+
a| Selects Nameplate submodels and filters out values from all nested submodel elements when the key "HIDE_VALUE" is present in the submodel’s semanticId. Additionally, any "HIDE_VALUE" keys in the submodel’s semanticId are removed from the result.
616+
|===
510617

511618
== Sorting and Pagination
512619

@@ -530,14 +637,15 @@ The table follows the structure of the JSON schema top to bottom.
530637
[width=100%, cols="25%,25%,50%"]
531638
|===
532639
h| JSON Schema h| Grammar h| Comment
533-
| modelStringPattern | <FieldIdentifier> | AAS model elements are strings which start with a $
640+
| FieldIdentifier | <FieldIdentifier> | AAS model elements are strings which start with a $
641+
| FragmentFieldIdentifier | <FieldIdentifierFragment> | AAS model fragments for query/security filtering
534642
| standardString | | All other value strings
535643
| hexLiteralPattern | <HexLiteral> |
536644
| dateTimeLiteralPattern | <DateTimeLiteral> |
537645
| timeLiteralPattern | <TimeLiteral> |
538646
| Value | <operand> | Comparisons eq, ne, gt, ge, lt, le; explicit properties for automatic code generation: strModel etc.
539647
| stringValue | <stringOperand> | String operations contains, starts-with, ends-with, regex; explicit properties for automatic code generation: strModel etc.
540-
| $field | - | string following the modelStringPattern
648+
| $field | - | string following the FieldIdentifier pattern
541649
| $strVal | - | string following the standardString
542650
| $attribute | - | explained in Security Access Rules; not used for query language
543651
| $numVal | <NumericalLiteral> | Number constant
@@ -564,7 +672,9 @@ h| JSON Schema h| Grammar h| Comment
564672
| rightsEnum | - | explained in Security Access Rules; not used for query language
565673
| AccessPermissionRule | - | explained in Security Access Rules; not used for query language
566674
| AllAccessPermissionRules | - | explained in Security Access Rules; not used for query language
675+
| QueryFilter | <QueryFilter> | A single filter block with $fragment and $condition
567676
| $condition | <logicalExpression> | Root object for the query condition expression
677+
| $filters | <QueryFilter>* | Optional list of filter blocks evaluated together
568678
| $select | <selectStatement> | Optional expresion to control the returned fields. Only 'id' is possible.
569679
|===
570680

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

Lines changed: 39 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
....
1+
....
22
{
33
"$schema": "http://json-schema.org/draft-07/schema#",
44
"title": "Common JSON Schema for AAS Queries and Access Rules",
@@ -8,9 +8,13 @@
88
"type": "string",
99
"pattern": "^(?!\\$).*"
1010
},
11-
"modelStringPattern": {
11+
"FieldIdentifier": {
12+
"type": "string",
13+
"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)))$"
14+
},
15+
"FragmentFieldIdentifier": {
1216
"type": "string",
13-
"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)))$"
17+
"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]*\\]))$"
1418
},
1519
"hexLiteralPattern": {
1620
"type": "string",
@@ -28,7 +32,7 @@
2832
"type": "object",
2933
"properties": {
3034
"$field": {
31-
"$ref": "#/definitions/modelStringPattern"
35+
"$ref": "#/definitions/FieldIdentifier"
3236
},
3337
"$strVal": {
3438
"$ref": "#/definitions/standardString"
@@ -180,7 +184,7 @@
180184
"type": "object",
181185
"properties": {
182186
"$field": {
183-
"$ref": "#/definitions/modelStringPattern"
187+
"$ref": "#/definitions/FieldIdentifier"
184188
},
185189
"$strVal": {
186190
"$ref": "#/definitions/standardString"
@@ -653,6 +657,12 @@
653657
"FILTER": {
654658
"$ref": "#/definitions/SecurityQueryFilter",
655659
"additionalProperties": false
660+
},
661+
"FILTERLIST": {
662+
"type": "array",
663+
"items": {
664+
"$ref": "#/definitions/SecurityQueryFilter"
665+
}
656666
}
657667
},
658668
"allOf": [
@@ -705,7 +715,7 @@
705715
"type": "object",
706716
"properties": {
707717
"FRAGMENT": {
708-
"type": "string"
718+
"$ref": "#/definitions/FragmentFieldIdentifier"
709719
},
710720
"CONDITION": {
711721
"$ref": "#/definitions/logicalExpression"
@@ -730,10 +740,23 @@
730740
}
731741
],
732742
"additionalProperties": false
733-
}
734-
},
735-
"type": "object",
736-
"properties": {
743+
},
744+
"QueryFilter": {
745+
"type": "object",
746+
"properties": {
747+
"$fragment": {
748+
"$ref": "#/definitions/FragmentFieldIdentifier"
749+
},
750+
"$condition": {
751+
"$ref": "#/definitions/logicalExpression"
752+
}
753+
},
754+
"required": [
755+
"$fragment",
756+
"$condition"
757+
],
758+
"additionalProperties": false
759+
},
737760
"Query": {
738761
"type": "object",
739762
"properties": {
@@ -743,6 +766,12 @@
743766
},
744767
"$condition": {
745768
"$ref": "#/definitions/logicalExpression"
769+
},
770+
"$filters": {
771+
"type": "array",
772+
"items": {
773+
"$ref": "#/definitions/QueryFilter"
774+
}
746775
}
747776
},
748777
"required": [

0 commit comments

Comments
 (0)