Type System

Primitive types

Composite types

enum

status: enum["pending", "approved", "rejected"]

Accepts string values only and cannot be empty. The JSON Schema counterpart is { "type": "string", "enum": [...] }. A value outside the list produces X.y must be one of these values: ….

Array

tags: string[]        // unbounded list of strings
items: LineItem[]      // list of nested schemas
grid: int[][]         // nested array

JSON Schema: { "type": "array", "items": { … } }. Each element is validated separately and the index appears in the error message: Invoice.items[2].amount missing.

An element is reached with [] — rows[0], rows[i].customer.name — and the same form on the left of an = writes one. Reading past the end is a named error, never a quiet null: xs[5] is out of bounds (length 2). Writing past the end is refused too, because a list does not grow by being indexed. The full table of boundary cases is on the language page.

map<T> / record<T>

metrics: map<float>       // { "score": 0.95, "confidence": 0.8 }
labels: record<string>    // record is an alias for map

An object with dynamic keys. JSON Schema: { "type": "object", "additionalProperties": { … } }. Keys are free; the type of the values is validated.

A value is reached with m["key"], and writing to a key that is not there creates it. Reading one that is not there does not return null — a missing key is a named error: m["missing"] is not present. That is a statement about the type and not merely about the runtime: map<T> holds T, not T | null, so a lookup is not a place where null can enter the program. A key you are not sure about has to be checked before it is read:

import col from "std/collections"

agent Reader {
  fn read(labels: map<string>, key: string) -> Out {
    if contains(col.keys(labels), key) {
      return { value: labels[key] }
    }
    return { value: "unknown" }
  }
}

The full table of indexing boundary cases — lists as well as maps, reads as well as writes — is on the language page.

schema MetaEntry {
  key: string
  value: string
}

// inside InvoiceExtract:
meta: MetaEntry[] @desc("Anything that does not fit the schema fields")

json<T>

import json from "std/json"

schema Envelope {
  raw: string           // JSON text
  data: any              // parsed, unvalidated value
  payload: json<Payload>    // parsed AND validated against Payload
}

Tuple

coordinate: [float, float]      // exactly two elements, positional

A fixed-length, positionally typed array. Validation checks the element count and the type at each position. It must contain at least one comma ([float] is not a tuple).

Error: @range can only be used on numeric fields or numeric arrays.

schema Point {
  lat: float [-90..90]
  lon: float [-180..180]
}

Schema reference

schema Address {
  city: string
}

schema Customer {
  address: Address      // nested object
  history: Address[]    // list of nested objects
}

Emitted as { "$ref": "#/$defs/Address" } in JSON Schema; the definition appears once under $defs.

Parametric schema — Name<T>

schema LineItem {
  sku: string
  amount: float
}

schema Page<T> {
  items: T[]
  total: int
}

schema Report {
  page: Page<LineItem>
}

A schema may declare type parameters. Inside the body the parameter reads like any other type name, and every use site supplies a concrete argument: Page<LineItem>, Page<Customer>.

Page<LineItem> is expanded while the file is parsed. The parser copies the body of Page, puts LineItem where T stood, and registers the result as an ordinary schema named Page_LineItem. Nothing past that point knows a parameter was ever involved — JSON Schema generation, validation, $defs, where, when, @desc and std/schema reflection all run on the expanded schema exactly as they would on one typed out by hand, and no genericity reaches the provider.

The expanded name is the name you see. It is the $defs key, it is what schema.name(…) returns, and it is the prefix of a validation error raised against that schema:

Page_LineItem.items[0].amount missing.

Every position that accepts a schema name

The carrying case is the one that matters: a producing method returns Page<LineItem> and a consuming method takes the same thing as a parameter, so the wrapper never has to be unpacked by hand at the boundary between them.

Several parameters, nesting, primitives

schema LineItem {
  sku: string
}

schema Customer {
  name: string
}

schema Page<T> {
  items: T[]
}

schema Pair<A, B> {
  left: A
  right: B
}

schema Box<T> {
  value: T
}

schema Envelope<T> {
  payload: T
  trace_id: string
}

schema Deep<T> {
  inner: Box<T>
}

schema Catalogue {
  pair: Pair<LineItem, Customer>
  pages: Page<Envelope<LineItem>>
  count: Box<int>
  deep: Deep<LineItem>
}

A type argument may be a primitive (Box<int>), a schema, or another instantiation (Page<Envelope<LineItem>>), and a generic body may reference a second generic — Deep<T> above holds a Box<T>. Each distinct instantiation is expanded once, under a name assembled from its arguments: Pair_LineItem_Customer, Page_Envelope_LineItem, Box_int, Deep_LineItem. Give a generic the wrong number of arguments and the count is named back at you: Generic schema 'Pair' expects 2 type argument(s), got 1.

What a parameter may stand for, and what may be passed to it

Both sides of the substitution are wider than the examples above suggest. A parameter is not restricted to a bare field: it substitutes into every composite position, so one declaration covers the array, the map, the nullable, the tuple and the raw-JSON form of the same type.

schema LineItem {
  sku: string
}

schema Multi<T> {
  one: T
  many: T[]
  lookup: map<T>
  maybe: T | null
  pair: [T, string]
  raw: json<T>
}

schema Catalogue {
  rows: Multi<LineItem>
}

And the argument does not have to be a schema name. Anything the type grammar can write may be passed, each one expanding under a name built from the argument's own written form:

Type parameters are a schema construct only. Writing them on any other block does not give you a generic agent or a generic function.

import "./base.luma"      // Taban, Ek, Zarf<T>

schema Birlesik = Taban + Ek        // composition
schema Kullanim = Zarf<Ic>          // generic alias
schema Sonuc { kutu: Zarf<Ic> }     // generic field type

Error: Schema definition 'schema K = …' matches no known form: use 'A + B' composition, 'A | B tagged by field' union, or a 'Template<Args>' generic alias.

Error: Unknown type argument schema 'Missing' for generic 'Page'.
Error: Generic schema cycle found: Tree<int> -> Tree<int>.
Error: Tagged unions cannot use generic schema members: Document.
Error: Tagged union 'Document' must contain at least two members.

Error: 'Page' variable is not defined yet.

Union and nullable

note: string | null
value: int | float | null
flexible: string | int

A union is written with | and produces anyOf in JSON Schema. During validation the members are tried in order; if none match, every sub-error is combined into one report:

Customer.tax_id does not match any union type: Customer.tax_id must be a string. | Customer.tax_id must be null.

Tagged union — tagged by

A | written inside a field type is an untagged union. A schema declared with = and tagged by is a different thing: a sum type. A value is one member or the other, and a tag field says which.

schema Invoice {
  date: string
  total: float
  invoice_number?: string
}

schema Receipt {
  date: string
  total: float
  reference?: string
}

schema Document = Invoice | Receipt tagged by kind

The declaration is a single line with no body, and it needs at least two members that are already-defined schemas — an unknown member stops the parser with Tagged union 'Document' member schema 'Voucher' was not found. From there the two forms are resolved by entirely different rules:

The tag is injected, not declared

tagged by kind adds the kind field to every member, and its value is that member's schema name: "Invoice", "Receipt". You never write the field yourself, and the members are not altered — Invoice on its own, as a field type, a parameter or an ask output, still has exactly the fields it declares and no kind among them.

Because the tag is injected, a member that declares it too is a conflict, and the parser refuses the whole program:

Error: Tagged union 'Document' discriminator 'kind' conflicts with member schema 'Invoice'.

Reading the tag

The tag is read before anything else. It selects one member and the rest of the value is validated against that member alone, so the branch is deterministic even when every member would have fitted:

agent Router {
  fn route(document: Document) -> Result {
    match document {
      case Invoice invoice { return { branch: "Invoice" } }
      case Receipt receipt { return { branch: "Receipt" } }
    }
  }
}

router = Router()
out = router.route({ kind: "Receipt", date: "2026-02-01", total: 42.0 })

A value whose tag is missing — or is not a string — never reaches a member, and neither does one whose tag names a schema outside the union:

Router.route.document.kind must identify a tagged union member.
Router.route.document.kind has unknown tagged union member 'Voucher'.

The prefix is the path of the value being validated; here, the document parameter of Router.route.

Optional / nullable matrix

This table is the distinction most often confused in Luma:

// The preferred pattern in invoice extraction:
invoice_number: string | null @desc("Invoice number")
due_date: string | null @desc("Payment due date")
items: InvoiceItem[] @desc("All line items; empty list if none")

Arrays and null

Collection annotations such as @minItems and @unique applied to a nullable array only run when the value really is an array; they are skipped when it is null.

Size and range shorthands

schema Answer {
  title: string
  paragraphs: string[2]           // exactly two paragraphs
  people: Person[1..3]        // 1-3 people
  scores: float[1..3] [0..100]
  confidence: float [0..1]        // a single number between 0 and 1
}

JSON Schema mapping

The schema below and the real JSON Schema it produces, taken from schema.toJsonSchema(...):

schema Address {
  city: string
}

schema Customer @desc("Invoice customer") {
  name: string @length(2, 40) @title("Full name") @example("Ada Byron")
  tax_id: string | null @length(10) @desc("Tax identification number")
  email?: string @fmt("email") @alias("e_mail")
  score: float [0..100]
  tags: string[] @minItems(1) @unique @contains("vip")
  kind: enum["individual", "company"]
  metrics: map<float>
  address: Address
  active: bool @default(true)

  where score >= 0
  when kind == "company" require [tax_id]
}

{
  "type": "object",
  "description": "Invoice customer",
  "properties": {
    "name": { "type": "string", "minLength": 2, "maxLength": 40,
              "examples": ["Ada Byron"], "title": "Full name" },
    "tax_id": { "anyOf": [ { "type": "string", "minLength": 10, "maxLength": 10 },
                           { "type": "null" } ],
                "description": "Tax identification number" },
    "email": { "type": "string", "format": "email",
               "x-luma-aliases": ["e_mail"] },
    "score": { "type": "number", "minimum": 0, "maximum": 100 },
    "tags": { "type": "array", "items": { "type": "string" },
              "minItems": 1, "uniqueItems": true,
              "contains": { "const": "vip" } },
    "kind": { "type": "string", "enum": ["individual", "company"] },
    "metrics": { "type": "object", "additionalProperties": { "type": "number" } },
    "address": { "$ref": "#/$defs/Address" },
    "active": { "type": "boolean", "default": true }
  },
  "required": ["name", "tax_id", "score", "tags", "kind", "metrics", "address"],
  "additionalProperties": false,
  "allOf": [
    { "if":   { "properties": { "kind": { "const": "company" } } },
      "then": { "allOf": [ { "required": ["tax_id"] } ] } }
  ],
  "x-luma-where": [ { "expression": "score >= 0" } ],
  "x-luma-conditionals": [ … ]
}

Points worth noting

• Given a single argument, @length(10) sets both minLength and maxLength to 10 — that is, exactly 10 characters.
• On a union field, annotations are applied to the matching branch: the length constraint goes to the string branch and the null branch is left untouched.
• @default and ? both keep the field out of required.
• The root object always carries additionalProperties: false — the model cannot produce a field outside the schema.
• where and conditional rules travel as x-luma-* extensions; gateways ignore them and Luma performs the validation locally.

A tagged union in JSON Schema

Each member is emitted in full inside anyOf, and the tag is pinned to a const in every one of them and joins that member's required list. That const is what does the discriminating: a document is a Receipt because its kind can only be "Receipt" there. This is the real dump for the Document union above:

{
  "anyOf": [
    { "type": "object",
      "properties": {
        "date": { "type": "string" },
        "total": { "type": "number" },
        "invoice_number": { "type": "string" },
        "kind": { "type": "string", "const": "Invoice" }
      },
      "required": ["date", "total", "kind"],
      "additionalProperties": false },
    { "type": "object",
      "properties": {
        "date": { "type": "string" },
        "total": { "type": "number" },
        "reference": { "type": "string" },
        "kind": { "type": "string", "const": "Receipt" }
      },
      "required": ["date", "total", "kind"],
      "additionalProperties": false }
  ]
}

The untagged form carries none of that. A doc: Invoice | Receipt field becomes a plain list of references, and nothing in the schema tells the gateway — or a validator — which member was meant:

"doc": { "anyOf": [ { "$ref": "#/$defs/Invoice" }, { "$ref": "#/$defs/Receipt" } ] }

A parametric schema in JSON Schema

There is nothing special to see, and that is the whole point of expanding at parse time. Below is the real request body for an ask whose output type is Page<LineItem>; the model is handed a narrow object schema and never learns that a parameter was written:

{
  "type": "object",
  "properties": {
    "items": { "type": "array", "items": { "$ref": "#/$defs/LineItem" } },
    "total": { "type": "integer" }
  },
  "required": ["items", "total"],
  "additionalProperties": false,
  "$defs": {
    "Page_LineItem": {
      "type": "object",
      "properties": {
        "items": { "type": "array", "items": { "$ref": "#/$defs/LineItem" } },
        "total": { "type": "integer" }
      },
      "required": ["items", "total"],
      "additionalProperties": false
    },
    "LineItem": {
      "type": "object",
      "properties": {
        "sku": { "type": "string" },
        "amount": { "type": "number" }
      },
      "required": ["sku", "amount"],
      "additionalProperties": false
    }
  }
}

$defs holds only what this root schema reaches: the expansion itself and the LineItem it refers to. A Page<Customer> declared elsewhere in the same program, on a path no request touches, is absent from the body — an expansion is not a request cost until something reachable points at it. That is why parametric schemas were held back until $defs pruning existed: without pruning, one wrapper multiplied by every payload type would be paid for on every single call.

Complete mapping table

Which type when?

schema Record {
  id: string
  amount: float | null
  status: enum["open", "closed"]
  items: LineItem[]
  meta: MetaEntry[]
}

schema Record {
  id: any             // no validation
  amount: float           // no "not found" path
  status: string          // free text
  items?: LineItem[]      // the model may skip it
  meta: map<any>        // may be rejected in strict mode
}

Choosing a type for a query row

Since v0.4.0 the same vocabulary also types data that no model produced. A query returns Schema[] and validates it row by row; a parallel over validates each element result against its declared element schema. Both name the position that failed — Orders.row[0].amount must be a number., classified[2].band must be one of these values: … — so the table above still applies, but the reasoning behind it changes.

A model output type is a negotiation: you are shaping what the model is allowed to say, and every choice trades strictness against the model's ability to comply. A row type is a description: the shape is already fixed by the table, nothing is negotiating with you, and the only question is whether the declaration matches what the bridge hands back. Nothing is coerced on the way in — the declared type is checked against the JS value the driver produced — so a column that arrives as a Date does not satisfy string, and the fix belongs in the SQL or in the bridge rather than in a looser type.