Overview

How Internet Object schemas describe the shape of data, and the pieces that make them up.

An Internet Object schema describes the shape of the objects in a document: their members, the type of each value, and the constraints each value must satisfy. A schema is written in the same object syntax as the data it validates, so it is compact, readable, and easy to author by hand.

Schema and data share one syntax. Unlike map-based schema languages (JSON Schema, XML Schema), an IO schema looks like the object it validates. There is no second grammar to learn.

A schema is normally declared once in the header — as the default $schema or as a reusable $ reference — and applied to every record in the data section. Validating a value against a schema either succeeds or produces a stable error code.

The shape of an object

A schema is a comma-separated list of members. In its simplest form it is just a list of keys; each value then has the any type:

name, age, address
---
John, 30, { Main St, NYC }

Give a member a type by writing key: type:

name: string, age: int, isActive: bool
---
John, 30, T

Add constraints by replacing the bare type with a MemberDef — a small object whose first value is the type and whose remaining entries are constraints:

score: { int, min: 0, max: 100 }
---
85

A value outside the constraint fails validation with a stable code:

score: { int, min: 0, max: 100 }
---
150          # ✗ mismatched-max — score is above max

Members nest: a member's type can itself be an object schema or an array:

name: string, address: { street: string, city: string }
---
John, { Main St, NYC }

The building blocks

A schema is assembled from a few orthogonal pieces. Each has its own reference page:

Piece	What it does	Reference
MemberDef	One member: a type plus its constraints	MemberDef
Data types	The base types and built-in shortcuts (string, int, email, …)	Schema Data Types
TypeDef	The fixed set of options each type accepts	TypeDef
Optional, nullable & defaults	?, *, and default values	MemberDef
Open & dynamic schemas	Allowing extra members with * and *: type	Open & Dynamic Schemas
References	Reusable schemas and types ($name)	Schema References
Union types	A value matching one of several types (anyOf)	Union Types
Composition & reuse	Building large schemas from small ones	Composition & Reuse

The exact placement rules — open vs. closed objects, keyed vs. positional members, and how the default $schema is chosen — are covered in Schema Representation.

Optional, nullable, and default members

A member name can carry a marker that changes how a missing or null value is treated. These markers are first-class schema features, not informal conventions: a conformant validator MUST honor them.

• Optional (?) — the member MAY be omitted from the data.

• Nullable (*) — the member MAY be null (N).

• Both (?*) — the member may be omitted or null.

• Default — the second value in a MemberDef supplies a value to use when the member is omitted (equivalently, the keyed default: option).

~ $schema: { name: string, email?: string, nickname?*: string, role?: { string, guest } }
---
~ John                          # email & nickname omitted, role defaults to "guest"
~ Mary, [email protected], N, admin    # nickname is null, role is "admin"

See MemberDef for the full resolution rules and Open & Dynamic Schemas for accepting members beyond those listed.

Schema grammar

The shape of a member, informally:

schema    = member ( "," member )*
member    = openMember | [ key modifier? ":" ] typeOrDef
openMember = "*" [ ":" typeOrDef ]
modifier  = "?" | "*" | "?*"
typeOrDef = typeName | ref | memberDef | "{" schema "}" | "[" typeOrDef "]"
memberDef = "{" ( typeName | ref ) ( "," constraint )* "}"
ref       = "$" name

The complete, normative grammar for documents and schemas is in the Formal Grammar appendix.

A complete example

A header defines a reusable $address and a default $schema; the data section is validated against it:

~ $address: { street: string, city: string, zip?: int }
~ $schema: {
    name: string,
    age?: int,
    email: { string, pattern: "^[^@]+@[^@]+$" },
    isActive: bool,
    address?: $address
}
---
~ John Doe, 30, [email protected], T, { Bond Street, New York }
~ Jane Doe, 28, [email protected], F

Both records validate: John Doe supplies an address; Jane Doe omits the optional address.

See Also

• Schema Representation — open/closed, keyed/positional, default schema

• Schema Data Types — the base types and shortcuts

• MemberDef — types, constraints, optional/nullable/default

• Schema References — reusable $ schemas and types

• Error Model — the validation error catalogue

• JSON Compatibility — mapping to and from JSON Schema