Which schema shaped my Format run? output_schema.source explained

Every Sume Format run receipt carries output_schema: { name, strict, source }, and source says which schema shaped output: default for the built-in schema, action_default for a schema bound to the Format itself, and request_override for the one you sent on this run. A per-request output_schema always overrides the Format's own default.

Reading source first saves debugging time. If the shape of output surprises you, the first question is not what the run did but which contract was applied.

What do the three values mean?

The structured output page defines them. default means nothing was bound, so output is the built-in sume/action-run-output/v1 shape, filled deterministically from the run's media and closing text. action_default is the Format's own bound schema, set in the dashboard. request_override is the output_schema on the request.

The action_ prefix is the wire spelling shared with Scheduled runs, so do not read it as a different kind of Format.

Why is the built-in schema the safe fallback?

Because no model is involved, it cannot fail the way a custom schema can. The built-in schema is filled deterministically from the run's generated media and its final text, with text nullable and four arrays (images, videos, audio, files) that are always present and may be empty. A custom schema is filled by the run, or by a projection pass if the run did not submit a valid object, and either can fail the checks.

If you only need the media, the built-in output is already enough to ship on, and it keeps output_schema_unsatisfied out of your error handling entirely.

How do I override the Format's schema for one run?

Send output_schema on the create call. The receipt's source will read request_override, and the Format's own default is untouched for every other caller. The OpenAI-shaped response_format alias is normalized into output_schema on the receipt, so what you read back is always the native spelling; sending both is 400 invalid_request.

Pair it with primary_output_key so the receipt resolves the one thing your UI shows. Resolution order is the key on the request, then the Format's own key, then the first top-level media key.

curl -sS -X POST "https://api.sume.com/v1/formats/acme/promo-hero/runs" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: sku-1042-hero-v1" \
  -d '{"instruction":"One hero image.",
       "output_schema":{"name":"acme/hero/v1","strict":true,"schema":{
         "type":"object","additionalProperties":false,
         "required":["hero_image"],
         "properties":{"hero_image":{"$ref":"SumeMediaFile#"}}}},
       "primary_output_key":"hero_image"}' \
  | jq '.data.output_schema'

What should an integration log from this field?

Log output_schema.name and source with the run id. When you bind your own schema, namespace the name and keep it stable, because it appears on every receipt and makes receipts greppable. A run that unexpectedly reports default or action_default tells you your override never reached the call, which is usually a body-building bug on your side rather than a platform problem.