The data model

Hypermedia Schemas type values from the IPLD data model, the set of kinds DAG-CBOR can encode. There are nine kinds. Every value is exactly one of them.

kind	JSON / dag-json form	notes
`null`	`null`
`boolean`	`true` / `false`
`integer`	`42`	DAG-CBOR encodes ints and floats differently
`float`	`3.14`
`string`	`"hi"`	UTF-8 text
`bytes`	`{"/":{"bytes":"aGVsbG8"}}`	raw octets; base64 in dag-json
`list`	`[…]`	ordered sequence
`map`	`{…}`	keys are strings; ordered, unique
`link`	`{"/":"bafy…"}`	a CID: a content-addressed pointer to another block

Why these are all built in

link and bytes are primitives. The schema language does not define them. They have the same status string and integer already have.

The codec defines what a string is. The schema language only names the kind so a schema can constrain a field to it. link and bytes work the same way: the codec (DAG-CBOR) owns their existence and their wire form, and the schema language names them in the type vocabulary. The schema language has always been a set of names for codec-defined kinds, so adding two more names changes nothing structural.

The practical rule, spelled out in the schema language and encoding: never model the {"/":…} representation as a map inside a schema. A link is its own kind that happens to render as a map with a / key in dag-json. Treat it as atomic and opaque, like a string.

`integer` vs `float`

JSON has one number type. DAG-CBOR has two, encoded with different major types. Merging them into one kind loses round-trip fidelity: a value written as 1.0 might re-encode as the integer 1. So the data model keeps them distinct.

The weak spot is JavaScript and JSON, which cannot tell 3.0 from 3. So the reference validator checks integer strictly (Number.isInteger) and accepts any number as float. A real DAG-CBOR pipeline keeps the distinction in the bytes, where it is unambiguous.

`map` vs `struct`: one kind of data, two types

At the data-model level there is only map. DAG-CBOR has no separate object or struct kind. The schema language gives that one kind two types, because a map is used in two different ways:

struct: the keys are known field names, each with its own schema (properties). It is closed unless values opens it to extra keys.

map: the keys are data, and every value matches one schema (values).

Both validate the same bytes. The type tells a form which fields to show, tells a validator which keys are stray, and tells a generated type whether to emit named members or an index signature. See the schema language.

Links connect blocks

A link is a CID: a hash that names another block by its content. Links make Hypermedia data a DAG (directed acyclic graph) that spans many blocks. A schema field typed link says "here is a pointer to another block." It can also say "and that block's value should match schema X," which is a typed link (see references and link-schema). Examples: in example/document, author links to a person and previous links to another document. example/folder and example/file link to each other.

The schema language uses the same mechanism on itself. Schemas link to other schemas, so the type definitions form their own graph, addressed and resolved like the data they describe.

The primitive schemas: `/<kind>`

A kind like string is a name in the vocabulary. {"type":"string"} is the schema for a string value. The library ships that schema as a canonical, named block, one per kind. These are the primitives:

primitive	is exactly	typed by
`null`, `boolean`, `integer`, `float`, `string`, `bytes`	`{ "type": "<kind>" }`	`schema/scalar-schema`
`link`	`{ "type": "link" }`	`schema/link-schema`
`struct`, `map`, `list`	`{ "type": "<kind>" }`	`schema/struct-schema` / `schema/map-schema` / `schema/list-schema`

These are the standard library. Keep two layers apart:

schema/scalar-schema is a meta-schema variant. It describes the shape {type:<scalar>, …constraints}, so it is the type of string.

string is a primitive: {"type":"string"}. It is an instance of that shape, and it is the block you reference.

A field names the primitive with type: { "type": "hm://…/string" }. The URL both names the kind and points at the canonical string block. So a field's type is itself a resolvable reference, using the same mechanism as any other reference (see references and hm:// URLs). The example schemas all do this. In example/person, every field's type names a primitive or another schema.

The data model

Why these are all built in

integer vs float

map vs struct: one kind of data, two types

Links connect blocks

The primitive schemas: /<kind>

See also

`integer` vs `float`

`map` vs `struct`: one kind of data, two types

The primitive schemas: `/<kind>`