JSON has no native way to write bytes or a link. dag-json borrows map syntax with one reserved key, /. These are the envelopes:

These are not maps. They are the JSON spelling of two separate kinds. In DAG-CBOR there is no ambiguity: a link is a tagged CID and bytes are a byte string. In dag-json they look like maps. This causes dag-json's one trap: a real data map with a single / key cannot be told apart from a link.

The schema language's rule avoids the trap (see the data model). Links and bytes are atomic kinds, and a schema never describes them as maps. A schema says {"type":"link"} and never reaches inside the envelope. The reference validator, validate.mjs, enforces this. Its typeOf recognizes the two envelopes and reports link or bytes, so a value typed map rejects a {"/":…} shape, and the reverse also holds.

A raw object can carry an optional top-level schema field that links to the schema describing its data. The schema and the instance are separate DAG-CBOR blobs, each with its own CID. Neither needs a Hypermedia document. This field is a convention of the Seed blob tools, not a keyword of DAG-CBOR or of the schema language.

The published link is a CID, written in dag-json as "schema": {"/": "<schema-cid>"}. The / envelope represents a native link, as explained above; put the bare CID inside it, without ipfs://. The shared resolver also accepts a schema-reference string, such as "schema": "ipfs://<schema-cid>" or an hm:// schema URL. The CLI and agent write tools add a CID link by default when given a schema with a known CID.

To validate a typed blob, the tools read its schema reference, load that schema and its dependencies, remove the top-level schema field from the value being checked, and validate the remaining fields. The stored blob keeps the link. You do not add schema to the schema's properties, and it does not count as an unexpected field in a closed struct. In the SDK these steps use blobSchemaRef, loadSchemaRef, withoutSchemaLink and validate. Calling the low-level validator directly does not remove the link for you.

Only a map can carry this field. A scalar or list can still be validated against a schema supplied separately, for example with the CLI's --schema option. An object may also omit the link when its schema is supplied separately. The link declares a type; it is not proof that the data conforms.

Person and Employee as raw data

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

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

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

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

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

schema, type and document bindings

CIDs are content hashes, so the same value must always encode to the same bytes. Otherwise its CID would change. DAG-CBOR requires a canonical encoding:

map keys sorted by a defined ordering,

shortest-form integer encodings,

no floating-point NaN/Infinity,

exactly one way to encode any value.

For authors, key order and formatting in these JSON files do not matter. Whitespace and the order of properties do not change the resulting block or its CID, because the encoder normalizes them. Two schemas that differ only in key order are the same block with the same CID.

Two scripts turn this repo into published Hypermedia types. node scripts/hypermedia/publish.mjs computes the CIDs, and pnpm hypermedia:push publishes the blobs:

publish.mjs parses each .schema.json file as dag-json. References are already hm:// URLs, which are names. The step does not rewrite them into CIDs, so recursive and mutually recursive schemas keep working (see references).

It encodes each schema to canonical DAG-CBOR and content-addresses it as a CIDv1 with sha2-256 and the dag-cbor codec (0x71). The backend uses the same codec for its blobs.

It writes schemas.lock.json, the manifest that maps each hm:// URL to its CID. publish.mjs publishes nothing. pnpm hypermedia:push encodes each schema file again, checks its CID against schemas.lock.json, and stops on any mismatch. Then it publishes every schema blob to the server and imports each page as a document in the space of the signing key at its path, with hm://hyper.media in links and frontmatter swapped for that key, with the schema blob as the page's schemaDefinition.

Canonical DAG-CBOR is deterministic, so the CID is a pure function of a schema's content. CI and any runtime that recomputes it get the same CID. This has two consequences:

node publish.mjs --check runs in CI. It fails if the lockfile is stale, and a CID that changes in a diff means the schema changed.

A schema links others by name, so its CID depends only on its own bytes. Editing block does not change the CID of change. In a CID or Merkle graph, any change would propagate upward. The manifest is the separate name-to-CID index a resolver uses.

Anyone can resolve a schema by its hm:// name, through the manifest or the SDK's bundle. The network does not resolve the hyper.media authority yet, so a fetch over the network uses the docs space's key. They can also fetch an exact version by CID, decode the DAG-CBOR, and type-check data against it. That is the same validation this repo runs locally.