fix: Transition cart.id to be omitted in update requests instead of a required field

[jingyli]

Description

Transition id field from required to omit in cart capability for update requests.

The current state presents a redundancy given the cart being updated is already identified at the transport level (e.g., via the resource path in REST /carts/{cart_id} or via tool arguments in MCP) - this is also the pattern used in checkout capability.

Also augmented logic in main.py to properly process schema with transition annotations so the rendering of the field requirement in reference.md clarifies the transition (and all ucp_request/ucp_response annotations properly). See attached screenshot for an example of how it will look like post this change.

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

N/A

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.

Screenshots / Logs (if applicable)

[raginpirate]

Good spot @jingyli, I am aligned with fixing this id advertisement and the main.py bug.

However, the immediate removal of id from all scaffolds looks wrong, as from is supposed to be the authoritative definition in the schema until a future cutoff is hit. The established sequence is #145 announce (keep the field, comment it) → #341 flip at version cut → #332 drop from docs. Unless we come up with a safe way to condense versioning, I think this blocks the PR from shipping as-is.

[igrigorik]

Agree with @raginpirate, the end state is right but the sequence is wrong. The examples must resolves against the production schema shape, not future state. Let's break this apart and follow same sequence we landed for checkout: land the transition first, then stage transition removal and concrete 'omit' with updated examples.

[jingyli]

@raginpirate @igrigorik Good prompt and callout.

Originally I was thinking whether the established sequence had areas for improvement (i.e. changing fields in docs #332 probably should have came before the version cut finalization #341 ) so draft ucp.dev always have the right documentation accompanying on the schema. But it should be done in another PR - though I do think we should do the documentation/scaffolding update in the same PR where we finalize the transition so both takes effect into the version cut. Will take a stab at it when closer to the version cut.

For now, reverted back the changes on scaffolding/documentation updates and attached a screenshot on how the main.py rendering will look like on reference.md.

[raginpirate]

@jingyli did you want to keep deprecation markers in the docs for this interim period?

P.S. While writing this I realized we never removed the deprecated IDs with #341! Opened a doc fix: #646

I wonder if theres some simple tooling that can help us catch deprecated fields in examples and ensure they match the existing transition states.

[igrigorik]

I wonder if theres some simple tooling that can help us catch deprecated fields in examples and ensure they match the existing transition states.

our schema validator with --strict flag would/should have caught this.

[jingyli]

@raginpirate PTAL at 7869d54!

Although just a side note from me personally: I feel the need to add deprecation markers to be a little bit unnatural given json doesn't allow for inline comments structurally. I guess it's fine since these are just doc examples and it's better for readability (but still feel a little bit odd given these are technically json code blocks we have in our markdown files).

[raginpirate]

🚀 Agreed, these are example payloads rather than schemas, and there's no clean way in base JSON to show this inline, so I'm personally happy with the // convention here.