Skip to main content
Use output_schema when you want TinyFish to validate the final run result against a constrained JSON Schema subset. The same rules apply across the REST API, SDKs, CLI, and MCP integrations as they all forward to the same API validator.
output_schema is optional and feature-gated. If your account does not have access yet, the API returns 403 FORBIDDEN.

​
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

ConstraintRule
Top-level shapeMust be a JSON object
Size limitSerialized schema must be 64KB or smaller
Nesting depthMaximum depth is 10
Boolean schema nodestrue and false schemas are not supported
Nullable valuesUse 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

TypeNotes
objectSupports properties, required, and propertyOrdering
arraySupports items, minItems, and maxItems
stringSupports enum and format
numberSupports minimum and maximum
integerSupports minimum and maximum
booleanSupported 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.

​
Common Rewrites

Instead ofUse
oneOfanyOf
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
  • 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 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.