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.
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.
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
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.
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.
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.mjsTo 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.jsonThe Seed CLI also checks data against a published type:
seed-cli blob validate -f value.json --schema <type URL>See also
Hypermedia Schemas: the schema system.
Hypermedia Schemas in one page: the features these examples follow.
Typed documents: attributes schemas on real pages.
The World Builder: the demo behind the world-builder types.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime