Resource kinds
The eight core kinds of resource in Stem, what each one's Kind descriptor says about its state, naming, children, access, target and retention, and how a new kind is defined without changing the protocol.

Part of Stem. This page lists the resource kinds the daemon ships with and shows how every one of them is described by the same record, the Kind descriptor. A kind decides how a resource's state is represented and validated, whether it has a name and children, how its audience is derived, what it is about, what peers keep, and which fields become links.

A kind is a resource

A kind is itself a resource: a node of kind kind whose Snapshot value is a Kind descriptor. Every Node blob names its kind by the hm:// URL of that kind resource, and the kind is fixed for the life of the node.

The daemon has one indexing routine, the handler. It does not know what a comment or a contact is. It reads the descriptor and from it learns: which Node targets are allowed (state), what schema the state must satisfy (schema), whether a name is required or forbidden (naming), whether the node may be a parent (children), how to compute the node's readers (access, target), what a following peer must keep (retention), and where in the state to look for references (links). Sync and access semantics are therefore enforced per kind, from data.

The core kinds are published under this page so that their URLs are stable. A daemon treats them as well known, but it validates them the same way it validates any kind someone else publishes.

The core kinds

kind

state

named

children

default access

target

retention

space

changes

unnamed

yes

own

none

history

document

changes

any

yes

inherit

none

history

comment

snapshot

unnamed

no

target

/target

latest

contact

snapshot

unnamed

no

inherit

none

latest

file

snapshot

any

no

inherit

none

latest

schema

snapshot

named

yes

inherit

none

history

kind

snapshot

named

no

inherit

none

history

policy

snapshot

named

no

own

none

latest

Two of these kinds are structural. The space root is the one node every space has; its id is the CID of a deterministic creating Node blob, so it is derivable from the owner's key. Documents are the only kind whose state is a Change graph besides the root. Everything else is a Snapshot chain: an edit replaces the whole value and lists the previous Snapshot in prev.

What a kind cannot change

The descriptor refines behaviour inside fixed bounds. It cannot introduce a new Node target, a new link kind, a new access mode or a new access level; those are the closed unions node/target, link-kind, node/access and access-level, and changing them is a protocol change. A kind also cannot weaken the write rule: who may publish a Node blob is decided by the authority graph, never by the kind.

Defining a new kind


    Publish the state schema as a schema resource, or reuse one. For a Change-based kind this is an attributes schema in the sense of typed documents; for a Snapshot kind it is the schema of the whole value.

    Publish a kind resource whose Snapshot value is a descriptor pointing at that schema and stating the other seven choices.

    Create nodes with kind set to the new kind's URL. Any daemon that can fetch the kind resource and the schema indexes them with the generic handler, applies the declared access mode and retention, and emits the declared links.

No daemon code changes. This is the Stem commitment that new concepts arrive as schemas and linked records, not as protocol changes.

Today (HM24)

The shipping daemon has one indexer per blob type: Change, Ref, Capability, Comment, Contact, Profile and DagPB, each with its own rules for identity, visibility and links, described in Signed blobs. The roadmap records the decision to name all mutable things resources and to treat capabilities as a special category of resource. Stem keeps "resource" as the word and makes the per-type rules into data.

See also

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

Unsubscribe anytime