Skip to content

fix: add op-specific example scaffolds for catalog get_product#616

Merged
carolinerg1 merged 2 commits into
Universal-Commerce-Protocol:mainfrom
sakinaroufid:fix/catalog-get-product-scaffolds
Jul 22, 2026
Merged

fix: add op-specific example scaffolds for catalog get_product#616
carolinerg1 merged 2 commits into
Universal-Commerce-Protocol:mainfrom
sakinaroufid:fix/catalog-get-product-scaffolds

Conversation

@sakinaroufid

@sakinaroufid sakinaroufid commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Description

The doc example validator merges each example into a scaffold before validating it. Scaffolds are looked up by schema + direction + op, with a fallback to a direction-only file. get_product never got its own scaffolds, so its examples fall back to the lookup ones. That's the wrong shape: lookup uses ids and products arrays, get_product uses a single id and a single product.

Result: every get_product example in the catalog docs is validated with a stray ids or products field merged in. It only passes because the schemas allow unknown properties. The examples aren't being checked as the shape they document, and if we ever tighten additionalProperties on these defs, all get_product examples break over fields nobody wrote.

#516 migrated the annotations to op=search|lookup|get_product but didn't add fixtures for the new op. This adds them:

  • shopping_catalog_lookup_request_get_product.json: minimal seed with id.
  • shopping_catalog_lookup_response_get_product.json: valid seed with ucp and a full product, same style as the checkout response scaffold.
  • tests in test_validate_examples.py: op-specific scaffolds win over the fallback, both fixtures have the right shape, and a fully elided get_product example validates from the response fixture alone.

No schema, doc, or SDK changes.

Category (Required)

Please select one or more categories that apply to this change.

  • Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
  • Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
  • Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
  • Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
  • Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
  • Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
  • SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
  • Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
  • UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
  • Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Related Issues

None.

Checklist

  • I have followed the Contributing Guide (including Conventional Commits title requirements and ! for breaking changes).
  • I have updated the documentation (if applicable).
  • My changes pass all local linting and formatting checks.
  • I have added tests that prove my fix is effective or that my feature works.
  • New and existing unit tests pass locally with my changes.
  • (For Core/Capability) I have included/updated the relevant JSON schemas.
  • I have regenerated Python Pydantic models by running generate_models.sh under python_sdk.

Unchecked items don't apply here (no doc, schema, or SDK changes).

Screenshots / Logs (if applicable)

$ python3 scripts/test_validate_examples.py
48 passed, 0 failed

$ python3 scripts/validate_examples.py --schema-base source/schemas --scaffolds scripts/scaffolds --docs docs/specification
274 passed, 0 failed, 0 errors, 31 skipped

@sakinaroufid
fix: add op-specific example scaffolds for catalog get_product
cfbc738 
The example validator resolves scaffolds by schema+direction+op with a
direction-only fallback. get_product shares catalog_lookup.json with
the lookup op but has a different payload shape (id/product vs
ids/products), and never got op-specific fixtures. Every get_product
example in the catalog docs therefore fell back to the lookup
scaffolds and was deep-merged with lookup boilerplate before
validation: requests validated carrying a stray ids array next to id,
responses a stray products array next to product. This passes only
because the schemas tolerate unknown properties; the examples were
never validated as the payload shape they document, and any future
tightening (additionalProperties/unevaluatedProperties) would fail
every get_product example against data no author wrote.

Add shopping_catalog_lookup_request_get_product.json and
shopping_catalog_lookup_response_get_product.json so get_product
examples merge into their own shape, and regression tests covering
op-specific scaffold precedence, the repo fixtures' shapes, and an
end-to-end fully-elided get_product example that shows the response
fixture is a valid payload seed.

Verified: scripts/test_validate_examples.py 48 passed, 0 failed; full
corpus validation 274 passed, 0 failed, 0 errors, 31 skipped.
@damaz91 damaz91 added the status:needs-triage Signal that the PR is ready for human triage label Jul 20, 2026
@carolinerg1 carolinerg1 added documentation Improvements or additions to documentation and removed status:needs-triage Signal that the PR is ready for human triage labels Jul 21, 2026
@carolinerg1

carolinerg1 commented Jul 21, 2026

Copy link
Copy Markdown

LGTM! Thanks for catching and addressing this, @sakinaroufid!

Review & Verification Summary

  • Accurate Scaffolding: Verified that shopping_catalog_lookup_request_get_product.json and shopping_catalog_lookup_response_get_product.json properly supply the singular id and product payload seeds for get_product, eliminating the unintended fallback merge with lookup's batch arrays (ids / products).
  • Regression Coverage: The new test_scaffold_resolution() test suite in scripts/test_validate_examples.py provides clean verification of op-specific scaffold precedence, fixture payload shapes, and end-to-end elided example validation.
  • Local Verification:
    • python3 scripts/test_validate_examples.py passed cleanly (48 passed, 0 failed).
    • python3 scripts/validate_examples.py --schema-base source/schemas --scaffolds scripts/scaffolds --docs docs/specification passed without errors (274 passed, 0 failed, 0 errors, 31 skipped).
  • CI & Compliance: All automated checks, Google CLA (cla/google), and Conventional Commits title formatting are passing.

@damaz91 damaz91 added devops status:under-review and removed documentation Improvements or additions to documentation labels Jul 22, 2026
@sakinaroufid

sakinaroufid commented Jul 22, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Thanks for the review @carolinerg1 @damaz91 - does this look good to merge now, or needs TC review?

@carolinerg1
carolinerg1 merged commit f29c3cb into Universal-Commerce-Protocol:main Jul 22, 2026
20 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@carolinerg1 carolinerg1 carolinerg1 approved these changes
@damaz91 damaz91 damaz91 approved these changes
@jingyli jingyli Awaiting requested review from jingyli
@DanielFalconGuedes DanielFalconGuedes Awaiting requested review from DanielFalconGuedes

Assignees

No one assigned

Labels

devops status:under-review

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@sakinaroufid @carolinerg1 @damaz91