Skip to content

fix(policies): require non-empty applies_to and fix the set-match example and coverage wording - #661

Open
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/policies-applies-to-and-prose
Open

fix(policies): require non-empty applies_to and fix the set-match example and coverage wording#661
vishkaty wants to merge 1 commit into
Universal-Commerce-Protocol:mainfrom
vishkaty:fix/policies-applies-to-and-prose

Conversation

@vishkaty

Copy link
Copy Markdown
Contributor

Problem

Three small policies[] corrections found while reading the merged policies capability:

  1. applies_to: [] is undefined. An empty array is schema-valid (no minItems on policy.json) but matches none of the three defined targeting forms (singular, set, omitted). Response-wide scope is expressed by omitting applies_to, so an empty array has no defined meaning.
  2. The Set-match example matches nothing. overview.md filters on $.products[?@.category=='electronics'], but the product schema defines categories (array of category objects) and tags (array of strings), not category, so the canonical example selects the empty set against a schema-conformant product.
  3. The coverage definition is circular. "the matched node's Normalized Path is a prefix of the target node's" is self-referential (the target matches a set, not a single node); it is the covered node whose path is prefixed.

Fix

  • policy.json: add minItems: 1 to applies_to (omit the field for response-wide scope).
  • overview.md: change the example filter to $.products[?@.tags[?@=='electronics']], a field products actually carry.
  • overview.md: reword the coverage sentence to "a prefix of that node's Normalized Path".

Verification

No example in docs/ or source/ uses "applies_to": [], so minItems: 1 breaks nothing (confirmed by grep and a full validate_examples.py run: 282 passing, unchanged). ucp-schema lint source/ passes. The new JSONPath is valid RFC 9535.

…mple and coverage wording

Three small policies[] corrections:

- policy.json: add `minItems: 1` to `applies_to`. An empty array was
  schema-valid but matched none of the three defined targeting forms (singular,
  set, omitted), leaving covers-nothing versus response-wide undefined.
  Response-wide scope is expressed by omitting `applies_to`.
- overview.md: the canonical Set-match example filtered on `@.category`, a
  field the product schema does not define (it defines `categories` and
  `tags`), so the example selected the empty set against schema-conformant
  products. Use `@.tags[?@=='electronics']`, a field products actually carry.
- overview.md: the coverage definition read "a prefix of the target node's",
  which is circular (the target matches a set, not a single node). It is the
  covered node whose path the matched node's path prefixes; reword to "a prefix
  of that node's Normalized Path".
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Jul 31, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status:needs-triage Signal that the PR is ready for human triage

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants