Examples

Every example here is built with Hypermedia Schemas and published as its own page under example/, with the schema beside it as example/<name>.schema.json. Each one shows one feature and links to the types it uses. The groups follow Hypermedia Schemas in one page. Thirty-two are schemas, and five are instances: documents whose attributes are the data.

Structs

A struct is a closed map with named fields, each marked required or optional.

address is three strings, street and city required and postalCode optional.

geo is float latitude and longitude with an optional integer altitude.

person has a required name, an integer age, a boolean flag, a home that includes address, and a list of nicknames.

employee extends person with a required employeeId and a department.

admin extends employee with a map of boolean permission flags, a two-level chain from admin to employee to person.

stats holds three integers bounded from 1 to 10, a literal-union alignment, and a list of traits.

constrained shows value constraints: a username with minLength, maxLength and pattern, a score between 0 and 100, and a list of one to three tags.

blob is a bytes payload with a required mime string and an optional size.

article pulls the others together: a status union, an author Link<person>, tags, a bytes body, a word count, a cover Link<blob>, a list of comment links, and open string metadata.

Maps and lists

A list constrains its items. An open map constrains its values. See the schema language.

counts is Map<Integer>, the worked example.

tags is List<String>.

matrix is List<List<Integer>>, a nested list.

metadata is Map<String>, an open map of strings.

registry is Map<Link<person>>, a map whose values are typed links.

tree is a node with an integer value and a list of links to child trees.

json is a recursive union: a JSON value is null, a boolean, an integer, a float, a string, a list of JSON values, or a map of JSON values.

Unions and literals

A union accepts a value that matches any one of its variants. A bare literal accepts exactly one value, so a union of literals is a fixed set of choices.

status is the union of three literals, draft, published and archived.

value is anyOf string, integer, boolean or null.

entry is a filesystem entry: a folder or a file.

Recursion

These work because schemas reference each other by name, as an hm:// URL. A content hash cannot point at itself, so a hash-based reference could not form a cycle. References and the fixpoint problem explain why.

document refers to itself: previous links to another document.

comment is a thread, because a comment's replies link to comments.

folder and file are mutually recursive: a folder lists files and subfolders, and a file links back to its parent folder.

A custom block and a custom Change

These show how an application adds its own block type and constrains the changes it accepts.

poll-block extends block/base with the type literal Poll, a required question, a required list of options, and attributes such as multiple.

app-block is the union of the core blocks and poll-block: every block this application understands.

myapp-change instantiates the generic change with Block set to app-block, so a change carrying an unknown block type is rejected deep inside its ops.

Attributes schemas for typed documents

An attributes schema is a plain struct of the fields a document's metadata carries. A document names it with attributesSchema, and a folder names it for its children with childAttributesSchema. See typed documents.

person-doc is a required surname and an optional givenName.

world-doc is a genre chosen from five literals, an epoch date and a tagline. It types the page at the root of the World Builder.

character-doc has birth and death dates, a role, hm:// links to a home place and a faction, and ipfs:// links to a portrait, stats and notes.

place-doc has a kind, a founding date, links to a containing region and a ruling faction, and ipfs:// links to geo coordinates and a map.

faction-doc has founding and dissolution dates, links to a seat and a leader, and an ipfs:// link to a banner.

event-doc has start and end dates, links to a location, a protagonist and a faction, and an outcome.

Instances

An instance is an ordinary typed document: its own attributes are the data, and its attributesSchema names the type they follow. Open one in the Seed app and its Attributes tab checks the data against the type.

alice and carol are people, instances of person.

bob and dave are employees, instances of employee.

root is an admin, an instance of admin, which is itself two levels of extension.

Every schema and instance page lists what it depends on and what depends on it. From person you can reach its dependents, employee plus alice and carol. From bob you can walk up to employee and person.

Checking the examples

From a checkout of the Seed repository, the reference validator checks every example schema against the meta-schema and runs accepting and rejecting data cases for many of them.

node scripts/hypermedia/validate.mjs

To check your own data file against one of these schemas, name the schema and the file.

node scripts/hypermedia/validate.mjs example/article my-article.json

The Seed CLI also checks data against a published type:

seed-cli blob validate -f value.json --schema <type URL>