· one of 13 variants:
A schema is a value that constrains other values. It is either a map written with the schema vocabulary, or a bare literal ("draft", 1, true, null) that accepts exactly one value. Every schema is typed by the meta-schema and matches one of its variants.
The meta-schema, named schema, is the schema that describes what a schema is. It is a discriminated union of nine map variants and four literal kinds. It validates as an instance of itself. It is the one type in the system that is known without being looked up.
This page defines the meta-schema. Its formal schema is attached through the schemaDefinition key in this page's metadata, so the Seed app can show it and create values of this type.
Hypermedia Schemas are a type system for content-addressed data. They type the IPLD and DAG-CBOR values that Hypermedia blocks and blobs are built from. A schema is itself a DAG-CBOR object on IPFS, so schemas reference other schemas the same way data references data.
This page shows how to use Hypermedia Schemas in the Seed app and lists the reference pages.
Start here
These pages explain the system from the top down:
Hypermedia Schemas in one page: the model, the library by link, the three keys that type a document, and the CLI commands, SDK calls and agent verbs that read, write and check them.
Why Hypermedia Schemas: the problem they solve, what they make possible, and what they do not try to do.
How Hypermedia Schemas work: the pipeline from a schema file to a signed blob, a browsable document, a resolved reference and a generated type.
Typed documents: how a document says what it is with attributesSchema, childAttributesSchema and schemaDefinition, and what the editor does with them.
The World Builder: a worked demo that builds a set of linked types, with date pickers, title pills and linked objects on every page.
User stories: what a person should be able to do through the app, the CLI and an agent, step by step, and how far each surface has come.
In one minute
Every value is one of nine kinds: null, boolean, integer, float, string, bytes, list, map, link. The data model describes each one.
A schema is a map that constrains a value. Its keys are type (a kind, or another schema to include or extend), properties (one property per field, each with its own required flag), items, values, target, anyOf, the generics keys params, var and args, and value constraints such as minLength, pattern and minimum. A bare literal ("draft", 1, true, null) accepts exactly that value, so a fixed set of choices is a union of literals.
Schemas reference each other by hm:// URL. A name can take part in a cycle and a content hash cannot, so names let types recurse.
Validation is advisory in the editors, which warn and never block, and strict in the reference validator.
Using Hypermedia Schemas in the Seed app
Typed documents need no setting: any document's Attributes tab shows its schema bindings. The raw building blocks, New Blob and New Schema, sit behind a switch on desktop. Open Settings, Developers, press Enable Debug Tools, then turn on Hypermedia Schemas. With it on, a document's options menu shows both entries, and the New menu gains Schema. The web app shows the options menu entries by default.
Browse the schemas
Every schema is a page of this site, starting at the meta-schema on this page. In the Seed app, a document that defines a schema shows it above its body in the schema browser. A schema blob with no defining document opens on its own at /hm/schema/<cid>.
The library covers the meta-schema, primitives, examples and the schemas of the network's signed blobs.
Each schema shows its fields with kinds and required flags, union variants, inherited and added fields for an extension, generic parameters, its published hm:// URL and CID, and its source dag-json.
Every reference is a link. Click a field's type, a dependency, or an hm:// value in the source to open that schema. Each page also lists what it depends on and what depends on it.
A type's page offers New Document and New Collection. Its options menu adds Extend Schema, New Raw Value and Inspect Schema.
Create a schema
Choose New Schema from the options menu. The editor opens against the meta-schema, so the form offers only choices a valid schema can make: pick a kind, add properties, mark them required, add literals or unions. Publishing stores the schema as a content-addressed blob that you can reference by CID or by name.
Create typed data
To start a value that matches a schema, choose New Blob for a blank DAG-CBOR object, New Raw Value on a type's page, or New Instance of this Schema on a schema blob in the inspector. The editor follows the schema. It suggests the schema's fields, offers dropdowns for unions of literals and pickers for union variants, shows the right controls for link and bytes, and flags anything that does not match without blocking you.
Type a document's metadata with a schema
A document names the type of its own attributes with attributesSchema. A folder names the type of its children's attributes with childAttributesSchema. Both are bindings in the document's Attributes tab. The tab ends with a Schema definition section, where a document defines a schema of its own. Once a type applies, the tab follows it. Required fields show as fixed rows and optional ones as chips. Literal unions get dropdowns, dates get date pickers, and hm:// references get search. A value that does not match gets a warning. Typed documents has the rules.
Inspect and validate
Open any IPFS blob in the inspector. When the blob is a schema, the inspector offers New Instance of this Schema. When a DAG-CBOR blob links a schema, the inspector fetches the schema and checks the value against it, as a warning only. You can edit the blob as fields or as raw dag-json, and attach or change its schema.
Raw objects and their schemas
A raw DAG-CBOR object links directly to its schema with "schema": {"/": "<schema-cid>"}. The blob tools set this field aside before checking the object's data against the schema. Both the schema and the instance can exist without a document. The schema field on raw objects defines the field and walks through publishing Person, Employee and an instance of each using only raw blobs.
Schemas can have hypermedia documents
A schema can be published as a normal Hypermedia document whose metadata has a schemaDefinition key pointing at the schema blob as ipfs://<cid>. Other schemas and documents then reference it by hm:// name, which is readable, versioned and resolvable. The CID pins the exact bytes. The type system is stored on the same network it types.
Reference documentation
The concepts, in reading order:
The data model: the nine kinds of value.
The schema language: the full vocabulary of closed maps, unions, generics, extension and value constraints, and how the language describes itself.
References & naming: include, typed link and extend, hm:// names, and why names make recursion possible where hashes cannot.
Encoding: DAG-CBOR, the dag-json human form, canonical encoding and the reserved-key envelopes.
Examples: every example schema, grouped by feature.
Schemas on the Hypermedia Network: schemas for the network's DAG-CBOR blobs (Change, Ref, Profile and the rest), the block model including tables and query blocks.
Design rationale: why the system has this shape, the decisions taken, and the open questions.
Terms: one page per definition, listed at the end of this page.
The tooling
The library's tools live in scripts/hypermedia/ in the Seed repository. The reference validator has no dependencies. It proves the meta-schema describes itself, validates every schema against it, and confirms the union rejects malformed schemas. The publisher hashes each schema to its DAG-CBOR CID. The TypeScript generator turns every schema into a TS type: maps become interfaces, literal unions become TS unions, extension becomes intersection, and Change<Block> becomes a TS generic. The registry generator bundles the library for the apps. The Seed app runs a port of the same validator, so its schema browser and editors agree with the reference validator. The Seed CLI, the SDK and Seed Agents use the same engine from @seed-hypermedia/client.
Terms
See also
Typed documents: how a document names its schema.
References and naming: why schemas point at each other by name.
Examples: every example schema, grouped by feature.
Metadata: the attribute keys that bind a document to a schema.
Blobs: the signed DAG-CBOR objects the network stores.
Documents: the pages schemas are published as.
URLs: the hm:// names schemas use.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime