Skip to content

docs: add discovery rules and agent checkout flow#18

Closed
omsaisudarshan108 wants to merge 1 commit intoUniversal-Commerce-Protocol:mainfrom
omsaisudarshan108:feat/discovery-sdk-agent-flow
Closed

docs: add discovery rules and agent checkout flow#18
omsaisudarshan108 wants to merge 1 commit intoUniversal-Commerce-Protocol:mainfrom
omsaisudarshan108:feat/discovery-sdk-agent-flow

Conversation

@omsaisudarshan108
Copy link
Copy Markdown

@omsaisudarshan108 omsaisudarshan108 commented Jan 12, 2026

Summary

  • Expand the discovery profile example in docs/specification/overview.md with Cart, Loyalty, and Post-Order capabilities.
  • Add profile validation rules to clarify required fields and constraints.
  • Add an agent checkout reference flow (sequence diagram + minimal payloads) in docs/specification/checkout-rest.md.
  • Add scripts/regenerate_artifacts.sh and document it in CONTRIBUTING.md.

Testing

  • Not run (docs/script change)

@omsaisudarshan108 omsaisudarshan108 requested a review from a team January 12, 2026 08:41
@jingyli
Copy link
Copy Markdown
Contributor

jingyli commented Jan 13, 2026

Thank you for your contribution to the Universal Commerce Protocol!

While we appreciate your enthusiasm for UCP, this PR currently seems to be bundling a few things together. To break it down:

  1. Expanding discovery profile example to include additional capabilities/extensions: Given some of the added capabilities/extensions are not UCP-governed constructs, we will decline this part of the change per reasons given in Feat/cart loyalty post order #17. We welcome you to define your own capabilities & extensions, host them on your own domain, and reference them in the profile as long as they follow UCP's governance model.

  2. Documentation updates on minimal payload & sequence diagram & new command definition: We will be evaluating the changes and will provide a formal response within 1-2 weeks, but we encourage you to clean up this PR's scope to be specific to those changes to help with our review process.

@omsaisudarshan108 @claude
docs: add discovery validation rules and agent checkout flow
d5f29e6 
This PR focuses on documentation improvements:

1. Profile Validation Rules: Adds clear validation requirements for
   discovery profiles including version format, service requirements,
   endpoint format, and capability reference constraints.

2. Agent Checkout Reference Flow: Documents the canonical REST
   checkout sequence with a Mermaid diagram and minimal payload examples
   showing the create → update → complete flow.

3. Developer Tooling: Adds regenerate_artifacts.sh script to simplify
   the workflow for regenerating schemas and SDK models in one command.

The discovery profile example now only includes UCP-governed capabilities
(checkout, fulfillment, discount) following governance guidelines.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@omsaisudarshan108 omsaisudarshan108 force-pushed the feat/discovery-sdk-agent-flow branch from b397704 to d5f29e6 Compare January 17, 2026 15:00
@omsaisudarshan108
Copy link
Copy Markdown
Author

omsaisudarshan108 commented Jan 17, 2026

PR Update - Addressed Maintainer Feedback
Thank you @jingyli for the detailed feedback! I've updated this PR to focus specifically on the documentation improvements as requested.

Changes Made
✅ Removed: Non-UCP-governed capabilities from discovery profile example

Removed dev.ucp.shopping.cart
Removed dev.ucp.shopping.loyalty
Removed dev.ucp.shopping.post_order
The business profile example now only includes UCP-governed capabilities (checkout, fulfillment, discount) following the governance model.

✅ Kept: Documentation improvements

Profile Validation Rules (lines 359-370 in overview.md)

Clear validation requirements for discovery profiles
Version format, service requirements, endpoint constraints
Capability reference validation rules
Agent Checkout Reference Flow (checkout-rest.md)

Mermaid sequence diagram showing canonical REST flow
Minimal payload examples for create and complete operations
Demonstrates the create → update → complete pattern
Developer Tooling

New scripts/regenerate_artifacts.sh convenience script
Updated CONTRIBUTING.md with usage instructions
Summary
The PR scope is now clean and focused on documentation enhancements. All changes follow UCP governance guidelines and are ready for your evaluation.

