# JSON Schema Definition Files

Schema definition files describe the expected JSON output contract for prompts that use:

- `output.format: json`
- `output.validation_mode: json_schema`

Schema files are JSON, typically stored under `schemas/`, for example `schemas/structured_events.schema.json`.

## Complete Example

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/schemas/structured-events.schema.json",
  "title": "Structured Events",
  "description": "Expected shape for extracted event output",
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "minLength": 1,
      "description": "High-level session summary"
    },
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "type": {
            "type": "string",
            "enum": ["discovery", "combat", "social", "travel", "downtime", "other"]
          },
          "notes": { "type": "string" }
        },
        "required": ["title", "type"],
        "additionalProperties": false
      },
      "minItems": 0
    }
  },
  "required": ["summary", "events"],
  "additionalProperties": false,
  "$defs": {
    "nonEmptyString": {
      "type": "string",
      "minLength": 1
    }
  }
}
```

## Available Options

Scriptorium does not define custom schema keywords. It expects a valid JSON Schema document and passes it to the validator/provider.

Commonly used JSON Schema options include:

- `$schema`: Draft identifier URI.
- `$id`: Schema identifier URI.
- `title`: Human-readable schema title.
- `description`: Human-readable schema description.
- `type`: Expected JSON type (`object`, `array`, `string`, etc.).
- `properties`: Object field definitions.
- `required`: Required object fields.
- `additionalProperties`: Whether undeclared fields are allowed.
- `items`: Array item schema.
- `enum`: Allowed literal values.
- `const`: Single allowed literal value.
- `oneOf`, `anyOf`, `allOf`: Composition rules.
- `minimum`, `maximum`: Numeric bounds.
- `minLength`, `maxLength`, `pattern`: String constraints.
- `minItems`, `maxItems`: Array constraints.
- `$defs`: Reusable local definitions.
- `$ref`: Reference to another schema/definition.

## Notes and Rules

- Schema path comes from prompt `output.schema_path` and is resolved relative to `schema_dir`.
- If schema loading fails for `json_schema` mode, the run fails before the LLM request.
- Keep schemas strict (`additionalProperties: false`) when you want predictable output shape.