Skip to content

fix(schemas): spell three experimental 3.3 values as their counterparts do - #8989

Open
KonstantinMirin wants to merge 3 commits into
adcontextprotocol:mainfrom
KonstantinMirin:schemas/experimental-token-spellings
Open

KonstantinMirin wants to merge 3 commits into
adcontextprotocol:mainfrom
KonstantinMirin:schemas/experimental-token-spellings

Conversation

@KonstantinMirin

Copy link
Copy Markdown
Collaborator

Part of #8901.

Three of the five tokens spelled two ways can take one spelling before the 3.3 RC. In each, the side that changes is experimental, added in 3.3 and only in the 3.3 betas, so no stable release is touched. This PR renames them in place, as offered in this comment. The other two (protocol names and nonlinear) have two stable sides and wait for 4.0.

Enum Was Now Matches In the betas
enums/execution-readiness-status.json (media_buy.execution_readiness) input_required input-required enums/task-status.json, which follows A2A's task states beta.1 to beta.5
enums/creative-change-kind.json (creative.live_updates) click_through clickthrough enums/url-asset-type.json, the url_type the change kind names beta.3 to beta.5
enums/delivery-projection-end-state.json (media_buy.delivery_projection) underdelivery under_delivery enums/offer-reason.json beta.0 to beta.5

All three enum files carry x-status: experimental and x-added-in: 3.3.0, and none exists on 3.2.x or in any 3.2 or earlier bundle under dist/schemas/.

What changes

  • Schemas: the three enums (values and enumDescriptions keys), the readiness descriptions in core/execution-requirement-readiness.json and core/product-execution-readiness.json, the end-state description in core/delivery-projection.json, and the three index.json descriptions.
  • Docs: the readiness table and rollup rules in the media-buy specification, list_products, the delivery projection example and tables in get_media_buy_delivery, the change-kind table and the assignment note in sync_creatives, and live_updates in get_adcp_capabilities. The experimental status page says on each row that the betas spelled the value the old way.
  • DR-0029 lists the end states, so it now says under_delivery, with an amendment note that the record was written with the beta spelling.
  • Training agent: the live-update change classifier and its declared in_place kinds use clickthrough. The hosted 3.3-beta.5 preview validates responses against the beta.5 bundle, which has only click_through. So a caller pinned to it still gets click_through in live_updates.in_place, staged_update.change_kinds and the CREATIVE_LIVE_UPDATE_UNSUPPORTED details, and served-release-shape.test.ts grades that. Execution readiness and delivery projections have no training-agent code.
  • Tests: tests/execution-readiness.test.cjs, tests/creative-live-updates.test.cjs, tests/delivery-projection.test.cjs and server/tests/unit/live-creative-updates.test.ts.
  • Changeset: .changeset/experimental-token-spellings.md. The consumed changesets for the three features stay in .changeset/pre/ as history.

No storyboard uses any of the three values.

Renamed in place

These are experimental, so there's no deprecation and no alias. lint-additive-minor skips experimental schemas and compares against 3.2.10, which has none of the three files, so it passes with no new baseline entry.

The experimental contract asks for 6 weeks' notice before a breaking change. These values are in no stable release, only in the betas, so this is the same kind of beta-to-beta change as #8758 and #8767 (#8501).

3.3 release pages

Three lines on the 3.3 release pages gave the old spellings. This PR changes them:

  • docs/reference/whats-new-in-3-3.mdx, the execution readiness bullet: input-required
  • docs/reference/migration/3-2-to-3-3.mdx, the execution readiness bullet: input-required
  • docs/reference/migration/3-2-to-3-3.mdx, the live creative updates paragraph: clickthrough

#8883 rewrites these pages for rc.0. Whichever lands second keeps the new spellings.

Not changed

Other uses of the same spellings name other things:

  • input_required in the MCP guide is MCP's own task state. The orchestrator-design example and the MCP task-store migration use it for task state too.
  • underdelivery as an ordinary word in descriptions and docs prose, such as bidding-policy.json.
  • asset_role: 'click_through' and requirements.url_type in server/src/shared/formats.ts are format slot labels, not change kinds.

For adopters

A seller or buyer built from a 3.3 beta bundle switches to the new spellings in readiness_status and the product rollup, creative.live_updates.in_place[].change, staged_update.change_kinds[], the CREATIVE_LIVE_UPDATE_UNSUPPORTED details, and projection.projected_end_state. The experimental status page lists one production adopter of delivery projections, and it would need to send under_delivery.

Checks

Run locally on origin/main a2a7d20fff. All of these pass:

  • build:schemas and build-compliance
  • test:schemas
  • test:additive-minor
  • every test:storyboard-* lint, and test:doc-compliance-drift
  • the four changed tests, and the tests that read the touched docs
  • the pre-commit commands (check-image-quality, npm run precommit: unit tests, server unit tests, typecheck)

On the training agent's sales tenant, served as the 3.3 candidate against the rebuilt schemas, creative_live_updates and creative_live_update_refusal pass 25 of 25 steps. execution_readiness is skipped, because the training agent doesn't declare media_buy.execution_readiness.

…ts do

Three tokens are spelled two ways for one concept, and in each the side
that changes is experimental, added in 3.3 and only in the 3.3 betas, so
it is renamed in place before the RC with no stable release touched.

- execution-readiness-status: input_required becomes input-required, the
  task-status spelling, which follows A2A's task states.
- creative-change-kind: click_through becomes clickthrough, the url_type
  value the change kind names.
- delivery-projection-end-state: underdelivery becomes under_delivery, the
  offer-reason spelling. DR-0029 is amended to match.

Updates the readiness and projection schema descriptions, index.json, the
media-buy specification, list_products, get_media_buy_delivery,
sync_creatives and get_adcp_capabilities docs, the experimental status
page, the training agent's change classifier, and the tests. The
additive-minor check compares against 3.2.x, which has none of the three
enums, so no baseline entry is needed. The 3.3 release pages are left to
adcontextprotocol#8883.

Part of adcontextprotocol#8901
…elling

The hosted 3.3-beta.5 preview validates responses against the beta.5
bundle, whose creative-change-kind enum has click_through. A caller pinned
to it now gets click_through in live_updates.in_place, staged_update
change_kinds and the CREATIVE_LIVE_UPDATE_UNSUPPORTED details; every
other caller gets clickthrough.
The execution readiness bullets in whats-new-in-3-3 and the 3.2-to-3.3
migration guide, and the live creative updates paragraph in the migration
guide, now give input-required and clickthrough.
@mintlify

mintlify Bot commented Nov 13, 2026

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit e200442.

Approve preview

@aao-secretariat

Copy link
Copy Markdown
Contributor

Ladon cannot review this PR until merge conflicts are resolved.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant