83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
# 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.
|