Schema Files

LODE schemas are stored in .lode files — plain JSON with the "schema": "lode" discriminator.

File Extension

The conventional extension is .lode. The lodec compiler accepts any file path but the convention aids tooling and discovery.


model-layer-v1.lode
prompt-contract-v1.lode
service-config-v2.lode

Naming Conventions

Schema files follow the pattern <name>-v<version>.lode:

name — lowercase, hyphen-separated description of the structure
version — matches the version field inside the schema

Complete Schema Example

model-layer-v1.lode


{
  "schema": "lode",
  "version": 1,
  "name": "ModelLayer",
  "fields": [
    { "id": 1, "name": "name",         "type": "string",             "required": true },
    { "id": 2, "name": "isDefault",    "type": "bool",               "required": true },
    { "id": 3, "name": "models",       "type": "string[]",           "required": true },
    { "id": 4, "name": "defaultModel", "type": "string",             "required": true },
    { "id": 5, "name": "defaults",     "type": "map<string,string>", "required": false }
  ]
}

Loading Schemas


import { loadLode } from "@stacknet/lode";
 
// From file path
const schema = loadLode("./schemas/model-layer-v1.lode");
 
// From inline object
const schema = loadLode({
  schema: "lode",
  version: 1,
  name: "Minimal",
  fields: [
    { id: 1, name: "value", type: "string", required: true },
  ],
});

Validation Errors

loadLode throws descriptive errors for invalid schemas:

Error	Cause
`Invalid schema type: expected "lode", got "proto"`	Wrong discriminator
`Invalid schema version: 0`	Version must be ≥ 1
`Schema must have a non-empty name`	Missing or empty `name`
`Schema must have at least one field`	Empty fields array
`Field 0: id must be 1-255, got 0`	Field ID out of range
`Duplicate field id: 3`	Two fields share the same ID
`Duplicate field name: "title"`	Two fields share the same name
`Field "data": unknown type "bytes"`	Unsupported type string