Schema Workflows
This page gives numbered steps for each task with Hypermedia Schemas and documents, from reading a type to publishing one, in the Seed app, with the CLI and through an agent.

This page shows how to do each common task with Hypermedia Schemas. A schema describes what some data must look like, and a document that follows one is a typed document. The tasks are: read a type, type a document or a folder, check a document, find typed documents, and define a type.

Each task has steps for three surfaces: the Seed app (desktop and web), the CLI (seed-cli), and an agent (the read and write tools of Seed Agents). Typed blob workflows continues with raw objects and signed blobs. The schema language explains the words a schema is written in.

Before you start

The app. Typed documents need no setting. The Attributes tab of any document shows its schema bindings. On desktop, two menu entries sit behind a switch: Schema in the New menu, and New World… in a document's options menu (the World Builder). To show them:

    Open Settings.

    Choose Advanced.

    In the Developers card, press Enable Debug Tools.

    Turn on Hypermedia Schemas.

The app only warns about a value that breaks its schema. It marks the value in red and never refuses it. See the rationale.

The CLI. Point the CLI at the server you work with, and sign with a key it holds.

    --server https://hyper.media is the default. It is the public gateway.

    --server http://localhost:58004 is the API of the desktop dev app.

    --key <name> chooses the signing key. key list shows the keys.

    --dev is a shortcut for the dev network. It sets the server to https://dev.hyper.media and uses the development keyring.

    Do not use --dev and --server together. The CLI stops with an error if you do.

The command reference is CLI, and keys covers the keyring.

An agent. An agent reads hypermedia with read <address> and publishes with write <address>. Publishing needs the publish grant on the agent. The contracts are in tools. The verbs have their own pages: read and write.

Names used below. <acct> is an account id such as z6Mk…. <library> is the key of the space the library is published to. Every library schema has a page at hm://<library>/<name>, where the name is its path in the library. So hm://<library>/document is the base document type. Inside schema files the library is written hm://hyper.media/<name>. The SDK resolves that name and the network does not, so a URL you open needs the key. See references and naming.

Read a document and its type

A document is its metadata (name, summary, icon, the schema fields) and its content, a tree of blocks. You can follow the types all the way down to the kinds of value they are built from.

The Schema view is the app's view of one schema. It shows the schema's fields, its union arms, what it depends on and what depends on it. A type page shows the Schema view above its body. A schema with no page opens in the Schema view at /hm/schema/<cid>, under a Schema tag.

In the app

    Open any document. The Attributes tab lists its metadata as fields you can edit. The Content tab is the block tree.

    Open hm://<library>/document. The page explains the type in prose and shows its schema above the body: metadata and content, each a link.

    Follow metadata to metadata. It lists every built-in key, including attributesSchema, childAttributesSchema and schemaDefinition.

    Follow content to block/node and on to the block types. Every type name is a link, down to the nine kinds in the data model.

    Read the Schema view of each type. It shows the fields with their kinds and required flags, the union variants, the inherited and added fields of an extension, the generic parameters, the published hm:// URL and CID, and the source dag-json.

    To see the raw blob, choose Inspect Schema in the type page's options menu. It opens the schema blob in the inspector, the screen that shows any blob by its CID.

With the CLI

    document get --md hm://<acct>/<path> prints the document as markdown. The metadata is YAML frontmatter, and each block's id follows the block.

    document get --json hm://<acct>/<path> prints the document as the API returns it. document get -m hm://<acct>/<path> prints the metadata only.

    document get --md hm://<library>/document reads the type page like any other page.

    schema get document prints the schema that page defines. schema get --resolve document prints the same schema with every reference followed and every extension merged.

    blob get <cid> reads any blob back as dag-json.

    document validate hm://<acct>/<path> names the schema a document follows and how it got it: its own attributesSchema, or the parent's childAttributesSchema. If the document has no schema, it says so.

Through an agent

    read hm://<acct>/<path> returns the document as markdown with frontmatter, the same picture the CLI gives. Add /:attributes after the address to read only the metadata. A read of a typed document also returns a schema block: the type, how it was bound, and any missing required fields.

    read hm://<library>/document reads the type page.

    read ipfs://<cid> fetches what the CID names. A file is loaded into memory. A DAG-CBOR object is decoded, with its value, its signature check and its schema check.

Give a document custom attributes and a type

You can add your own attributes to a document, such as surname, status and born. When the document is one of a kind of thing, you say which type it follows. Then the attributes are checked.

