schema.json defines the expected structure of a skill’s output using JSON Schema draft-07. When a skill is executed, the platform validates the agent’s response against this schema to ensure structured, consistent results.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"title": "invoice-extraction",
"description": "Structured data extracted from an invoice document",
"properties": {
"invoice_id": {
"type": "string",
"description": "Unique invoice identifier"
},
"invoice_date": {
"type": "string",
"format": "date",
"description": "Invoice date in ISO 8601 format"
},
"total_amount": {
"type": "number",
"description": "Total invoice amount"
}
},
"required": ["invoice_id", "invoice_date", "total_amount"],
"additionalProperties": false
}
Key Fields
| Field | Description |
|---|
$schema | JSON Schema version — use http://json-schema.org/draft-07/schema# |
type | Top-level type — typically "object" |
title | Human-readable name for the schema |
description | What the schema validates |
properties | Object properties with types and descriptions |
required | Array of mandatory field names |
additionalProperties | Set to false to disallow extra fields |
Property Types
Supported JSON Schema types for properties:
| Type | Example | Use Case |
|---|
string | "invoice-001" | Text fields, IDs, descriptions |
number | 42.5 | Amounts, scores, measurements |
integer | 3 | Counts, indices |
boolean | true | Flags, binary classifications |
array | [...] | Lists of items |
object | {...} | Nested structures |
String Constraints
{
"date": {
"type": "string",
"format": "date",
"description": "Date in YYYY-MM-DD format"
},
"category": {
"type": "string",
"enum": ["invoice", "receipt", "purchase_order"],
"description": "Document category"
},
"timestamp": {
"type": "string",
"pattern": "^\\d{2}:\\d{2}$",
"description": "Timestamp in MM:SS format"
}
}
Array Items
{
"line_items": {
"type": "array",
"description": "List of invoice line items",
"items": {
"type": "object",
"properties": {
"description": { "type": "string" },
"quantity": { "type": "integer" },
"unit_price": { "type": "number" }
},
"required": ["description", "quantity", "unit_price"]
}
}
}
Relationship to Skill Creation
When creating a skill from a prompt, you can pass a json_schema parameter. The platform uses this to generate the schema.json file within the skill package:
skill = client.agent.skills.create(
prompt="Extract invoice data",
json_schema={
"type": "object",
"properties": {
"invoice_id": {"type": "string"},
"total_amount": {"type": "number"}
},
"required": ["invoice_id", "total_amount"]
}
)
schema.json directly in the skill directory.
Include description on every property. The model uses these descriptions to understand what data to extract and how to format it.
