Spec
Every Colloq artifact has a machine-readable schema. These URLs are stable identifiers: a file's $id points here, so a validator can resolve it.
The JSON representation is an interchange and debugging format. It is not the canonical binary encoding, and it is not stable yet. The Rust checker enforces more than the schema does: it recomputes identities, verifies references and rejects a noncanonical transition table.
| Schema | What it describes |
|---|---|
| Conversation colloq-conversation-v0.schema.json |
The global conversation: roles, messages, choices, loops, cancellation and declared failures. This is the file you write. |
| Plan colloq-plan-v0.schema.json |
The compiled artifact: conversation identity, plan identity, one endpoint graph per role and the compact transition table. |
| Endpoint colloq-endpoint-v0.schema.json |
One role's projected state machine, as produced by colloq project. |
| Session preface colloq-session-v0.schema.json |
The preface two peers exchange before frame zero. A mismatch stops the session there. |
| Node identity colloq-node-v0.schema.json |
A local, secret-bearing Iroh identity. Written with mode 0600 and never shared. |
| Authorization colloq-authorization-v0.schema.json |
Which authenticated peer may take which role under which exact plan. No wildcards. |
| Graph colloq-graph-v0.schema.json |
The wider graph interchange experiment from RFC-0001. |
| Evidence colloq-evidence-v0.schema.json |
A reproducible correctness, security or performance result, tied to one revision. |
| Jev binding (optional) colloq-jev-v0.schema.json |
Binds one choice state to a typed model question, with an explicit threshold and escalation branch. |
Validate a file
pipx run check-jsonschema --schemafile \
https://colloq.dev/spec/colloq-conversation-v0.schema.json \
examples/route.colloqconv.json