Skip to content

fix(examples): correct broken BNF and JSON example files#73

Open
aorzelskiGH wants to merge 1 commit into
IDTA-01004-3-1_Workingfrom
fix/broken-examples
Open

fix(examples): correct broken BNF and JSON example files#73
aorzelskiGH wants to merge 1 commit into
IDTA-01004-3-1_Workingfrom
fix/broken-examples

Conversation

@aorzelskiGH
Copy link
Copy Markdown
Contributor

Summary

Fixes concrete bugs in the BNF and JSON example files under
documentation/IDTA-01004/modules/ROOT/partials/examples/. Wider
CI-side example validation is intentionally deferred to the
conformance-tests PR (T-16).

Problem

Several examples were broken in ways that prevent them from being
used as normative illustrations:

  • filter.bnf, filter.json: DESCRIPTOR $aasDesc("*") — the
    grammar token is $aasdesc. Case-sensitive parsers reject this.
  • filter.bnf: FILTER: FRAGMENT "$aasdesc#specificAssetIds[]"
    used the old route-literal form. The current
    <SecurityQueryFilter> requires
    FRAGMENT: <FieldIdentifierFragment>.
  • allow-read-list-semanticids-machinestate.json: FORMULA was
    not a logicalExpression at all; it contained a stray
    "REFERENCE" object with a dangling string, not even well-formed
    JSON of a formula value.
  • reuse-acl-object-formula.json: the first REFERABLE had an
    unbalanced escape sequence "$sme("\https://s1.com\").p1".
  • allow-create-only-specific.json: $eq compared
    {"CLAIM": "Role"} directly (an attribute descriptor) instead of
    wrapping it in {"$attribute": {"CLAIM": "Role"}}.
  • allow-read-all-users-of-company-for-submodel.bnf,
    allow-read-submodels-id-pattern.bnf: CLAIM("…") was at the
    same indentation as RIGHTS, so the attribute was visually not
    scoped under ATTRIBUTES:.

Solution

Targeted fixes only, keeping the examples' original intent:

  • Lowercase $aasdesc throughout filter.*.
  • Rewrite the FILTER fragment clause to the field-identifier form.
  • Rewrite allow-read-list-semanticids-machinestate.json FORMULA
    to mirror its .bnf twin: $eq of the REFERENCE $attribute and
    a $strVal "not-running".
  • Correct the escape sequence in reuse-acl-object-formula.json.
  • Wrap CLAIM in $attribute in allow-create-only-specific.json.
  • Re-indent CLAIM("…") under ATTRIBUTES: in the two BNF files.

All 11 JSON examples under partials/examples/ now parse as valid
JSON.

Impact

  • Affected spec: IDTA-01004 (aas-specs-security)
  • Consumers copying these snippets get working grammar and schema
    inputs.
  • No structural changes to the schemas or grammar.

Review notes

  • Please sanity-check that the intent of
    allow-read-list-semanticids-machinestate.json (allow EXECUTE
    only when machineState is "not-running") is what the original
    authors wanted — the previous content was unreconstructable; this
    interpretation follows the sibling .bnf file.
  • The filter.* FRAGMENT rewrite depends on the canonical
    SecurityQueryFilter form from the Security BNF; it is orthogonal
    to the API-side harmonization in the parallel API PR.

Related

Review Finding T-12: Broken example files.
Complements: T-02 (aas-specs-api PR #579) for the canonical
SecurityQueryFilter shape.

Several example files in partials/examples shipped broken content
that a reader or test harness would either reject or silently
misinterpret. This change fixes the concrete bugs; wider CI-side
example validation is added by a follow-up PR (T-16).

filter.bnf / filter.json
  - DESCRIPTOR used $aasDesc; grammar defines $aasdesc. Corrected.
  - FRAGMENT syntax inside FILTER used the old route-literal form
    (FRAGMENT "..."). Corrected to FRAGMENT: <FieldIdentifierFragment>
    to match <SecurityQueryFilter>.

allow-read-list-semanticids-machinestate.json
  - FORMULA was not a logicalExpression: it contained a stray
    "REFERENCE" object with a bare string token, not even valid JSON
    of a formula. Rewritten to match the .bnf counterpart:
      REFERENCE(...) $eq "not-running"
    -> $eq of $attribute/REFERENCE and $strVal.

reuse-acl-object-formula.json
  - First REFERABLE had an unbalanced backslash/quote sequence
    ('$sme("\https://s1.com\").p1'). Replaced by the correctly
    escaped form used in its sibling entry.

allow-create-only-specific.json
  - $eq compared {"CLAIM": "Role"} (an attribute descriptor, not a
    Value object). Wrapped it in {"$attribute": {"CLAIM": "Role"}}
    to match the BNF form CLAIM("Role") $eq "...".

allow-read-all-users-of-company-for-submodel.bnf
allow-read-submodels-id-pattern.bnf
  - ATTRIBUTES child was at the same indentation as RIGHTS, making
    the examples visually ambiguous. Indented under ATTRIBUTES:.

Refs: Review Finding T-12
Made-with: Cursor
Copy link
Copy Markdown
Collaborator

@Martin187187 Martin187187 left a comment

Choose a reason for hiding this comment

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

good findings

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants