Typing a Blob
A raw DAG-CBOR object can name the schema that describes it in a top-level schema field, and this page shows how the tools check it, with a Person and Employee example.

A raw object can say which schema describes it. It does this with one extra field at the top, named schema, that links to the schema. For example, an object {"schema": <link>, "name": "Bob"} says "check me against that schema".

A raw object here is a DAG-CBOR blob: a piece of data stored by the hash of its bytes, its CID. The schema and the object are two separate blobs, each with its own CID. Neither needs a Hypermedia document. The schema field is optional. It is a convention of the Seed blob tools. It is not a keyword of DAG-CBOR or of the schema language.

The published link is a CID. In dag-json you write it as "schema": {"/": "<schema-cid>"}. The / envelope is how dag-json writes a real link. Put the bare CID inside it, without ipfs://. The shared resolver also accepts a string that names a schema, such as "schema": "ipfs://<schema-cid>" or an hm:// schema URL. The CLI and the write tool of Seed Agents add a CID link for you when you give them a schema whose CID is known.

To check a typed blob, the tools do four things:

    Read the blob's schema reference.

    Load that schema and the schemas it depends on.

    Take the top-level schema field out of the value to check.

    Check the fields that remain.

The stored blob keeps the link. You do not add schema to the schema's properties, and a closed struct does not count it as an unexpected field. In the SDK these steps are blobSchemaRef, loadSchemaRef, withoutSchemaLink and validate. If you call the low-level validator yourself, it does not remove the link for you.

Only a map can carry this field. You can still check a scalar or a list against a schema that you give separately, for example with the CLI's --schema option. An object can also leave the link out when you give its schema separately. The link states a type. It does not prove that the data matches.

Person and Employee as raw data

Publish the four objects below in order. Replace each CID placeholder with the CID you get back when you publish its schema. The built-in hm://hyper.media/… types come from the library bundled in the SDK, so you do not need to create documents for them.

1. Person schema. Save this as person.schema.json and publish it to get <person-schema-cid>. A schema does not need a schema link of its own. The tools check it against the meta-schema, which they already know.

{ "type": "hm://hyper.media/struct", "properties": { "name": { "value": {"type": "hm://hyper.media/string"}, "required": true }, "age": { "value": {"type": "hm://hyper.media/integer"} } } }

2. Employee schema. Save this as employee.schema.json and publish it to get <employee-schema-cid>. Its type names the Person schema directly by ipfs:// URL. Its properties extend Person, so both name and employeeId are required.

{ "type": "ipfs://<person-schema-cid>", "properties": { "employeeId": { "value": {"type": "hm://hyper.media/string"}, "required": true }, "department": { "value": {"type": "hm://hyper.media/string"} } } }

3. An employee. Save this as alice.json. Its schema link points at Employee, and the Employee schema refers to Person.

{ "schema": {"/": "<employee-schema-cid>"}, "name": "Alice", "age": 32, "employeeId": "E-001", "department": "Engineering" }

4. A person. Save this as bob.json. Person requires name, and age is optional.

{ "schema": {"/": "<person-schema-cid>"}, "name": "Bob", "age": 28 }

Publish the files with the CLI, in these steps:

    Publish person.schema.json. --schema schema checks it against the bundled meta-schema, and --no-link stores its content exactly as shown above.

    Put the Person CID you got back into employee.schema.json, then publish it the same way.

    Put both schema CIDs into alice.json and bob.json, then publish them.

seed-cli blob create -f person.schema.json --schema schema --no-link seed-cli blob create -f employee.schema.json --schema schema --no-link seed-cli blob create -f alice.json seed-cli blob create -f bob.json

The last two commands read the schema link of each object and check the object before they publish it. seed-cli blob validate -f alice.json runs the same check and publishes nothing.

schema, type and document bindings

These three are easy to mix up:

    In a schema, type names the kind or the parent schema that the schema refines.

    On a raw object, schema links to the schema that describes the object.

    A data field named type, such as "type": "Change" on a signed blob, is an ordinary field. The blob's schema constrains it. It does not replace the schema link.

Typed documents add a binding one level up. attributesSchema types a document's metadata, and schemaDefinition makes a document the named home of a schema blob. The four raw objects above need neither field.

See also

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

Unsubscribe anytime

Comments