Vein Wire Format
Vein is LODE’s compact binary encoding. Every compiled LODE object is a Vein payload.
Binary Layout
Header
| Offset | Size | Field | Description |
|---|---|---|---|
| 0 | 1 | Magic[0] | 0x4C ('L') |
| 1 | 1 | Magic[1] | 0x44 ('D') |
| 2 | 1 | Version | Schema version (matches schema.version) |
| 3 | 1 | Count | Number 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:
| Offset | Size | Field | Description |
|---|---|---|---|
| 0 | 1 | Field ID | Numeric field identifier (1–255) |
| 1 | 1 | Type Tag | Wire type (see Type System) |
| 2 | 2 | Length | Data length in bytes (big-endian uint16) |
| 4 | N | Data | Type-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-veinByte 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:
| Format | Size |
|---|---|
| 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:
| Part | Layout |
|---|---|
| Header | magic 0x4C 0x45 ("LE"), version (1), count (1) |
| Field entry | field id (1), type tag (1), length (4, big-endian), data |
| Record / variant body | count (1), then field entries in declaration order |
string, enum | UTF-8 bytes |
bool | 0x00 / 0x01 |
int | 8 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.