Agent Schemas

January 8, 2026 · View on GitHub

Note: This is a community project, not affiliated with Anthropic.

JSON Schema definitions for AI coding agent session formats.

Why This Repo Exists

To build apps on top of coding agents, you need to parse and load their session messages.

The Claude Agent SDK doesn't yet provide programmatic access to session history or type definitions for the JSONL format (#109). This repo fills that gap with reverse-engineered JSON schemas, enabling:

Type-safe parsing for building UIs and tools
Session data validation
Type generation for any language

Supported Agents

Agent	Versions	Status
Claude Code	v2.0.76, v2.1.1	Complete

Quick Start

Generate Types

# TypeScript
npx json-schema-to-typescript \
  claude-code/v2.1.1/session.schema.json \
  -o claude-code.d.ts

# Python
npx quicktype \
  --src claude-code/v2.1.1/session.schema.json \
  --src-lang schema \
  --lang python \
  -o claude_code_types.py

Validate Session Files

# Clone the repo
git clone https://github.com/moru-ai/agent-schemas.git
cd agent-schemas

# Setup (one-time)
python3 -m venv .venv
source .venv/bin/activate
pip install jsonschema

# Validate Claude Code sessions
python claude-code/validate.py ~/.claude/projects/<your-project>/

Use in Code

import json
import requests
from jsonschema import Draft202012Validator

# Fetch schema from GitHub
schema_url = "https://raw.githubusercontent.com/moru-ai/agent-schemas/main/claude-code/v2.1.1/session.schema.json"
schema = requests.get(schema_url).json()
validator = Draft202012Validator(schema)

# Validate a session file
with open("session.jsonl") as f:
    for line_num, line in enumerate(f, 1):
        data = json.loads(line)
        errors = list(validator.iter_errors(data))
        if errors:
            print(f"Line {line_num}: {errors[0].message}")

// TypeScript with Ajv
import Ajv from 'ajv';

const ajv = new Ajv({ loadSchema: async uri => (await fetch(uri)).json() });
const validate = await ajv.compileAsync({
  $ref: 'https://raw.githubusercontent.com/moru-ai/agent-schemas/main/claude-code/v2.1.1/session.schema.json',
});

const isValid = validate(messageData);

How We Made This

The schemas are reverse-engineered from actual session data, not official documentation.

Process

Data Collection: Gathered ~50,000 messages across 480 session files from real Claude Code usage
Field Discovery: Analyzed all unique fields, types, and patterns in the data
Schema Writing: Created JSON Schema Draft 2020-12 definitions covering all message types, tool inputs, and content blocks
Iterative Validation: Ran validation against all session data, fixing schema issues until 100% pass rate
Version Differentiation: Identified version-specific fields (e.g., toolUseResult in v2.1.1)

Validation Results

Agent	Files	Messages	Pass Rate
Claude Code	480	52,057	100%

Limitations

Schemas describe observed data, not official spec
Undiscovered message types may exist
Future CLI versions may introduce breaking changes
additionalProperties: true allows forward compatibility

Repository Structure

agent-schemas/
├── README.md                 # This file
└── claude-code/
    ├── README.md             # Claude Code specific docs
    ├── validate.py           # Validation script
    ├── history.schema.json   # ~/.claude/history.jsonl schema
    ├── v2.0.76/
    │   └── session.schema.json
    └── v2.1.1/
        └── session.schema.json

Contributing

We welcome contributions for schema improvements.

Improving Existing Schemas

Find a message that fails validation
Add the missing field/type to the schema
Run validation to confirm fix
Submit PR with:
- Schema change
- Example of the previously-failing message (anonymized)

Guidelines

Use JSON Schema Draft 2020-12
Include $id, title, description, x-generated-date
Set additionalProperties: true for forward compatibility
Version schemas by CLI version
Validate against real data before submitting

License

MIT