In the app

    Open the document and switch to the Attributes tab.

    Press Add field.

    Enter the Field name, pick the type of the field (text, number, toggle, list, object, link…), and enter the value.

    Save or publish, as with any edit.

    To type the document, add the field attributesSchema and set it to the type document's URL (hm://<acct>/types/person). The field is a document reference, so it offers a search and shows the target as a title pill. The type's required fields appear at once as fixed rows.

You can also start from the type. Its page has a New Document button, which starts a draft whose attributesSchema is that page.

With the CLI (three ways, pick one)

    Export, edit, import. space export hm://<acct> -d ./site writes every document to a markdown file. The frontmatter of each file holds every metadata key. Add surname: Smith (and attributesSchema: hm://<acct>/types/person) to the file. Then run space import hm://<acct> -d ./site --key <name>. Only the changed document publishes.

    Create from a file. document create -f page.md keeps every frontmatter key: surname: Smith in the file becomes surname on the document.

    Update with flags. document update hm://<acct>/<path> --metadata '{"surname":"Smith"}' sets any attribute from the command line. Add --attributes-schema hm://<acct>/types/person to type the document. Both flags work on create too, and a flag wins over the file.

Through an agent

    Call write hm://<acct>/<path> with options: {action: "update", metadata: {surname: "Smith", attributesSchema: "hm://<acct>/types/person"}}. The agent merges options.metadata into the document's metadata, and custom keys are allowed. dryRun: true shows what would publish.

Type every page in a folder

You can make a folder typed. Then every page created directly under it is a person, a place or an event. You do not set attributesSchema on each page by hand.

