The problem

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 know the shape of the data in advance.

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. A new kind of resource needed a code change on both sides and a release. Document metadata was an untyped bag of keys, so software could not tell a "person" page from a "product" page. The agent system had its own separate schema world for tool inputs and outputs. The hypermedia core knew nothing about it. A tool could not return a real document, and a document could not be passed to a tool without a hand-written translation layer.

So there were two separate schema worlds, and adding a type needed a release. Hypermedia Schemas solve that.

What Hypermedia Schemas are

Hypermedia Schemas is a small schema language for IPLD data, the values DAG-CBOR can encode. The type system lives inside the network it describes. Three design choices make that work.

Types are data. A Hypermedia schema is itself a DAG-CBOR block. It uses the same encoding, content addressing, signing and syncing as the data it types. A schema has a CID. You can pin, fetch and verify it 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. References are names, so types can refer to each other in cycles, such as a folder that contains files that live in folders. A pure hash graph cannot express that. See references and naming.

Types are minimal. There are nine kinds of value and nine shapes a schema can take. Every feature has to pass one test: the schema that defines what a schema is must stay a valid instance of itself. The meta-schema describes itself. That self-description is the design constraint, and it keeps the language small. See the schema language and design rationale.

What it makes possible

New resource types without a release. To add a kind of thing, publish a schema document. Any app that can resolve the URL can validate that kind, render forms for it and generate code for it. The core does not change.

Typed documents. A document can say which schema it conforms to, which schema its children must conform to, or which schema it defines. The editor shows required fields as rows that are always present and flags data that does not match. See typed documents.

One schema system for content and for tools. A tool's contract is an input schema and an output schema. Those are Hypermedia schemas, the same objects that type documents. A tool can emit a real document, and a document can be a tool's typed input, because both sides use the same language.

Generated code. Every schema becomes a TypeScript type. The app's types come from the published schemas, so there is no second source of truth to drift.

Machine-readable meaning for agents. An agent that lands on an hm:// document can follow its attributesSchema link and learn which fields to expect and what they mean. It reads a tool's contract the same way. Types are found by URL, with no out-of-band convention.

Who it serves

Readers see no change, except that typed pages can render better. A person page can show a person instead of a bag of keys.

Authors get guardrails. The attributes form knows which fields a document of this kind needs. It offers the right control for each: a dropdown for a fixed set of choices, a searchable title pill for a document reference, and a file picker for an IPFS reference. It points out what does not match the schema, and it never refuses to save.

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

Agents and tools get contracts they can read and be checked against. Tools and agents can then be hypermedia resources themselves.

Validation warns and never blocks

Validation has two modes. At rest it is advisory. A blob is a cryptographic fact, and you will often 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 warnings that do not block anything. At a boundary it is strict. The reference validator rejects malformed schemas, and a tool or API call is checked against its declared contract before it runs. Validation is lenient where data is stored and strict where it is acted on.

What Hypermedia Schemas are not

It is not	Because
a re-implementation of JSON Schema	breadth is a non-goal; the language is intentionally tiny and must stay self-describing
IPLD Schema	Hypermedia schemas are themselves IPLD data and hypermedia documents, and references are names that can recurse
a query or transformation language	it types data, nothing more; queries live in the hypermedia layer
an abstraction over IPLD	links and content addressing are visible on purpose
a gate on writing	violations warn; they never block a save

Where to go next

Read how Hypermedia Schemas work for the whole system, typed documents for how documents bind to schemas, or go to the reference chapters from the schema home page.