Skip to content

feat(schema): add native creative localization contract#5914

Draft
bokelley wants to merge 3 commits into
mainfrom
bokelley/adcp-native-localization-contract
Draft

feat(schema): add native creative localization contract#5914
bokelley wants to merge 3 commits into
mainfrom
bokelley/adcp-native-localization-contract

Conversation

@bokelley

@bokelley bokelley commented Jul 19, 2026

Copy link
Copy Markdown
Contributor

Why

AdCP has no typed way to request or read back provider-native creative localization. Implementations must either reject localization or accept unvalidated provider extensions, which loses locale, asset, review, and variant identity across sync_creatives and list_creatives. This blocks adcp-client#2370 and downstream Meta exact-readback work.

What Changed

  • Added a provider-neutral, sync-only localization write contract. sync_creatives.creatives[].localization uses explicit typed oneOf arms for buyer-supplied and provider-generated targets; inline creatives on media-buy create/update reject localization.
  • Added creative.localization capability discovery with the current supported locale set, translation modes, variant ceiling, and review scope.
  • Added typed source/buyer/provider readback arms and exact request → sync → list verifier constraints for source ID/locale and target ID/locale/mode.
  • Made top-level platform_id the single provider creative identity; localization retains only per-variant provider IDs.
  • Required complete status/platform/localization evidence for accepted localized sync results and excluded localization from failed/deleted results.
  • Enforced status/launch compatibility, machine-readable blockers, deterministic aggregate status, and whole-creative archive atomicity.
  • Made localized-source upserts fail closed: omitting localization can preserve topology only when source assets are exactly unchanged; source changes require a full topology or explicit removal.
  • Kept locale_variant_id separate from both build_variant_id and delivery variant_id.
  • Updated normative docs, schema-extension guidance, composed conformance coverage, and the minor changeset.

Exact implementation head: 8ca0b9f1bc597b42c715cdfb7372abea572fc4e4.

Test Plan

  • npm run build:schemas — pass (651 source schemas; 89 bundled schemas)
  • npm run test:schemas — pass (19/19)
  • npm run test:composed — pass (172/172, including standalone bundled compilation)
  • npm run test:json-schema — pass (285 schema-backed documentation examples)
  • npm run test:platform-agnostic — pass
  • npm run test:oneof-discriminators — pass (no new undiscriminated unions)
  • npm run test:schema-utf8 — pass
  • npm run lint:schema-links — pass
  • npm run typecheck — pass
  • Push gates — pass (version sync, changeset policy, schema-link convention, Mintlify broken links)

The full local suite also exposed two pre-existing environment/baseline failures unrelated to this diff: released 3.1.3 is correctly marked withdrawn while dist-schema-version-ids still expects every semver release to be stable, and nine C2PA tests cannot load the cloned native Mach-O slice on this host. This PR changes neither area; Linux CI remains authoritative for those checks.

Unblocks adcontextprotocol/adcp-client#2370; that issue remains open until a generated client release consumes this schema.

@bokelley bokelley added creative schema JSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene spec / protocol needs-wg-review Blocked on a working-group decision — surface in WG meeting agendas labels Jul 19, 2026
@bokelley
bokelley marked this pull request as ready for review July 19, 2026 12:13
@bokelley
bokelley requested a review from benminer July 19, 2026 12:13

@aao-secretariat aao-secretariat Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Argus is not auto-reviewing this PR because it modifies protected paths that require human review (.changeset/add-native-creative-localization-contract.md, static/schemas/source/core/creative-asset.json, static/schemas/source/core/creative-localization-readback.json, static/schemas/source/core/creative-localization.json, static/schemas/source/core/locale-tag.json, static/schemas/source/core/x-entity-types.json, static/schemas/source/creative/list-creatives-request.json, static/schemas/source/creative/list-creatives-response.json, static/schemas/source/creative/sync-creatives-response.json, static/schemas/source/index.json, static/schemas/source/protocol/get-adcp-capabilities-response.json). A human reviewer should review and merge this PR; Argus will resume on subsequent PRs once these changes land on main.

@bokelley

Copy link
Copy Markdown
Contributor Author

Independent exact-head contract audit found five substantive blockers despite 31/31 CI: generated union narrowing, request→sync→list equality, status/launch and whole-creative archive invariants, source-update semantics, and accidental inline-trafficking scope. I moved this PR back to draft while those are corrected; please hold human review until a new exact head is posted. The provider-neutral identity/mode model remains the right direction, but downstream Meta must not claim exact localization against an underconstrained contract.

@bokelley
bokelley marked this pull request as draft July 19, 2026 12:20
@bokelley

Copy link
Copy Markdown
Contributor Author

The five HOLD findings are addressed at exact head 8ca0b9f1bc597b42c715cdfb7372abea572fc4e4:

  1. Request and readback variants are explicit typed oneOf arms with required string const discriminators.
  2. Machine-readable verifiers and tests enforce exact request → sync → list identity, accepted/failed action boundaries, and one top-level provider creative ID.
  3. Status/launch pairs, blockers, aggregate status, and whole-creative archive atomicity are enforced.
  4. Localized source upserts reject ambiguous source changes when localization is omitted.
  5. Localization writes are scoped to sync_creatives; inline create/update package creatives reject the field.

The rebuilt schema, composed (172/172), documentation JSON, oneOf, platform-agnostic, UTF-8, schema-link, TypeScript, changeset-policy, and Mintlify push gates pass. I am leaving the PR draft for CI and protected-path human review.

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

Labels

creative needs-wg-review Blocked on a working-group decision — surface in WG meeting agendas schema JSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene spec / protocol

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant