A literal schema accepts exactly one value, and is written as that value: "draft", 1, true, null. A literal can be a string, an integer, a boolean, or null (the value union). It can never be a float, a map, or a list. A union of literals restricts a field to a fixed set of choices. Each choice can carry a description in the long form {value, description}:

Every signed blob type pins its type this way, and every RPC method schema pins its key. In TypeScript they become literal types (type: 'Change', 'draft' | 'published' | 'archived').

One rule governs the whole language: type names what a node is, and every other key refines what it names. If type names one of the nine kinds, the schema is grounded there. If it names another schema, the node is an include. With nothing else on the node, it becomes whatever that schema says. Add any refinement and it becomes an extension (below). The refinement can be structural (properties, values, items) or a leaf constraint (format, pattern, minLength, target, …), and the rule is the same. A node with type:"link" and a target is a typed link: a link whose target should match the named schema.

A node whose type names another schema and that also carries refinements extends what it names. The result is a subtype with the parent's fields plus new ones. The worked example is example/employee, which extends example/person:

Open example/employee in the schema explorer to see the merged result, with every field marked inherited or added.

The rules reuse existing keywords, so there is no extends keyword:

properties are merged: the parent's plus the extension's, and same-named keys override. Each is a property, so a field's required flag travels with it.

values / items on the extension override the parent's.

the result keeps the parent's kind and closedness. An employee must have name (required on the parent) and employeeId (required on the extension), may use any inherited field, and still rejects unknown keys.

A bare { "type": X }, where X names another schema and the node has nothing else, is a pure include. It becomes an extension only when a refinement is present. validate.mjs checks this (see the example/employee.schema checks and an extension can pin a field to a literal).

A struct names its fields in properties, one property per field. properties[name] is {value, required?, description?}: the schema the field's value must match, whether a value must include the field, and what the field is for. A struct is closed, so keys not listed are rejected. Add values and it is open: extra keys are allowed as long as their values match the values schema. A map has no named fields, and every key's value matches values. So:

struct with properties and no values is a closed struct (fixed field set)

map with values is a map (uniform value type, any keys)

struct with both has known fields in properties, and everything else must match values

a bare map or struct accepts any map

Closedness lets the meta-schema reject malformed schemas with extra keys (see below).

Beyond the kind, a schema can narrow the values a leaf accepts. Every constraint is optional, and a missing constraint means no limit. validate.mjs checks all of them (see its Value constraints section), and example/constrained uses them together.

These constraints come from the "Seed Blob Schema v1" dialect. validate() reports each violation as an error string, for example $.username: expected at least 3 characters. The exported validateAdvisory() wrapper runs the same checks and is documented as warn, don't block: callers show its result as warnings and do not reject the write.

anyOf lists alternative schemas, and a value is valid if it matches any of them. It is the language's one composite construct. It makes the meta-schema a discriminated union: a value is one of a fixed set of shapes, told apart by a discriminant (here, the type tag).

The schema language has both kinds of generic.

Applied generics supply a type parameter directly. items and values give them with no extra keys:

list + items = List<T>, where items is T

map + values = Map<V>, where values is V

So {"Apples":5,"Oranges":3} is Map<Integer>, written example/counts: { "type":"map", "values":{ "type":"integer" } }. This nests to any depth.

Generic abstraction defines a reusable parameterized type to instantiate later. It uses three keys:

The parameter passes through references: each level passes it down with args, so binding it at the top substitutes it everywhere. The worked example is change, a Change<Block> whose Block parameter flows through change, change/body, change/op and change/op/replace-block. Its instantiation example/myapp-change is Change<example/app-block>, which validates blocks strictly deep inside the op stack (see the Generics: Change<Block> checks in validate.mjs). A generic used bare falls back to its parameter defaults, so the common case needs no args.

schema is a discriminated union of nine variants, the nine map shapes a schema can take, plus the four bare kinds a literal can be. This makes it much stricter than a loose map with optional keys:

Each variant is a closed map, so a nonsense schema like {type:"string", items:{…}} matches none of them. The closed schema/scalar-schema rejects the stray items key, and the type tag rules out the others. Run it:

The loop still closes

validate.mjs validates schema against itself and every variant against the union. It also confirms the union rejects malformed schemas. You can run it:

If you extend the vocabulary, run it again. If the union can no longer describe its own new shape, the loop is broken and the check fails.