scriptorium/docs/config/schema-definitions.md

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

{
  "$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.