Skip to Content
DocsLanguageNamed Types

Named Types

Since v0.2

A 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> or map<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

ErrorCause
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 requiredrequired: true inside a variant
Field "a": "min" is only allowed on int fieldsBounds on a non-int field
Type "Loop" has no finite value (unguarded recursion)See Recursion
Last updated on