On a content-addressed network, a piece of data is a hash and some bytes. The hash proves which bytes you have; it says nothing about what they mean. Every reader has to already know the shape of what it is looking at.

The Hypermedia Network grew up that way. Its signed blobs — Change, Ref, Profile, Comment, Capability, Contact — had shapes hardcoded twice, once in the Go daemon and once in the TypeScript apps. Introducing a new kind of resource meant a code change on both sides and a release. Document metadata was an untyped bag of keys, so a "person" page and a "product" page were indistinguishable to software. And the agent system had grown its own, separate schema world for tool inputs and outputs — one the hypermedia core knew nothing about, so a tool could not return a real document and a document could not be fed to a tool without a hand-written translation layer.

Two fragmented schema worlds, and extensibility gated on releases. That is the problem Onyx exists to solve.

Onyx is a small schema language for IPLD data — the values DAG-CBOR can encode — designed so that the type system lives inside the network it describes rather than beside it. Three moves make that work.

Types are data. An Onyx schema is itself a DAG-CBOR block: same encoding, same content addressing, same signing and syncing as the data it types. A schema has a CID. It can be pinned, fetched, and verified like any other blob. There is no separate registry service to run or trust.

Types are documents. Every schema is also published as a normal Hypermedia document, owned by an account and reachable at an hm:// URL. That gives types names, versions, human descriptions, and a place in the same browsable graph as everything else. A document declares what it is by pointing at one of these URLs. Because references are names rather than hashes, types can refer to each other in cycles — a folder that contains files that live in folders — which a pure hash graph cannot express. See references & naming.

Types are minimal. Nine kinds of value, seven shapes a schema can take, and one bar for every feature: the schema that defines what a schema is must remain a valid instance of itself. Onyx describes Onyx. That self-description is the design constraint, and it is what keeps the language from sprawling. See the schema language and design rationale.

Readers notice nothing, except that typed pages can render more richly — a person page can show a person, not a bag of keys.

Authors get guardrails: the attributes form knows which fields a document of this kind needs, offers the right controls for each (a dropdown for an enum, a searchable title pill for a document reference, a file picker for an IPFS reference), and points out what is out of spec — without ever refusing to save.

Developers get types in TypeScript, a browsable, linked reference for every schema, schema-driven forms for free, and a console for calling the API with validated inputs.

Agents and tools get contracts they can read and be checked against — the foundation for tools and agents that are themselves hypermedia resources.

Validation in Onyx is deliberately two-speed. At rest it is advisory: a blob is a cryptographic fact, and you will routinely receive data whose schema you have not fetched or whose author used a newer version. The app stores it, renders what it can, and shows red, non-blocking warnings rather than refusing. At a boundary it is strict: the reference validator rejects malformed schemas outright, and a tool or API call is checked against its declared contract before it runs. Lenient where data lives, strict where it is acted on.

Read how Onyx works for the system end to end, typed documents for the document-binding model, or go straight to the reference chapters from the home page.