Named Types
Since v0.2A schema may declare named types in a top-level types object. Names start with an upper-case letter ([A-Z][A-Za-z0-9_]*), so they never collide with built-in types. Any field, at any depth, may refer to any declared name.
Records
A record is a nested object. Its fields use the same shape as top-level fields: id (1–255, unique within the record), name, type, required.
{
"schema": "lode",
"version": 1,
"name": "Pipeline",
"types": {
"Step": {
"kind": "record",
"fields": [
{ "id": 1, "name": "tool", "type": "string" },
{ "id": 2, "name": "timeoutMs", "type": "int", "min": 0 },
{ "id": 3, "name": "note", "type": "string", "required": false }
]
}
},
"fields": [
{ "id": 1, "name": "name", "type": "string" },
{ "id": 2, "name": "steps", "type": "list<Step>" }
]
}Records are closed: a source object with a key that the record does not declare fails the type check.
Variants
A variant is a record in which exactly one field is present. The present field’s name is the tag. Variant fields never set required.
{
"schema": "lode",
"version": 1,
"name": "Filter",
"types": {
"Cond": {
"kind": "variant",
"fields": [
{ "id": 1, "name": "word", "type": "string" },
{ "id": 2, "name": "all", "type": "list<Cond>" },
{ "id": 3, "name": "any", "type": "list<Cond>" },
{ "id": 4, "name": "not", "type": "Cond" }
]
}
},
"fields": [{ "id": 1, "name": "when", "type": "Cond" }]
}Values look like { "word": "hello" } or { "all": [{ "word": "a" }, { "not": { "word": "b" } }] }.
Enums
An enum is a closed set of non-empty strings. The JSON value is the string itself.
{ "Mode": { "kind": "enum", "values": ["first_match", "max_weight", "lookup"] } }On the wire an enum travels as a string (tag 0x01). Decoding a value that the schema’s enum does not list is an error, so a reader never acts on a value it does not know.
Recursion
Types may refer to themselves or to each other, as Cond does above. Every type must have at least one finite value, so recursion has to pass through something that can stop it:
- an optional field,
- a
list<T>ormap<string,T>(which can be empty), - a variant with at least one non-recursive alternative.
{ "Loop": { "kind": "record", "fields": [{ "id": 1, "name": "next", "type": "Loop" }] } }is rejected: Type "Loop" has no finite value (unguarded recursion). Values are also limited to 64 levels of nesting.
Validation errors
| Error | Cause |
|---|---|
Type name "rule" must match ^[A-Z][A-Za-z0-9_]*$ | Lower-case or invalid type name |
Field "a": unknown type "Rule" | Reference to an undeclared type, or a malformed expression |
Type "E": duplicate enum value "x" | Repeated enum value |
Type "V": Field "x": variant fields cannot be required | required: true inside a variant |
Field "a": "min" is only allowed on int fields | Bounds on a non-int field |
Type "Loop" has no finite value (unguarded recursion) | See Recursion |