Skip to Content
DocsLanguageVein Wire Format

Vein Wire Format

Vein is LODE’s compact binary encoding. Every compiled LODE object is a Vein payload.

Binary Layout

OffsetSizeFieldDescription
01Magic[0]0x4C ('L')
11Magic[1]0x44 ('D')
21VersionSchema version (matches schema.version)
31CountNumber of encoded fields

The magic bytes LD identify the payload as a Vein binary. Any file or buffer starting with 0x4C44 is a candidate Vein payload.

Field Entry

Each field is encoded as:

OffsetSizeFieldDescription
01Field IDNumeric field identifier (1–255)
11Type TagWire type (see Type System)
22LengthData length in bytes (big-endian uint16)
4NDataType-specific encoded value

The maximum data length per field is 65,535 bytes (2^16 - 1).

Content Type

Vein binaries are served with the MIME type:

Content-Type: application/x-vein

Byte Order

All multi-byte integers in Vein are big-endian (network byte order). This includes:

  • Field data length (2 bytes)
  • String array item count (2 bytes)
  • String array item lengths (2 bytes each)
  • Map entry count (2 bytes)
  • Map key/value lengths (2 bytes each)

Size Characteristics

For a typical model layer with 5 fields:

FormatSize
JSON (pretty)~350 bytes
JSON (compact)~220 bytes
Vein~90 bytes

The Vein encoding is roughly 60% smaller than compact JSON for structured data with string fields.

Extended Vein v0.2

A schema that uses only the v0.1 types (string, bool, string[], map<string,string>) and declares no types always compiles to the v0.1 layout above, byte for byte. A schema that uses any v0.2 type compiles to extended Vein:

PartLayout
Headermagic 0x4C 0x45 ("LE"), version (1), count (1)
Field entryfield id (1), type tag (1), length (4, big-endian), data
Record / variant bodycount (1), then field entries in declaration order
string, enumUTF-8 bytes
bool0x00 / 0x01
int8 bytes, big-endian two’s complement
string[]count (4), then per item: length (4) + UTF-8; items sorted
list<T>count (4), then per item: length (4) + item data; source order
map<string,T>count (4), then per entry: key length (4) + key + value length (4) + value data; keys sorted

Extended Vein is canonical: logically equal values encode to identical bytes. All lengths are 32-bit, so a single field can hold up to 4 GiB.

The different magic makes a v0.1 decoder reject extended payloads (Invalid magic) instead of misreading them. Decoders skip unknown field ids at any depth (forward compatibility), reject a known field whose tag does not match the schema, reject trailing bytes, and reject enum values the schema does not list.

v0.1 Vein limits each field, item, key and value to 65,535 bytes. Since v0.2 the encoder throws when a value is larger; v0.1 wrote a truncated length, producing a corrupt payload.

Last updated on