docs(query-language): add normative Query Evaluation Semantics#585
Open
aorzelskiGH wants to merge 1 commit intoIDTA-01002-3-2_workingfrom
Open
docs(query-language): add normative Query Evaluation Semantics#585aorzelskiGH wants to merge 1 commit intoIDTA-01002-3-2_workingfrom
aorzelskiGH wants to merge 1 commit intoIDTA-01002-3-2_workingfrom
Conversation
Specify how AAS queries MUST be evaluated, covering: - parse and schema validation (400 / 422 mapping), - behaviour of FieldIdentifiers that do not resolve on the target (candidate excluded, no error), - behaviour under profile restrictions (non-applicable prefix is treated like "field not present"), - semantics of list-valued FieldIdentifiers (existential match), - behaviour on casting errors (candidate excluded, query stays green), - interaction with Access Rules (IDTA-01004): applicable ALLOW rules filter the candidate set; "not applicable" rules do not fail the query. Refs: Review Finding T-15 Made-with: Cursor
aorzelskiGH
requested review from
BirgitBoss,
alexgordtop,
danielporta,
g1zzm0,
mjacoby,
sebbader-sap,
waltersve and
zrgt
as code owners
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
| === Evaluation of FieldIdentifiers | ||
|
|
||
| * A FieldIdentifier that does not resolve to any value on a candidate object (because the field does not exist on that target) produces *no comparison match*: the candidate is excluded from the result set. This MUST NOT raise an error. | ||
| * A FieldIdentifier that is not applicable for the active profile (see xref:http-rest-api/service-specifications-and-profiles.adoc#fieldidentifier-applicability[FieldIdentifier Applicability per Profile]) is treated like "field does not exist": the candidate is excluded, no error is raised. |
| === Casting Errors | ||
|
|
||
| * An explicit cast that fails on the current candidate (e.g. `num("abc")`) MUST exclude the candidate from the result set; it MUST NOT fail the whole query. | ||
| * Implicit casts between the types listed in clause xref:_casting[] follow the same rule. |
|
|
||
| === Combination with Access Rules | ||
|
|
||
| When a query is evaluated by a service that also enforces Access Rules (see IDTA-01004), the query's candidate set MUST be filtered through the applicable access rules before being returned. Access rules that evaluate to `not applicable` for a candidate (e.g. because a referenced FieldIdentifier does not exist in the current profile) MUST NOT cause the query to fail; such rules simply do not contribute an ALLOW for the candidate. |
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
2 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 "Query Evaluation Semantics" clause to
query-language.adocso that parse, field resolution, casting, list handling and interaction with Access Rules (IDTA-01004) behave deterministically across implementations.Problem
The query language currently leaves several runtime questions implicit:
Implementations disagree (some 500, some 200/empty, some 400), which blocks interoperability and conformance testing.
Solution
Introduce a new section
Query Evaluation Semantics (normative)just before the JSON Schema clause. It specifies:400 Bad Request; unsupported combinations =>422 Unprocessable Entity;Affected files
documentation/IDTA-01002-3/modules/ROOT/pages/query-language.adocReview notes
admin-shell-io/aas-specs-security#...adds the equivalentEvaluation Semanticssection for the Access Rule Model and mirrors the error-handling conventions.Refs: Review Finding T-15