JSON Schemas
Schemas are provided as JSON Schema (Draft 2020-12). Each implementation must validate against these schemas. The JSON representation of the wire format is normative; future binary codecs encode the same shapes.
| Schema | Layer |
|---|---|
snapshot.json | IPC — Snapshot message |
delta.json | IPC — Delta message (all 7 DeltaOp variants) |
ffi.json | Cross-language FFI boundary |
signaling.json | Signaling (WebSocket) |
distributed.json | Distributed (CRDT) |
snapshot.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://lazily.dev/schemas/snapshot.json",
"title": "Snapshot",
"description": "Full graph state message for lazily-IPC",
"type": "object",
"properties": {
"type": { "const": "snapshot" },
"epoch": { "type": "integer", "minimum": 0, "description": "Current IPC epoch" },
"nodes": {
"type": "array",
"items": { "$ref": "#/$defs/NodeSnapshot" },
"description": "All serialized nodes"
},
"edges": {
"type": "array",
"items": { "$ref": "#/$defs/EdgeSnapshot" },
"description": "Dependency edges"
},
"roots": {
"type": "array",
"items": { "type": "integer", "minimum": 0 },
"description": "Cell and source slot IDs"
}
},
"required": ["type", "epoch", "nodes", "edges", "roots"],
"additionalProperties": false,
"$defs": {
"NodeSnapshot": {
"type": "object",
"properties": {
"slot_id": { "type": "integer", "minimum": 0 },
"type_tag": { "type": "string", "description": "Stable cross-process type key" },
"state": {
"type": "string",
"enum": ["resolved", "dirty", "unset"],
"description": "Node state"
},
"payload": {
"type": ["string", "null"],
"contentEncoding": "base64",
"description": "Serialized value (null if unset)"
}
},
"required": ["slot_id", "type_tag", "state"],
"additionalProperties": false
},
"EdgeSnapshot": {
"type": "object",
"properties": {
"dependent": { "type": "integer", "minimum": 0 },
"dependency": { "type": "integer", "minimum": 0 }
},
"required": ["dependent", "dependency"],
"additionalProperties": false
}
}
}
delta.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://lazily.dev/schemas/delta.json",
"title": "Delta",
"description": "Incremental change set for lazily-IPC",
"type": "object",
"properties": {
"type": { "const": "delta" },
"base_epoch": {
"type": "integer",
"minimum": 0,
"description": "Epoch this delta applies to"
},
"epoch": {
"type": "integer",
"minimum": 0,
"description": "New epoch (must equal base_epoch + 1)"
},
"ops": {
"type": "array",
"items": { "$ref": "#/$defs/DeltaOp" },
"description": "Ordered operations"
}
},
"required": ["type", "base_epoch", "epoch", "ops"],
"additionalProperties": false,
"$defs": {
"DeltaOp": {
"oneOf": [
{
"type": "object",
"title": "CellSet",
"properties": {
"op": { "const": "cell_set" },
"slot_id": { "type": "integer", "minimum": 0 },
"payload": {
"type": "string",
"contentEncoding": "base64",
"description": "Serialized cell value"
}
},
"required": ["op", "slot_id", "payload"],
"additionalProperties": false
},
{
"type": "object",
"title": "SlotValue",
"properties": {
"op": { "const": "slot_value" },
"slot_id": { "type": "integer", "minimum": 0 },
"payload": {
"type": "string",
"contentEncoding": "base64",
"description": "Serialized slot value"
}
},
"required": ["op", "slot_id", "payload"],
"additionalProperties": false
},
{
"type": "object",
"title": "Invalidate",
"properties": {
"op": { "const": "invalidate" },
"slot_id": { "type": "integer", "minimum": 0 }
},
"required": ["op", "slot_id"],
"additionalProperties": false
},
{
"type": "object",
"title": "NodeAdd",
"properties": {
"op": { "const": "node_add" },
"slot_id": { "type": "integer", "minimum": 0 },
"type_tag": { "type": "string" },
"payload": {
"type": ["string", "null"],
"contentEncoding": "base64"
}
},
"required": ["op", "slot_id", "type_tag"],
"additionalProperties": false
},
{
"type": "object",
"title": "NodeRemove",
"properties": {
"op": { "const": "node_remove" },
"slot_id": { "type": "integer", "minimum": 0 }
},
"required": ["op", "slot_id"],
"additionalProperties": false
},
{
"type": "object",
"title": "EdgeAdd",
"properties": {
"op": { "const": "edge_add" },
"dependent": { "type": "integer", "minimum": 0 },
"dependency": { "type": "integer", "minimum": 0 }
},
"required": ["op", "dependent", "dependency"],
"additionalProperties": false
},
{
"type": "object",
"title": "EdgeRemove",
"properties": {
"op": { "const": "edge_remove" },
"dependent": { "type": "integer", "minimum": 0 },
"dependency": { "type": "integer", "minimum": 0 }
},
"required": ["op", "dependent", "dependency"],
"additionalProperties": false
}
]
}
}
}
ffi.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://lazily.dev/schemas/ffi.json",
"title": "FFI Types",
"description": "C ABI types for the lazily FFI boundary",
"$defs": {
"LazilyFfiBytes": {
"type": "object",
"description": "Owned byte buffer crossing the FFI boundary",
"properties": {
"ptr": { "type": "integer", "minimum": 0, "description": "Pointer to byte buffer" },
"len": { "type": "integer", "minimum": 0, "description": "Buffer length in bytes" }
},
"required": ["ptr", "len"],
"additionalProperties": false
},
"LazilyFfiStatus": {
"type": "integer",
"enum": [0, 1, 2, 3, 4, 5],
"description": "FFI operation status code",
"oneOf": [
{ "const": 0, "title": "Ok" },
{ "const": 1, "title": "Empty" },
{ "const": 2, "title": "NullPointer" },
{ "const": 3, "title": "InvalidMessage" },
{ "const": 4, "title": "EncodeFailed" },
{ "const": 5, "title": "Panic" }
]
},
"LazilyFfiMessageKind": {
"type": "integer",
"enum": [0, 1, 2],
"description": "IPC message kind discriminator",
"oneOf": [
{ "const": 0, "title": "Unknown" },
{ "const": 1, "title": "Snapshot" },
{ "const": 2, "title": "Delta" }
]
}
}
}
signaling.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://lazily.dev/schemas/signaling.json",
"title": "Signaling Protocol",
"description": "WebSocket signaling frames for lazily peer discovery",
"$comment": "Validates both client→server and server→client frames",
"oneOf": [
{
"title": "ClientMessage",
"oneOf": [
{
"type": "object",
"title": "Join",
"properties": {
"type": { "const": "join" },
"peer": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
"capabilities": { "type": "array", "items": { "type": "string" } }
},
"required": ["type", "peer"],
"additionalProperties": false
},
{
"type": "object",
"title": "Offer",
"properties": {
"type": { "const": "offer" },
"to": { "type": "integer", "minimum": 0 },
"sdp": { "type": "string" }
},
"required": ["type", "to", "sdp"],
"additionalProperties": false
},
{
"type": "object",
"title": "Answer",
"properties": {
"type": { "const": "answer" },
"to": { "type": "integer", "minimum": 0 },
"sdp": { "type": "string" }
},
"required": ["type", "to", "sdp"],
"additionalProperties": false
},
{
"type": "object",
"title": "Ice",
"properties": {
"type": { "const": "ice" },
"to": { "type": "integer", "minimum": 0 },
"candidate": { "type": "string" }
},
"required": ["type", "to", "candidate"],
"additionalProperties": false
},
{
"type": "object",
"title": "Relay",
"properties": {
"type": { "const": "relay" },
"to": { "type": "integer", "minimum": 0 },
"payload": {}
},
"required": ["type", "to", "payload"],
"additionalProperties": false
},
{
"type": "object",
"title": "Leave",
"properties": {
"type": { "const": "leave" }
},
"required": ["type"],
"additionalProperties": false
}
]
},
{
"title": "ServerMessage",
"oneOf": [
{
"type": "object",
"title": "Welcome",
"properties": {
"type": { "const": "welcome" },
"peer": { "type": "integer", "minimum": 0 },
"peers": {
"type": "array",
"items": { "type": "integer", "minimum": 0 }
}
},
"required": ["type", "peer", "peers"],
"additionalProperties": false
},
{
"type": "object",
"title": "PeerJoined",
"properties": {
"type": { "const": "peer-joined" },
"peer": { "type": "integer", "minimum": 0 }
},
"required": ["type", "peer"],
"additionalProperties": false
},
{
"type": "object",
"title": "PeerLeft",
"properties": {
"type": { "const": "peer-left" },
"peer": { "type": "integer", "minimum": 0 }
},
"required": ["type", "peer"],
"additionalProperties": false
},
{
"type": "object",
"title": "ForwardedOffer",
"properties": {
"type": { "const": "offer" },
"from": { "type": "integer", "minimum": 0 },
"sdp": { "type": "string" }
},
"required": ["type", "from", "sdp"],
"additionalProperties": false
},
{
"type": "object",
"title": "ForwardedAnswer",
"properties": {
"type": { "const": "answer" },
"from": { "type": "integer", "minimum": 0 },
"sdp": { "type": "string" }
},
"required": ["type", "from", "sdp"],
"additionalProperties": false
},
{
"type": "object",
"title": "ForwardedIce",
"properties": {
"type": { "const": "ice" },
"from": { "type": "integer", "minimum": 0 },
"candidate": { "type": "string" }
},
"required": ["type", "from", "candidate"],
"additionalProperties": false
},
{
"type": "object",
"title": "ForwardedRelay",
"properties": {
"type": { "const": "relay" },
"from": { "type": "integer", "minimum": 0 },
"payload": {}
},
"required": ["type", "from", "payload"],
"additionalProperties": false
},
{
"type": "object",
"title": "Error",
"properties": {
"type": { "const": "error" },
"code": { "type": "string" },
"message": { "type": "string" }
},
"required": ["type", "code", "message"],
"additionalProperties": false
}
]
}
]
}
distributed.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://lazily.dev/schemas/distributed.json",
"title": "Distributed Types",
"description": "CRDT and permission types for lazily-distributed",
"$defs": {
"PeerId": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Wire-stable peer identifier (u64, must stay ≤ Number.MAX_SAFE_INTEGER)"
},
"NodeId": {
"type": "integer",
"minimum": 0,
"description": "Wire-stable node identifier (decoupled from internal SlotId)"
},
"OpKind": {
"type": "string",
"enum": ["read", "write", "trigger_effect"],
"description": "Permission-gated operation kind"
},
"RemoteOp": {
"type": "object",
"description": "Gated, serializable unit a peer requests",
"properties": {
"kind": { "$ref": "#/$defs/OpKind" },
"node": { "$ref": "#/$defs/NodeId" }
},
"required": ["kind", "node"],
"additionalProperties": false
},
"CellRegisterType": {
"type": "string",
"enum": ["lww", "mv", "pn-counter"],
"description": "CRDT register type for a replicated cell"
},
"HLCStamp": {
"type": "object",
"description": "Hybrid logical clock stamp for causal ordering",
"properties": {
"wall_time": {
"type": "integer",
"minimum": 0,
"description": "Wall-clock microseconds since epoch"
},
"logical": {
"type": "integer",
"minimum": 0,
"description": "Logical counter for causal tiebreak"
},
"peer_id": { "$ref": "#/$defs/PeerId" }
},
"required": ["wall_time", "logical", "peer_id"],
"additionalProperties": false
}
}
}