> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tinyfish.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured-output schema

> Structured-output schema support for the output_schema request field

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

```json theme={null}
{
  "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:

```json theme={null}
{
  "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"]` |

> [!NOTE]
>
> `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.`

## Related

> [card] [Get a TinyAgent Run as Structured JSON](https://docs.tinyfish.ai/tinyagent/how-to/structured-output.md)
>
> Walked-through how-to, Playground and API, including common mistakes

> [card] [Agent Reference](https://docs.tinyfish.ai/tinyagent/api/agent)
>
> Where `output_schema` fits in the full request body

> [card] [Quick Start](https://docs.tinyfish.ai/quick-start.md)
>
> Your first request end to end

> [card] [CLI Commands](https://docs.tinyfish.ai/cli/commands.md)
>
> Pass `output_schema` from the command line


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.