Use 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.
Structured Output is in beta. It is available to accounts enrolled in the TinyFish beta program. If your account does
not have access yet, requests with output_schema return 403 FORBIDDEN. Join the beta program at
agent.tinyfish.ai/beta. Example
{
"output_schema": {
"type": "object",
"properties": {
"title": { "type": "string" },
"price": { "type": "number", "minimum": 0 },
"published_at": {
"type": "string",
"format": "date-time",
"nullable": true
},
"tags": {
"type": "array",
"items": { "type": "string" },
"maxItems": 10
}
},
"required": ["title", "price"],
"propertyOrdering": ["title", "price", "published_at", "tags"]
}
}
Top-Level Constraints
| Constraint | Rule |
|---|
| Top-level shape | Must be a JSON object. If type is present, it must be object |
Top-level anyOf | Not supported. Put composition inside object fields instead |
| Size limit | Serialized schema must be 64KB or smaller |
| Nesting depth | Maximum depth is 10 |
| Boolean schema nodes | true and false schemas are not supported |
| Nullable values | Use nullable: true, not type: ["string", "null"] |
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
| Type | Notes |
|---|
object | Supports properties, required, and propertyOrdering |
array | Supports items, minItems, and maxItems |
string | Supports enum and format |
number | Supports minimum and maximum |
integer | Supports minimum and maximum |
boolean | Supported as a field type |
Supported Keywords
Any keyword outside this allowlist is rejected:
anyOfenumformatitemsmaxItemsmaximumminItemsminimumnullablepropertiespropertyOrderingrequiredtype
Important Rules
- Use
anyOf for composition. oneOf is not supported.
enum requires type: "string", and every enum value must be a string.format requires type: "string". Supported formats are date, date-time, duration, and time.items, minItems, and maxItems require type: "array".minimum and maximum require type: "number" or type: "integer".propertyOrdering requires properties, values must be unique, and every referenced field must exist in
properties.required fields must also exist in properties, unless the requirement is being expressed inside an anyOf branch.- Stored runs include the requested schema as
output_schema on GET /v1/runs/{id} and runs.list().
Common Rewrites
| Instead of | Use |
|---|
oneOf | anyOf |
const: "ready" | type: "string", enum: ["ready"] |
type: ["string", "null"] | type: "string", nullable: true |
type: ["number", "null"] | type: "number", nullable: true |
type: ["integer", "null"] | type: "integer", nullable: true |
Commonly Rejected Keywords
These are not supported in output_schema:
additionalPropertiesconstexampleexamplesoneOf
Any other keyword outside the supported allowlist is also rejected.
Example Errors
The API returns a 400 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.
