SMALL

Schemas

SMALL schemas define the valid shape of each artifact.

V1 artifact schemas

  • intent
  • constraints
  • plan
  • progress
  • handoff

V2 record schemas

V2 is not an extension of the v1 YAML records. It has separate schemas for:

  • profile
  • session
  • event
  • receipt

The reducer also validates policy revisions and explicit conflict resolutions as part of the v2 authoritative tree.

Why schemas exist

  • Prevent drift and "AI vibes"
  • Enable validation in CI
  • Make handoffs portable across tools

Where to find them

  • Canonical source: github.com/justyn-clark/small-protocol under spec/small/
  • Vendored copy: This site maintains a pinned copy at vendor/small-protocol/spec/
  • Vendor lock file: vendor/small-protocol/VERSION records the source commit used for docs sync
  • Runtime schemas: Served at /schemas/small/v1/*.schema.json (compiled from canonical source)
  • V2 source schemas: Embedded in the v2 CLI and included in the site's vendored/public copies when the pinned protocol commit contains spec/small/v2.0.0/
  • Playground workflow schemas: Served separately at /schemas/workflow/v1/*.schema.json; these support the website demo and are not canonical SMALL v1 artifacts

V1 Enforcement Rules

The CLI enforces specific rules beyond schema validation:

Handoff: ReplayId Required

handoff.small.yml must include:

  • replayId.value - 64-character lowercase hex string (SHA-256)
  • replayId.source - Either auto (deterministic hash of intent + plan + constraints) or manual

Progress: Timestamp Rules

Progress entries must follow these rules:

  • Timestamps must be RFC3339Nano format with fractional seconds (e.g., 2025-01-15T10:00:00.123456789Z)
  • Timestamps must be strictly increasing across entries
  • Completed tasks must have matching progress entries with evidence populated

See How to Use SMALL for full enforcement documentation.

V2 additionally enforces identity consistency, causal graph integrity, session sequence continuity, mode policy, evidence availability, and complete expected-frontier conflict resolution. Use small check --strict as the final gate for either profile.