@nearlyforget nearlyforget requested a review from jingyli February 18, 2026 19:45
@nearlyforget nearlyforget requested a review from a team February 27, 2026 23:41
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 17, 2026
@alexpark20 @claude
feat: add audit findings Universal-Commerce-Protocol#16–21 to spec diff
a563545 
Add 6 missed post-release changes discovered during full audit of 58 PRs
merged after the 2026-01-23 branch was cut:

  Universal-Commerce-Protocol#16 — Optional request/response signing headers (PR Universal-Commerce-Protocol#156) [Additive]
  Universal-Commerce-Protocol#17 — Eligibility claims & provisional discounts (PR Universal-Commerce-Protocol#250) [High/Breaking]
  Universal-Commerce-Protocol#18 — Optional signals field on cart and checkout (PR Universal-Commerce-Protocol#203) [Additive]
  Universal-Commerce-Protocol#19 — Fulfillment method id/type optional on update (PR Universal-Commerce-Protocol#143/Universal-Commerce-Protocol#196) [Low]
  Universal-Commerce-Protocol#20 — intent field added to context (PR Universal-Commerce-Protocol#95) [Additive]
  Universal-Commerce-Protocol#21 — available_instruments added to payment handler (PR Universal-Commerce-Protocol#187) [Additive]

Also updates PR_URLS map and changes/visible counts from 15 → 21.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 17, 2026
@alexpark20 @claude
feat: add audit findings Universal-Commerce-Protocol#16–21 to spec diff
d1cefca 
Add 6 missed post-release changes discovered during full audit of 58 PRs
merged after the 2026-01-23 branch was cut:

  Universal-Commerce-Protocol#16 — Optional request/response signing headers (PR Universal-Commerce-Protocol#156) [Additive]
  Universal-Commerce-Protocol#17 — Eligibility claims & provisional discounts (PR Universal-Commerce-Protocol#250) [High/Breaking]
  Universal-Commerce-Protocol#18 — Optional signals field on cart and checkout (PR Universal-Commerce-Protocol#203) [Additive]
  Universal-Commerce-Protocol#19 — Fulfillment method id/type optional on update (PR Universal-Commerce-Protocol#143/Universal-Commerce-Protocol#196) [Low]
  Universal-Commerce-Protocol#20 — intent field added to context (PR Universal-Commerce-Protocol#95) [Additive]
  Universal-Commerce-Protocol#21 — available_instruments added to payment handler (PR Universal-Commerce-Protocol#187) [Additive]

Also updates PR_URLS map and changes/visible counts from 15 → 21.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 18, 2026
@alexpark20 @claude
docs: remove cart-specific entry, mark Universal-Commerce-Protocol#17 …
65c4a1b 
…and Universal-Commerce-Protocol#18 as not implemented

Cart capability was not part of the 2026-01-23 spec (introduced 2026-01-26),
so cart-to-checkout (Universal-Commerce-Protocol#13) is new capability work, not a migration concern.

Eligibility claims (Universal-Commerce-Protocol#17) and signals (Universal-Commerce-Protocol#18) are not yet implemented in Shopify.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 18, 2026
@alexpark20 @claude
docs: remove cart-specific entry, mark Universal-Commerce-Protocol#17 …
b6cc8cc 
…and Universal-Commerce-Protocol#18 as not implemented

Cart capability was not part of the 2026-01-23 spec (introduced 2026-01-26),
so cart-to-checkout (Universal-Commerce-Protocol#13) is new capability work, not a migration concern.

Eligibility claims (Universal-Commerce-Protocol#17) and signals (Universal-Commerce-Protocol#18) are not yet implemented in Shopify.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 19, 2026
@alexpark20
feat: comprehensive change list audit — add changes Universal-Commerc…
d5bc905 
…e-Protocol#23-Universal-Commerce-Protocol#26, fix Universal-Commerce-Protocol#3/Universal-Commerce-Protocol#14/Universal-Commerce-Protocol#18
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 19, 2026
@alexpark20
feat: comprehensive change list audit — add changes Universal-Commerc…
4bc3ad9 
…e-Protocol#23-Universal-Commerce-Protocol#26, fix Universal-Commerce-Protocol#3/Universal-Commerce-Protocol#14/Universal-Commerce-Protocol#18
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 19, 2026
@alexpark20
feat: comprehensive change list audit — add changes Universal-Commerc…
0daca95 
…e-Protocol#23-Universal-Commerce-Protocol#26, fix Universal-Commerce-Protocol#3/Universal-Commerce-Protocol#14/Universal-Commerce-Protocol#18
alexpark20 added a commit to alexpark20/ucp that referenced this pull request Mar 19, 2026
@alexpark20
feat: comprehensive change list audit — add changes Universal-Commerc…
9348936 
…e-Protocol#23-Universal-Commerce-Protocol#26, fix Universal-Commerce-Protocol#3/Universal-Commerce-Protocol#14/Universal-Commerce-Protocol#18
@damaz91
Copy link
Copy Markdown
Contributor

damaz91 commented Apr 17, 2026

The changes and feedback from this PR was addressed in newest iterations of the documentation. Closing this.

@damaz91 damaz91 closed this Apr 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jingyli jingyli Awaiting requested review from jingyli

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@omsaisudarshan108 @jingyli @damaz91