In the app

    Open the folder document's Attributes tab.

    Add the field childAttributesSchema and point it at the type document (hm://<acct>/types/person). It uses the same search pill as attributesSchema.

    Create a page under the folder. Its required attributes are already there as fixed rows, and its Attributes tab says which type it inherits.

The type page's New Collection button does steps 1 and 2 on a new draft. A child that sets its own attributesSchema uses that instead. See typed documents for the inheritance rule.

With the CLI

    Run document update hm://<acct>/people --child-attributes-schema hm://<acct>/types/person. Or put childAttributesSchema: hm://<acct>/types/person in the folder's frontmatter, then publish the folder page with document create or space import.

Through an agent

    Call write hm://<acct>/people with options: {action: "update", metadata: {childAttributesSchema: "hm://<acct>/types/person"}}.

Check a document against its schema

Wherever you edit a typed document, the editor tells you what the type requires and what does not match. It never stops you saving.

In the app

    Open a typed document. It is typed by its own attributesSchema, or by the parent's childAttributesSchema.

    Look at the required fields. They are rows that are always visible, at the top of the Attributes tab and above the body in the Content tab. You cannot remove them.

    Edit a field. Each field gets the control its type calls for: a dropdown for a union of literals, a date picker for a date, a searchable title pill for a document reference, and a file picker for an IPFS reference.

    Look for red badges. A value that breaks the schema shows a red badge on the field, and the badge names the rule ("surname is required", "status must be one of draft, published, archived"). Saving still works.

    Press a chip to add an optional field. The Attributes tab suggests the schema's optional fields as chips, and each one starts with a value that fits the schema.

With the CLI

    Run document validate hm://<acct>/<path>. The command finds the document's effective attributes schema (its attributesSchema, else the parent's childAttributesSchema), fetches every type that schema names, and checks the metadata.

    Read the result. Each violation is on its own line ($.born: does not match pattern for format "date"). The exit code is 1 when there is any violation. With --json the report is {id, schema, via, violations}.

    To check a whole folder of files, run space import self -d ./site --check. It runs the same check over every file. A file's parent in the folder gives the inherited type. When the folder has no parent file, the site's parent document gives it. Nothing publishes while any file breaks its schema.

Through an agent

    read hm://<acct>/<path> of a typed document returns a schema block, {schema, via, required, missing, violations}. It names the type. It says whether the type came from the document's own attributesSchema or was inherited. It lists what does not match.

    A write to a typed document returns the violations as warnings beside the published id. It publishes anyway, because the check only warns. dryRun: true returns the same warnings without publishing.

Find documents by type or attribute

A typed attribute is an ordinary document attribute, so the document query finds typed pages. The query grammar is the same on every surface.

In the app

    Open Explore, the advanced search. Its attribute pickers list the attribute keys that documents carry and the values each key takes.

With the CLI

    query <acct> --where 'attributesSchema=hm://<acct>/types/person' lists every page typed by person. Any attribute condition works.

    query '*' --where 'has:childAttributesSchema' lists every typed folder, anywhere.

    attributes <acct> lists which attribute keys documents carry, with their kinds. attributes <acct> --values status lists the distinct values of one key.

Through an agent

    call the tool query with q in the same grammar, or a raw filter. Examples of q: attributesSchema=hm://<acct>/types/person, in:hm://<acct>/places kind=fortress, has:childAttributesSchema, status="In Progress" AND priority>=3. The tool returns each document with its full attributes. You can sort and page the result.

    call the tool attributes to list the attribute keys documents carry, with their kinds. With key, it lists the distinct values of one key.

Define a type and publish it

You can publish a type of your own, such as a Person or a Vote, as a document that others point at by URL. The document's metadata key schemaDefinition links the schema blob.

In the app

    Choose New, then Schema. This needs the Hypermedia Schemas switch. A draft opens with an empty schema shown above the body.

    Give the document a name, and write a description in the body. The page is where people read about the type. A schema can hold a short description of its own, and it has no name.

    Press Edit on the schema section. The schema editor opens.

    Press Add field for each property. Enter its Field name, its type, whether it is required, and a description. You pick the type from every type document and from the built-in types (text, date, HM link, IPFS file / object…). A union or a list is edited in the same form. The JSON tab lets you edit the schema as text.

    Publish. The app freezes the working schema into a DAG-CBOR blob, and the document's schemaDefinition points at it. The page shows a schema tag in its header. For a struct of attributes it also shows New Document and New Collection. For a signed blob type it shows Create.

Three more ways to define a schema in the app:

    Build on an existing type. Open its page and choose Extend Schema in the options menu. The new draft starts as {type: <that type>} plus your fields, which is an extension. An attributes schema for a typed document is a plain struct of attributes. It never extends hm://hyper.media/document. See typed documents.

    Make a schema with no page. Choose New Schema from the options menu of the inspector, or of a schema's page at /hm/schema/<cid>. The editor opens against the meta-schema, so the form offers only choices a valid schema can make. Publishing stores the schema as a blob that you reference by CID.

    Give a document or a folder fields without a separate type page. Open its Attributes tab. Scroll to Attributes schema (for this document) or Children attributes schema (for the pages inside it). Press Define, then Custom Attributes or Custom Children Attributes, and add the fields. Typed documents describes this in-page schema.

With the CLI (check first, then publish with step 2 or step 3)

    Check it. schema validate person.schema.json checks the file against the meta-schema. The command also takes an ipfs:// CID or a type document's URL.

    Publish it with a folder. Write the schema as dag-json next to the page: types/person.md and types/person.schema.json. Then run space import hm://<acct> -d ./site --key <name>. It encodes the schema to its CID, publishes the blob, and binds it to the document as schemaDefinition. See publish a folder.

    Or publish it with one command. document create -f person.md -p types/person --schema-definition person.schema.json publishes the page and the schema blob together and binds them. document update hm://<acct>/types/person --schema-definition person.schema.json binds a new schema to a page that exists.

Through an agent

    Call write ipfs:// with the schema as JSON content and options: {schema: "schema"}. This checks it against the meta-schema, publishes the schema blob, and returns its CID.

    Call write hm://<acct>/types/person with options: {name: "Person", metadata: {schemaDefinition: "ipfs://<cid>"}}. This binds the blob to a type page. A schemaDefinition that is not a valid schema comes back as a warning.

Which surface runs which check

One piece of code resolves schemas, checks values and signs blobs. It lives in @seed-hypermedia/client (schema-engine, schema-resolve, signed-blob). The app, the CLI and the app environment share that code, so every surface agrees about what a schema means. See the SDK.

check

app

CLI

SDK

agent

a document against its effective schema

Attributes tab, live

document validate, space import --check

checkDocumentSchema

read → schema; write → warnings

a schemaDefinition is a valid schema

schema editor, live

schema validate

checkSchemaDefinition

write → warnings

a raw object against a type

value editor, live

blob validate, blob create

validate + loadSchemaRef

read ipfs://, write ipfs:// (refuses)

a signed blob's signature

inspector

blob verify

verifySignedBlob

read ipfs:// → signature

resolve a type by URL, CID or name

Schema view

schema get [--resolve]

resolveSchemaRef, loadSchemaRef

read hm:// (type page), read ipfs:// (blob)

find documents by attribute, or typed by a schema

Explore (advanced search)

query --where, query --filter

QueryDocuments

call → query

which attribute keys exist, and their values

Explore's attribute pickers

attributes, attributes --values

ListDocumentAttributeNames, ListDocumentAttributeValues

call → attributes

The editors warn and never block. The CLI's checks exit with an error. blob create and an agent's write ipfs:// refuse a raw object that does not match its type, unless you force them.

See also

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Comments