Skip to main content
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.

​
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:
Without the array field, a prompt like “list 10 tools” returns only the first match, because the schema describes a single object.

​
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:
  • anyOf
  • enum
  • format
  • items
  • maxItems
  • maximum
  • minItems
  • minimum
  • nullable
  • properties
  • propertyOrdering
  • required
  • type

​
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

​
Commonly Rejected Keywords

These are not supported in output_schema:
  • additionalProperties
  • const
  • example
  • examples
  • oneOf
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.