Output schema unsupported_ref: $defs must live at the schema root
A $ref to a nested $defs, an external URL or a missing name fails with unsupported_ref in a Sume output_schema. Move $defs to the root and fix the pointer.
Sume resolves only two $ref targets in an output_schema: #/$defs/<name> for your own definitions, declared at the root of the document, and SumeMediaFile# for its media shape. Anything else is the rule unsupported_ref: a URL, a sibling document, #/components/..., $ref: "#", or a name with no entry in root $defs (Structured output).
Typical causes
If $defs itself is not an object of named schemas, the rule is invalid_defs instead.
| You wrote | Fix |
|---|---|
$ref: "https://example.com/scene.json" | Copy the shape into root $defs. |
#/components/schemas/Scene (from OpenAPI) | Rename to #/$defs/Scene and move the entry. |
$defs inside a property | Move the block to the root. Nested blocks are not found. |
$ref: "#" | Recurse through a named definition. |
#/$defs/scene with no scene entry | Add the entry, or fix the spelling. |
Example
SumeMediaFile# is the built-in shape for a file the run made. Sume fills it from the media the run produced, and a URL that the run did not make is rejected.
{
"type": "object",
"additionalProperties": false,
"required": ["hero"],
"properties": { "hero": { "$ref": "SumeMediaFile#" } }
}Sources
Related posts
More in Formats
- Output schema max_enum_values: 1,000 values per enum, then what
Sume refuses an enum of more than 1,000 values with rule max_enum_values. Use a string with a pattern or format, or split the list into two enums.
- Output schema max_depth: 10 levels, and $defs recursion is free
Sume's output_schema allows 10 levels of literal nesting. Past that you get max_depth. A self-referencing $defs entry does not add to the depth count.
- Output schema max_string_length: descriptions use a 120,000 budget
A big Format output_schema can fail with max_string_length although no field is long. The 120,000-character budget covers every key, name and string in it.
- Output schema node with only a description: missing_type violation
A property with only a description is legal JSON Schema, but Sume rejects it with missing_type. Give it a type, a $ref or an anyOf, and move constraints.
Written by Sume