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.lodeNaming Conventions
Schema files follow the pattern <name>-v<version>.lode:
name— lowercase, hyphen-separated description of the structureversion— matches theversionfield 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 }
]
}Named types v0.2
A schema may add a types object declaring records, variants and enums that fields refer to by name. Fields may use int, list<T> and map<string,T>. See Named Types.
pipeline-v1.lode
{
"schema": "lode",
"version": 1,
"name": "Pipeline",
"types": {
"Stage": { "kind": "enum", "values": ["build", "test", "ship"] },
"Step": {
"kind": "record",
"fields": [
{ "id": 1, "name": "stage", "type": "Stage" },
{ "id": 2, "name": "timeoutMs", "type": "int", "min": 0 }
]
}
},
"fields": [
{ "id": 1, "name": "name", "type": "string" },
{ "id": 2, "name": "steps", "type": "list<Step>" }
]
}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 or malformed type expression, or undeclared type name |
Field "a": "min" is only allowed on int fields | Bounds on a non-int field (v0.2) |
Type "Loop" has no finite value (unguarded recursion) | Recursive type with no way to stop (v0.2) |
Last updated on