schema.json

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.

Format

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

When creating a skill from a file (zip upload), include 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.

Overview

Specification

Using Skills

Managing Skills

Format

Key Fields

Property Types

String Constraints

Array Items

Relationship to Skill Creation

​Format

​Key Fields

​Property Types

​String Constraints

​Array Items

​Relationship to Skill Creation

Format

Key Fields

Property Types

String Constraints

Array Items

Relationship to Skill Creation