Skip to content

fix(schema): make account.supported_billing conditional on media_buy protocol#3750

Merged
bokelley merged 1 commit into
3.0.xfrom
claude/issue-3746-conditional-billing-requirement
May 11, 2026
Merged

fix(schema): make account.supported_billing conditional on media_buy protocol#3750
bokelley merged 1 commit into
3.0.xfrom
claude/issue-3746-conditional-billing-requirement

Conversation

@bokelley

@bokelley bokelley commented May 1, 2026

Copy link
Copy Markdown
Contributor

Closes #3746

Summary

The get_adcp_capabilities response schema required account.supported_billing unconditionally for all agents, even those that don't declare media_buy in supported_protocols. The field has no semantics outside of media buying (operator-pays / advertiser-pays arrangements), and the schema's own description already stated "Expected when media_buy is in supported_protocols." This mismatch caused every non-media-buy agent (signals, creative, governance, brand, SI, measurement) that included an account block to fail schema validation on a single irrelevant field, which cascades into SDK v2-downgrade loops and storyboard failures across the board.

Changes:

  1. Removes "required": ["supported_billing"] from the account object definition — it was enforced unconditionally on any agent that included an account block.
  2. Adds a root-level allOf if/then constraint: account and account.supported_billing are required only when supported_protocols contains "media_buy". Uses the same contains: { const: "..." } + required: [...] guard pattern as governance/sync-plans-request.json.
  3. Updates account.description to surface the conditional rule at first read.
  4. Updates media_buy.description from "should include" to "MUST include" — the if/then now normatively enforces it.

Non-breaking justification: Relaxes a constraint for non-media-buy agents (they may now omit supported_billing from an account block without failing validation). Preserves the constraint for media-buy agents via the then branch. Any conformant 3.0.0 media-buy implementation already satisfies the new MUST — the description established the expectation; the schema constraint now aligns with it.

Code-generator note: draft-07 if/then is dropped by openapi-typescript, zod-to-json-schema, datamodel-code-generator pre-0.25, and quicktype. SDK generator targets should add a runtime guard requiring supported_billing when media_buy is declared and account is present. (The same caveat already applies to adcp.idempotency's oneOf in this schema per its existing inline comment.)

Pre-PR review

  • code-reviewer: approved — JSON Schema draft-07 valid, allOf placement correct, then.properties.account.required correctly overlays root account definition; redundant required: ["supported_protocols"] guard inside if is harmless (root-level required already enforces it); patch changeset level correct.
  • ad-tech-protocol-expert: approved — non-breaking per spec; then.properties.account type guard technically redundant given root-level "type": "object" on account (and the established repo pattern in sync-plans-request.json doesn't add type guards either); description nits addressed in this diff.

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

  • Push fixup commits directly: gh pr checkout <num>
    fix → push.
  • Or re-trigger: comment /triage execute on the source
    issue.

See #3121
for context.

Session: https://claude.ai/code/session_01VE9kbAjX6nAmAruFXbUeka


Generated by Claude Code

@bokelley bokelley added the claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage. label May 1, 2026
…protocol

Removes unconditional `required: ["supported_billing"]` from the `account`
object definition and replaces it with a root-level `allOf` `if/then`
constraint: `supported_billing` (and `account` itself) is required only when
`media_buy` is in `supported_protocols`.

The schema description already stated "Expected when media_buy is in
supported_protocols" — this aligns enforcement with documented intent.

Non-breaking: relaxes the constraint for non-media-buy agents (signals,
creative, governance, brand, SI); preserves it for media-buy agents via the
`then` branch. Any conformant 3.0 implementation already satisfies the new MUST.

Note: draft-07 `if/then` is dropped by some code generators (openapi-typescript,
zod-to-json-schema, quicktype). SDK generator targets should treat
`supported_billing` as required when `media_buy` is declared and `account`
is present.

Closes #3746

Session: https://claude.ai/code/session_01VE9kbAjX6nAmAruFXbUeka
@bokelley bokelley force-pushed the claude/issue-3746-conditional-billing-requirement branch from ef3d177 to 4783430 Compare May 11, 2026 18:51
@bokelley bokelley marked this pull request as ready for review May 11, 2026 18:52
@bokelley bokelley merged commit 6ed6bed into 3.0.x May 11, 2026
6 of 7 checks passed
@bokelley bokelley deleted the claude/issue-3746-conditional-billing-requirement branch May 11, 2026 18:52
bokelley pushed a commit that referenced this pull request May 13, 2026
…ture

The composed-schema-validation test for the adcp.idempotency oneOf
discriminator constructs a `capabilitiesBase` fixture declaring
`supported_protocols: ['media_buy']`. Since #3750 made
`account.supported_billing` conditional-required on `media_buy`, the
fixture itself fails the schema — the IdempotencySupported and
IdempotencyUnsupported positive-case assertions both error with
"must have required property 'account'".

This failure was masked while test:json-schema was red (npm chained the
test steps with &&); fixing the doc-block examples in this PR's earlier
commit surfaces it. Same fix shape — add the canonical
`{ supported_billing: ['operator', 'agent'] }` block.

Verified: npm run test:schemas / test:json-schema / test:extension-schemas /
test:composed all pass locally.
bokelley pushed a commit that referenced this pull request May 13, 2026
…es (unblocks 3.0.x CI) (#4483)

* docs(capabilities): add account.supported_billing to media_buy examples

#3750 made `account.supported_billing` conditionally required on
`get_adcp_capabilities_response` whenever `supported_protocols` contains
`media_buy`. Four illustrative example blocks in the docs were not
updated alongside the schema and have since been failing the docs
schema-validation step on every `3.0.x` PR, blocking the branch.

Each affected example now declares `account.supported_billing` with
`["operator", "agent"]`, matching the established pattern in
`docs/building/integration/accounts-and-agents.mdx`.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test(composed): add account.supported_billing to capabilitiesBase fixture

The composed-schema-validation test for the adcp.idempotency oneOf
discriminator constructs a `capabilitiesBase` fixture declaring
`supported_protocols: ['media_buy']`. Since #3750 made
`account.supported_billing` conditional-required on `media_buy`, the
fixture itself fails the schema — the IdempotencySupported and
IdempotencyUnsupported positive-case assertions both error with
"must have required property 'account'".

This failure was masked while test:json-schema was red (npm chained the
test steps with &&); fixing the doc-block examples in this PR's earlier
commit surfaces it. Same fix shape — add the canonical
`{ supported_billing: ['operator', 'agent'] }` block.

Verified: npm run test:schemas / test:json-schema / test:extension-schemas /
test:composed all pass locally.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Brian O'Kelley <brian@agenticadvertising.org>
@aao-release-bot aao-release-bot Bot mentioned this pull request May 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

claude-triaged Issue has been triaged by the Claude Code triage routine. Remove to re-triage.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants