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.

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.

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 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.

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.