Skip to content

The submitted-task envelope is named in core/compact-task-submitted.json and still restated inline at 9 nodes #8470

Open

Description

@KonstantinMirin

Summary

core/compact-task-submitted.json names the submitted-task envelope. #8547 and #8934 fixed
the wire defect this issue reported: every submitted response now composes
core/task-submitted.json, whose task_id refers to core/task-id.json (minLength: 1), so
no submitted response accepts "task_id": "". What remains is structural: 9 nodes restate the
named document's properties inline instead of referencing it.

We found this generating a typed SDK from the bundle, where each declaration has to be
reproduced faithfully, so a shape declared two ways becomes two types. Everything below is
measured over the 1,115 source documents at da254264d6, and every claim names the
pointer it was read from, so any of it can be checked or dismissed.

What the bundle states

core/compact-task-submitted.json composes core/protocol-envelope.json and
core/task-submitted.json in allOf, declares {context, errors, ext}, and states
additionalProperties: true.

count
documents that $ref it (not counting index.json) 10
nodes that restate its properties inline 9, in 9 documents
documents that do both 0

The split runs between siblings in one directory. media-buy/accept-proposal-async-response-submitted.json
references it. media-buy/build-creative-async-response-submitted.json
inlines it.

The inline sites:

creative/sync-creatives-async-response-submitted.json                               /
creative/sync-creatives-response.json                                        /oneOf/2
media-buy/build-creative-async-response-submitted.json                              /
media-buy/build-creative-response.json                                       /oneOf/5
media-buy/sync-audiences-response.json                                       /oneOf/2
media-buy/sync-catalogs-async-response-submitted.json                               /
media-buy/sync-catalogs-response.json                                        /oneOf/2
media-buy/update-media-buy-async-response-submitted.json                            /
media-buy/update-media-buy-response.json                                     /oneOf/2

The copies are now identical

Each of the 9 nodes composes core/task-submitted.json in allOf and declares
{context, errors, ext}. With description and other annotations removed, its properties are
identical to the named document's. The remaining divergence between the copies is description
text.

Why it matters

On SDK generation. A generator reproduces what each declaration states, so one concept
declared ten ways becomes ten types. It cannot collapse them on its own: two
documents that agree today are still two independent schemas, and inferring that they are "the
same type" would silently couple them, so that a later change to one would be emitted for both.
The duplication is therefore not something a downstream generator can fix. It has to be fixed
where the shape is declared.

On ergonomics. A buyer integrating against a generated SDK sees nine differently named
types for one envelope and no single symbol to program against. The same holds for anyone
hand-writing a client from the schemas: there is no one name for the thing.

What we propose

Replace each inline declaration with $ref to core/compact-task-submitted.json, exactly as
the 10 documents that already reference it do.

The change accepts and rejects the same payloads. Each of the 9 nodes already composes
core/task-submitted.json, and each response root already composes
core/protocol-envelope.json, so the $ref adds nothing the node doesn't already state.

What it does not require: no new file, no $id change, no new wire semantics, no change to any
document that already references the envelope. It is an alignment of the source schemas and
nothing else — the same class of change as #8453, which keeps ownership outside the schemas so
no published schema or $id moves.

Per-site descriptions are worth keeping where they say something specific. A $ref with a
sibling description carries that, and the bundle already uses that pattern elsewhere.

Method

Counts are over the 1,115 source documents at da254264d6 (static/schemas/source; the
built bundled/ and mcp/ directories are projections of the same documents and counting them
inflates every figure). The walk descends properties, items, additionalProperties, not,
propertyNames, allOf, anyOf, oneOf, if/then/else, patternProperties,
contains, $defs and definitions. A node was treated as a declaration of this shape when
it composes core/task-submitted.json in allOf, states properties whose key set equals the
named document's, and carries no $ref.

Revised 2026-11-19: #8547 and #8934 fixed the empty task_id on the wire, so this issue is narrowed to the 9 nodes that still restate core/compact-task-submitted.json inline.

Activity

  1. added this to the Spec Backlog milestone on Nov 9, 2026
  2. added
    schemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    on Nov 9, 2026
  3. changed the title [-]The submitted-task envelope is named in core/compact-task-submitted.json and re-declared inline 16 times, each dropping task_id.minLength[/-] [+]The submitted-task envelope is named in core/compact-task-submitted.json and still restated inline at 9 nodes[/+] on Nov 19, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.schemaJSON Schema source-of-truth: definitions, codegen artifacts, validation, hygiene

    Type

    No type

    Projects

    No projects

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions