Node reference
A reference to a resource by its stable identity, a space and node id with an optional version, the structured form of the mutable URL used by links, redirects, policies and RPC inputs instead of paths.
Fetching schema…

Part of Stem. This page defines the node reference, the struct Stem uses wherever one record points at a resource.

A node reference names a resource by space and node id, optionally pinned to a version; with node omitted it names the space root.

Fields

field

type

required

meaning

space

principal

yes

The space that holds the node.

node

node id

no

The node within that space. Omitted to reference the space root.

version

version

no

An immutable version of the node's state.

Rules

A node reference without version means "the resource as it is now". With version it is immutable. It is the DAG-CBOR form of the mutable URL hm://<space>/<node>?v=<version>, and of the bare hm://<space>?v=<version> when node is omitted; the forms convert exactly. Redirect targets, comment targets, link targets, policy scopes and RPC inputs all use it, so moving or renaming a resource never breaks any of them. The version is ignored where a reference names an audience, as in the readers audience.

Today (HM24)

References are hm://<space>/<path> strings, sometimes with ?v=. A move breaks every one that was not pinned. Stem writes links with both the path and the node id (see Placement) and stores the id in records.

Example

{"space": {"/": {"bytes": "7QEE...Starlight"}}, "node": "bafyreiujzdegxdncf32epf3dhodzdocis2jhtlgmxgedn73u55xtplpft7", "version": "bafyreib3nq5mkq2w7e4w3slkz2n7m7xq6x4hw4x2x3vl6tz2cmkfnq5a3e"}

See also

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

Unsubscribe anytime