output_schema when you want TinyFish to return the final run result in a predictable JSON shape.
The same rules apply across the REST API, SDKs, CLI, Playground, and MCP integrations as they all forward to the same API validator.
Example
The Schema Is the Contract
output_schema defines the exact shape of the result. When your schema and your prompt
disagree about whether to return a single object or a list, the schema wins — the
result is shaped to match the schema, not the wording of the prompt.
A schema that describes a single object returns a single object, even if the prompt asks
for “10 results”. To return a list, the schema must say so explicitly (see below).
Returning a List of Items
The top level must always be an object, so a list of results goes in an array field:Top-Level Constraints
type: "boolean" is supported for fields in your result. What is not supported is using a schema node that is itself
the literal boolean true or false.Supported Types
Supported Keywords
Any keyword outside this allowlist is rejected:anyOfenumformatitemsmaxItemsmaximumminItemsminimumnullablepropertiespropertyOrderingrequiredtype
Important Rules
- Use
anyOffor composition.oneOfis not supported. enumrequirestype: "string", and every enum value must be a string.formatrequirestype: "string". Supported formats aredate,date-time,duration, andtime.items,minItems, andmaxItemsrequiretype: "array".minimumandmaximumrequiretype: "number"ortype: "integer".propertyOrderingrequiresproperties, values must be unique, and every referenced field must exist inproperties.requiredfields must also exist inproperties, unless the requirement is being expressed inside ananyOfbranch.- Stored runs include the requested schema as
output_schemaonGET /v1/runs/{id}andruns.list().
Common Rewrites
Commonly Rejected Keywords
These are not supported inoutput_schema:
additionalPropertiesconstexampleexamplesoneOf
Example Errors
The API returns a400 error before execution when the schema is invalid. Common validation messages include:
output_schema field "oneOf" is not supported at #. Use "anyOf" instead.output_schema top-level "anyOf" is not supported at #. Top-level schema must declare "type": "object".output_schema type arrays are not supported at #/properties/title. Use 'type: "string", nullable: true' instead.output_schema field "additionalProperties" is not supported at #.output_schema exceeds the maximum nesting depth of 10.
Related
Get a TinyAgent Run as Structured JSON
Walked-through how-to, Playground and API, including common mistakes
Agent Reference
Where
output_schema fits in the full request bodyQuick Start
Your first request end to end
CLI Commands
Pass
output_schema from the command line