PLAYBOOK.md Schema

Machine-readable schema definitions for the PLAYBOOK.md specification.

This repo provides:

• TypeScript types (src/) — source of truth for the data model
• JSON Schema (generated/) — generated from TypeScript, used for validation

Data Model

The schema defines the parsed representation of a PLAYBOOK.md document:

PlaybookDefinition
├── title: string
├── description?: string
├── system_prompt?: string
├── artifact_type?: ArtifactType
├── inputs: InputDef[]
│   ├── name: string
│   ├── type: "string" | "text" | "number" | "boolean" | "enum"
│   ├── default?: string
│   ├── options?: string[]       (enum only)
│   ├── description?: string
│   └── required: boolean
└── steps: Step[]
    ├── number: number
    ├── label: string            ("1", "2a", "3b")
    ├── title: string
    ├── content: string
    ├── prompt_ref?: { prompt_id: string }
    ├── output_var?: string
    ├── extract_field?: string
    ├── elicitation?: ElicitationDef
    │   ├── type: "input" | "confirm" | "select"
    │   ├── prompt: string
    │   └── options?: string[]
    ├── tool_call?: StepToolCall
    │   ├── connection_name: string
    │   ├── tool_name: string
    │   └── arguments?: string   (JSON)
    ├── is_branching: boolean
    └── branches?: Branch[]
        ├── condition?: Condition
        │   ├── variable: string
        │   ├── operator: "==" | "!="
        │   ├── value: string
        │   └── source: "input" | "step_output"
        └── steps: Step[]        (sub-steps)

Usage

TypeScript

import type { PlaybookDefinition, Step, InputDef } from '@playbook-md/schema';

JSON Schema Validation

import Ajv from 'ajv';
import schema from '@playbook-md/schema/generated/playbook.schema.json';

const ajv = new Ajv();
const validate = ajv.compile(schema);

const parsed = myParser.parse(markdownContent);
const valid = validate(parsed);

Development

npm install
npm run build       # Generate JSON Schema from TypeScript
npm run validate    # Validate generated schema
npm test            # Run tests

Versioning

Schema versions track the spec versions. Each tagged spec release gets a corresponding schema release.

License

MIT