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

# schema.json

> JSON Schema for validating skill output

`schema.json` defines the expected structure of a skill's output using [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-release-notes). When a skill is executed, the platform validates the agent's response against this schema to ensure structured, consistent results.

## Format

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "$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

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "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

```json theme={"theme":{"light":"github-light","dark":"dark-plus"}}
{
  "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](/skills/manage/create), you can pass a `json_schema` parameter. The platform uses this to generate the `schema.json` file within the skill package:

```python theme={"theme":{"light":"github-light","dark":"dark-plus"}}
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.

<Tip>
  Include `description` on every property. The model uses these descriptions to understand what data to extract and how to format it.
</Tip>