· one of 13 variants:
A schema is a description of what some data must look like. It says which fields the data has and what kind of value each field holds. Software uses a schema to check data and to draw forms for it. A schema is data too, so one schema can describe other schemas.
Here is a small schema. It says: the data is a map with one required field, surname, and that field is a string.
{
"type": "hm://hyper.media/struct",
"properties": {
"surname": {"value": {"type": "hm://hyper.media/string"}, "required": true}
}
}The value {"surname": "Smith"} matches this schema. The values {} and {"surname": 7} do not.
The one schema that describes all schemas is the meta-schema. Its name is schema, and this page is its home. The meta-schema lists every shape a schema can take: nine shapes that are maps, and four kinds of plain value. Each shape is called a variant. A plain value such as "draft", 1, true or null is a literal: a schema that accepts only that one value. The meta-schema is a discriminated union, which means it picks one variant for each schema it checks. It also describes itself: it is a valid schema by its own rules. Software knows the meta-schema without looking it up.
The formal schema of the meta-schema is attached to this page. The schemaDefinition key in this page's metadata points at it, so the Seed app can show it and create values of this type. This page is also the starting point for all the pages about Hypermedia Schemas. They are listed below.
Hypermedia Schemas in brief
Hypermedia Schemas are a type system for content-addressed data. Content-addressed data is data that is named by the hash of its bytes. The schemas 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 a schema references another schema the same way data references data.
Every value is one of nine kinds: null, boolean, integer, float, string, bytes, list, map, link.
A schema names a kind or another schema with type. The other keys narrow what it names: properties for the fields of a struct, items for a list, values for a map, anyOf for a union, and value constraints such as minLength and pattern. A fixed set of choices is a union of literals. The words are all in the schema language.
Schemas reference each other by hm:// URL, which is a name. Two names can point at each other in a circle. Two content hashes cannot. So names let types refer to themselves and to each other.
You can publish a schema as a normal Hypermedia document. The document's metadata has a schemaDefinition key that points at the schema blob as ipfs://<cid>. Other schemas and documents then reference the document by name, and the CID pins the exact bytes. The type system lives on the same network it types.
Where to read next
Read the concepts in this order:
The data model: the nine kinds of value. Read it first.
The schema language: the full reference for every key a schema can use, and how the language describes itself.
References and naming: the ways one schema points at another, hm:// names, and why names can form a circle where hashes cannot.
Encoding: DAG-CBOR, the dag-json form that people read, canonical encoding and a schema's CID.
Then go to the page for what you want to do:
Typed documents: how a document says what it is with attributesSchema, childAttributesSchema and schemaDefinition, and what the editor does with them.
Typing a blob: how a raw DAG-CBOR object links to its schema, with a worked example.
Schemas on the Hypermedia Network: how schemas type the signed blobs (Change, Ref, Profile and the rest) and the block model. It also shows how to define a signed blob type or a block type of your own.
The catalogue of types: every type in the library with one line each. Use it to find a type's page.
Examples: every example schema, grouped by the feature it shows.
Schema workflows and typed blob workflows: numbered steps for each task in the Seed app, with the CLI and through an agent. They also say how to turn the schema menus on.
The World Builder: a worked demo that builds a set of linked types, with date pickers, title pills and linked objects on every page.
Why Schemas: the problem they solve, the reasons behind the language, and what it does not try to do.
The schema library pipeline: for contributors. It shows how the Seed repository checks, pins, publishes and bundles the library.
Words used in these pages
Each word below links the page that defines it.
Envelope, the dag-json spelling of a link or bytes
See also
Start with these
The schema variants
Terms
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime