Part of Stem. This page defines the Kind descriptor, the record that tells the daemon how to treat every resource of a kind. Kinds are themselves resources of kind kind, and this schema is bound to the kind kind page as its state schema, so the system describes itself.

A Kind is the contract between a resource type and the daemon: it names the state representation, the state schema, the naming rule, whether children are allowed, the default access mode, the target pointer, the retention rule and the link rules.

Fields

field	type	required	meaning
`name`	string	yes	Human name.
`description`	string	no	What resources of this kind are for.
`state`	one of `changes`, `snapshot`, `any`	yes	Which node target the kind's nodes may use.
`schema`	hm URL	yes	Schema of the state: the attributes schema for `changes`, the value schema for `snapshot`.
`naming`	one of `named`, `unnamed`, `any`	no	Whether nodes carry a name. Default `any`.
`children`	boolean	no	Whether nodes may be parents. Default true.
`access`	node access	no	The default access mode for nodes of this kind. Default `inherit`.
`target`	string	no	JSON Pointer into the state naming the node this resource is about. Required when `access` is `target`.
`retention`	one of `history`, `latest`	no	What a following peer keeps. Default `history` for `changes`, `latest` for `snapshot`.
`links`	list of link rule	no	Where the handler finds references and what links they become.

How the daemon reads a descriptor

When a Node arrives, the handler resolves its kind URL to a Kind resource, then:

State. It accepts the Node's target only if the kind's state allows it. For heads it loads the Change graph and validates the merged attributes against schema; for snapshot it validates the Snapshot's value against schema and requires the Snapshot's own schema to be the same or an extension.

Naming and children. It rejects a named node of an unnamed kind and an unnamed node of a named kind. It rejects a Node whose parent is a node of a kind with children false.

Access. It uses access as the node's mode unless the Node blob overrides it (between inherit and own). A kind with access target must have a target pointer; the handler reads the node reference at that pointer in the state and makes the node's readers follow that node's readers.

Links. For each link rule it reads the value at path, finds node references, hm:// URLs and ipfs:// URLs there, and emits links of the rule's kind. Changes and Snapshots also emit their deps and prev as dep links without any rule.

Retention and sync. It tells the retention and sync layers whether superseded state may be dropped (latest) and which links are dependencies to fetch before the resource can be applied.

Nothing in that list is specific to documents or comments. A new kind is a new Kind resource plus a schema; the daemon enforces its semantics the day it is published. The kinds Stem ships are enumerated in Resource kinds; their descriptors are validated strictly, and the daemon may refuse a user-defined kind that asks for something it cannot yet do (such as a target pointer into a Change graph).

Rules

A node's kind is fixed at creation. A Kind resource may publish new versions; a Node refers to the kind by URL, so it follows the latest version, and a client may pin ?v= to freeze it. The schema URL may name a schema resource in Stem form or a library document with schemaDefinition. Kinds may extend one another by extending their schemas; there is no inheritance of the descriptor itself.

Today (HM24)

Each blob type has hand-written index code and the roadmap item "schemas as daemon resources" wanted resources to be the primary entity so the daemon could index typed attributes generically. The Kind descriptor is that generic indexer's input, with sync and permission behaviour added to validation.

Example

The comment kind:

{
  "name": "Comment",
  "description": "A remark about another resource, threaded by reply.",
  "state": "snapshot",
  "schema": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/comment/value",
  "naming": "unnamed",
  "children": false,
  "access": "target",
  "target": "/target",
  "retention": "latest",
  "links": [
    {"path": "/target", "kind": "target"},
    {"path": "/threadRoot", "kind": "link"},
    {"path": "/replyParent", "kind": "link"},
    {"path": "/body", "kind": "mention"}
  ]
}

Fields

How the daemon reads a descriptor

Rules

Today (HM24)

Example

See also