Structured Output

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

{
  "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"]
  }
}

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:

{
  "output_schema": {
    "type": "object",
    "properties": {
      "results": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "url": { "type": "string" }
          },
          "required": ["name", "url"]
        }
      }
    },
    "required": ["results"]
  }
}

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

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:

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

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:

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.

Start Here

Agent API

Search API

Monitor

Fetch API

Browser API

Research API

Capabilities

Tools & Integrations

Guides

Use Cases

Reference

Example

The Schema Is the Contract

Returning a List of Items

Top-Level Constraints

Supported Types

Supported Keywords

Important Rules

Common Rewrites

Commonly Rejected Keywords

Example Errors

​Example

​The Schema Is the Contract

​Returning a List of Items

​Top-Level Constraints

​Supported Types

​Supported Keywords

​Important Rules

​Common Rewrites

​Commonly Rejected Keywords

​Example Errors

​Related

Example

The Schema Is the Contract

Returning a List of Items

Top-Level Constraints

Supported Types

Supported Keywords

Important Rules

Common Rewrites

Commonly Rejected Keywords

Example Errors

Related