Part of Stem. This page defines the schema kind. A schema resource is a node whose state is a Hypermedia schema, an instance of the meta-schema. It is the "schemas as daemon resources" item of the roadmap. The formal schema of this kind's state is attached as the schemaDefinition of this page, and it is the meta-schema itself.

Descriptor

{
  "name": "Schema",
  "description": "A Hypermedia schema as a resource.",
  "state": "snapshot",
  "schema": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/schema/value",
  "naming": "named",
  "children": true,
  "access": "inherit",
  "retention": "history",
  "links": [
    { "path": "", "kind": "schema" }
  ]
}

State

The value is any schema accepted by the meta-schema: a struct, map, list, scalar, link, include, union, variable or literal schema, written in the schema language. The one link rule has the empty JSON Pointer, meaning the whole value: every hm:// or ipfs:// reference anywhere in the schema emits a schema link, so a peer fetching a schema also learns which schemas it includes or extends.

Rules

The handler validates the value against the meta-schema strictly. A Snapshot whose value is not a valid schema is rejected, not stashed.

The resource's hm:// URL is the schema's name. Other schemas reference it with "type": "hm://<space>/<path>" or the mutable URL hm://<space>/<node-id>, and pin a version with ?v= or ipfs://<cid> exactly as in References and naming.

Names must be present: a schema is a type and types are named. Children are allowed so a schema can own its variants, as schema/struct-schema sits under schema.

Retention is history because other data pins schema versions. A peer that follows a schema keeps every version it has seen.

Resolution order for a type URL is: schema resource at that node; otherwise a document at that node with schemaDefinition in its metadata, which points at a schema blob. Both are supported. The document form stays for pages that want prose beside the schema, and this site uses it. New schemas should prefer the resource form when they need no page.

Validation of ordinary documents against their attributesSchema stays advisory in editors and strict in the reference validator, unchanged.

Today (HM24)

A schema was a document whose schemaDefinition metadata named a separate unsigned DAG-CBOR schema blob by ipfs:// CID, and typed documents pointed at the page with attributesSchema. The Onyx = HM26 note observed that this made schemas slow to resolve and asked for a convention closer to comments and profiles. The schema resource is that convention. Existing schema documents keep working through the fallback.

Example

{
  "type": "Snapshot",
  "signer": { "/": { "bytes": "7QHm…" } },
  "sig": { "/": { "bytes": "…" } },
  "ts": 1759904000000,
  "schema": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/schema/value",
  "value": {
    "type": "hm://hyper.media/struct",
    "properties": {
      "title": { "value": { "type": "hm://hyper.media/string" }, "required": true, "description": "Title of the talk." },
      "speaker": { "value": { "type": "hm://hyper.media/hm-url", "format": "hm-profile" }, "description": "The speaker's account." }
    },
    "description": "A talk."
  }
}

{
  "type": "Node",
  "signer": { "/": { "bytes": "7QHm…" } },
  "sig": { "/": { "bytes": "…" } },
  "ts": 1759904000000,
  "kind": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/schema",
  "parent": "bafyreidfyspsc5lkr4aqxvupctnwlavyf6rmpafqfjzczbttofjyu7jsjc",
  "name": "talk",
  "target": { "kind": "snapshot", "snapshot": { "/": "bafy2bzacel…" } }
}

Descriptor

State

Rules

Today (HM24)

Example

See also