Skip to content

Is status meant to be required in the completed branch of refine-proposals-response and request-proposals-response? #8698

Open

Description

@KonstantinMirin

A question rather than a bug report: both documents below are self-consistent, and we can represent them either way. We would rather ask than guess.

The question

media-buy/refine-proposals-response.json declares the response as a two-branch anyOf:

branch required properties.status
#/anyOf/0 ["results", "products"] {"type": "string", "const": "completed"}
#/anyOf/1 ["status", "task_id"] {"type": "string", "const": "submitted"}

The root declares properties.status as {"type": "string", "enum": ["completed", "submitted"]} and has no required of its own.

So the completed branch pins status without requiring it, while the submitted branch requires it. An instance carrying results and products with no status key is valid, and a client receiving it has no status field to read.

media-buy/request-proposals-response.json has the same asymmetry across four branches, and three of its four pin status to the same value "completed":

branch required properties.status
#/anyOf/0 ["outcome", "proposals", "products"] const: "completed"
#/anyOf/1 ["outcome", "products", "purchase_continuation"] const: "completed"
#/anyOf/2 ["outcome", "reason"] const: "completed"
#/anyOf/3 ["status", "task_id"] const: "submitted"

Did you mean status required in every branch?

Why we think it may be an oversight

Measured over every combinator in bundle 3.2 whose branches all pin one shared property:

  • 4,441 also list that property in every branch's required
  • 24 do not, in 16 documents
    • 18 are oneOf, where an absent key leaves several branches matching, so oneOf rejects the instance and the key is required by implication
    • 6 are anyOf, where an absent key leaves the instance valid without identifying its branch

The six anyOf sites, over four distinct nodes (two reached twice, once directly and once through core/mcp-webhook-payload.json#/properties/result):

core/async-response-data.json#/anyOf/5/anyOf              status   4 branches, 3 not requiring it
core/async-response-data.json#/anyOf/7/anyOf              status   2 branches, 1 not requiring it
media-buy/refine-proposals-response.json#/anyOf           status   2 branches, 1 not requiring it
media-buy/request-proposals-response.json#/anyOf          status   4 branches, 3 not requiring it

The asymmetry inside a single union, against 4,441 sites that require the key, is what prompts the question.

What is not being claimed

The documents are sound. In refine-proposals-response.json the two branches have disjoint required sets — ["results", "products"] against ["status", "task_id"] — so no instance satisfies both, and an instance omitting status is valid and unambiguous. A client can identify the branch from the keys present.

We are not blocked. If status is deliberately optional in the completed branch, say so and we will leave it optional; the answer only changes which fact our generated types state, not whether they can state it.

If the answer is "required in every branch"

Adding "status" to #/anyOf/0's required in both documents makes status a usable discriminant for clients, consistent with the 4,441 sites that already do this. It narrows the accepted set, so it is a breaking change for any producer currently omitting the key.

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
    questionFurther information is requested
    claude-triagedIssue has been triaged by the Claude Code triage routine. Remove to re-triage.
    on Nov 9, 2026
  3. bokelley commented on Nov 11, 2026

    @bokelley
    Contributor

    Yes. status is required on every task response, the completed branch included. The rule lives in the envelope, not the body: core/protocol-envelope.json has required: ["status"] and says "Agents shipping responses without a top-level status are non-conformant regardless of whether the task body schema would otherwise validate." That text is the same on 3.2.x and main.

    The asymmetry you measured comes from the 3.2 body schemas not composing the envelope. From 3.3.0-beta.3, every task response composes it (allOf: [{"$ref": "/schemas/core/protocol-envelope.json"}], #8547), so on 3.3 an instance of either document without status fails in every branch. The const: "completed" pins in the body branches narrow the value; they were never meant to make the key optional.

    For generated 3.2 types: state status as required. No conformant 3.2 producer omits it, so nothing narrows. The same answer covers the two core/async-response-data.json sites, which are the same nodes reached through the webhook result. In 4.0, bodies-only responses with generated status unions (#8565) and literal discriminators (#8191) should remove the duplicated pins altogether.

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.questionFurther information is requestedschemaJSON 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