This page shows how to work with typed blobs. A blob is one stored piece of data, named by the hash of its bytes. A typed blob is a blob that follows a schema, which is a description of what the data must look like. There are three tasks: create a raw object that follows a schema, define a signed blob type of your own, and sign and publish an instance of it.
Each task has steps for the Seed app, the CLI and an agent. Schema workflows covers the setup of each surface, the names used here (<acct>, the inspector, the Schema view), and the tasks for documents and types. Typing a blob explains the model.
Create an object of a type
When a type is published, you can create an object of that type. The object is a DAG-CBOR blob, not a document. The editor checks it against the schema as you type. Typing a blob explains the schema link the object carries.
In the app
Open the type document and choose New Raw Value in its options menu. The blob editor opens with the schema's required fields already there. Each field has the control its type calls for, and the editor checks the blob on every keystroke.
Fill the fields.
Press Publish. The app publishes the blob with a schema link to the type and shows its ipfs://<cid>. The inspector opens the blob, names its type as a chip, and says whether it matches.
Other ways to reach the same editor:
On a schema blob in the inspector, choose New Instance of this Schema in the options menu.
On the web, and for a signed blob type, the page header has a Create button that opens a form for the type.
Inside a document, open the Attributes tab. A field whose schema is an IPFS reference has a Create linked object button (the curly braces). When the field has a target type, the dialog is locked to that type and publishes only a value that matches it. Press Publish & link to set the field to the new ipfs://<cid>. Edit linked object publishes a new version and points the field at it.
To check a blob that exists:
Open the blob by its CID in the inspector. When the blob links a schema, the inspector fetches the schema and checks the value against it. The result is a warning only.
To check against another type, choose Attach Schema… and pick the type.
Edit the blob as fields, or choose View raw to edit it as dag-json.
New Blob in the inspector's options menu starts a blank DAG-CBOR object with no schema.
With the CLI
blob validate -f bob.json --schema hm://<acct>/types/person checks a dag-json value against the type. The schema can also be a file, an ipfs:// CID, or a library name.
blob create -f bob.json --schema hm://<acct>/types/person checks the value and refuses it on a violation, unless you pass --force. Then it publishes the DAG-CBOR blob with a schema link to the type's blob and prints ipfs://<cid>. -q prints only the URL. --dry-run shows the blob and its CID without publishing.
blob get <cid> reads it back as dag-json. blob verify <cid> checks it against the linked schema, and says that it is not a signed blob.
Through an agent
Call write ipfs:// with the object as JSON content and options: {schema: "hm://<acct>/types/person"}. The agent checks it against the type and refuses it on a violation, unless options.force is set. Then it publishes the DAG-CBOR blob with a schema link and returns its CID.
read ipfs://<cid> reads it back with its schema check.
Define a signed blob type
You can define a new kind of signed record, such as a Vote or an Attestation. It carries signer, sig and ts like every built-in blob. It adds its own fields and its own type tag. The shared fields are called the envelope, and Network blobs explains it.
In the app
Choose New, then Schema. This needs the Hypermedia Schemas switch (schema workflows says where it is).
Press Edit on the schema section. In the editor, search the root type for Blob, the signed blob envelope, and pick it.
Enter the Type tag, for example Vote. The schema is then an extension of the envelope with type pinned to the literal "Vote". The envelope fields show as inherited.
Add the type's own fields, for example target as an HM link and choice as a union of literals.
Publish. The page carries the schema and is a signed type: its Create button opens the signing form.
You can also start from the envelope. Open the Blob page and choose Extend Schema in its options menu.
With the CLI
Write a schema file, vote.schema.json, whose root is {"type": "hm://hyper.media/blob", "properties": {"type": {"value": "Vote", "required": true}, …}}.
Publish it as a type page with document create -f vote.md -p types/vote --schema-definition vote.schema.json. Or put it beside its page and run space import hm://<acct> -d ./site --key <name>. Both are in define a type and publish it.
Through an agent
Call write ipfs:// with options: {schema: "schema"} and, as content, a schema whose root is {"type": "hm://hyper.media/blob", "properties": {"type": {"value": "Vote", "required": true}, …}}. This publishes the schema blob of the signed type and returns its CID.
Call write hm://<acct>/types/vote with options: {metadata: {schemaDefinition: "ipfs://<cid>"}}. This binds the blob to a type page.
Sign and publish an instance of a signed type
You fill in a Vote and sign it with the account you are using. The result is a signed blob on the network, and anyone can check its signature.
In the app
Open the Vote type page and press Create. The form shows only the type's own fields. The envelope is filled in at signing.
Fill the fields. The app signs with the selected account. The button explains when the app cannot sign for that account.
Press Sign & publish. The app encodes the blob as canonical CBOR with sig set to zeros, signs it with the account's key, and publishes it with the signature in place. This is the same signing rule the daemon uses.
Press Inspect the signed blob to open it. signer is the account, sig is the signature, and the type chip names Vote.
With the CLI
Run blob sign -f vote.json --schema hm://<acct>/types/vote --key <name>. The file holds the type's own fields. The command adds the envelope: type from the schema's pinned tag, signer set to the key's principal, ts set to the current time, and sig. It signs the canonical DAG-CBOR with sig set to zeros, which is the daemon's rule and the app's rule too. Then it checks the whole signed blob against the type, publishes it, and prints ipfs://<cid>. --dry-run shows the signed blob without publishing. With no schema, --type <tag> signs any blob with the envelope.
Run blob verify <cid>. It checks the signature (who signed, and when) and the schema. The exit code is 1 when either check fails. --json reports both.
Through an agent
Call write ipfs:// with the fields as JSON content and options: {schema: "hm://<acct>/types/vote", sign: true}. The agent wraps the fields in the signed blob envelope and signs with its own identity. options.signer picks an identity when several are enabled. Then it checks the blob and publishes it.
read ipfs://<cid> returns the decoded value, the signature (signer, time, and whether it is valid), and the schema check.
See also
Schema workflows: setup, typed documents, and how to define and publish a type.
Typing a blob: the schema link on a raw object, with a worked example.
Network blobs: the signed envelope and the built-in signed blob types.
Blob: the envelope's fields and the signing rule.
CLI: the blob and schema commands.
write: the agent verb that publishes blobs.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime