feat: extension "Product addons"

[sdedeo2025]

Description

Adds the Product Addons extension (dev.ucp.shopping.product_addons), enabling shoppers to select and change product addons (e.g., Warranty, Engraving, Gift Wrapping) directly within cart and checkout sessions.

Addons are optional purchasable extras associated with a product — unlike variant-defining options (Size, Color) which are handled at the catalog level, addons represent supplementary choices that affect pricing without changing the base
product variant. Without this extension, businesses must either inflate their product catalogs with pre-built variants for every addon permutation, or handle addon selection entirely outside the checkout flow.

How it works:

• The platform sends item.id as a product identifier — optionally with selected addons, or with no addons to receive server defaults.
• The business responds with all available addon choices, each with its own id, title, default flag, and totals representing the cost of that specific addon choice.
• To change an addon, the platform sends an update with a new selected_choice_id. The business recalculates pricing and returns updated totals.

Design decisions:

• Modeled as a UCP extension (not a core schema change), following the same $defs + allOf composition pattern as discount.json and fulfillment.json.
• Selection pattern mirrors fulfillment groups: selected_choice_id (bidirectional) + choices[] (response-only).
• Each addon choice is a standalone type (addon_choice) with id, title, image_url, default, and totals — not derived from item.json, since addon choices are conceptually different from line item products.
• selected_choice_id is optional on create (server picks defaults based on default flag), optional on update.
• Backwards compatible — items without addons continue to work as standard line items.

Files:

• source/schemas/shopping/product_addons.json — Extension schema with addon_choice, item_addon, extended item, line_item, and $defs for dev.ucp.shopping.checkout / dev.ucp.shopping.cart
• docs/specification/product-addons.md — Extension documentation with discovery, schema definitions, and examples (product ID only with server defaults, selected addons, upgrade warranty, mixed items with and without addons)
• mkdocs.yml — Nav entries for the new doc

Category (Required)

• 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.
• I have updated the documentation (if applicable).
• My changes pass all local linting and formatting checks.
• (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.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.