Part of Stem. This page defines the comment kind. A comment is a resource of its author: an unnamed node under the author's root whose Snapshot value says what it is about and what it says. Its readers are the readers of the thing it is about. The formal schema of this kind's state is attached as the schemaDefinition of this page.

Descriptor

{
  "name": "Comment",
  "description": "A remark on a resource at a version, threaded by reply, owned by its author.",
  "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": "dep" },
    { "path": "/replyParent", "kind": "dep" },
    { "path": "/body", "kind": "link" }
  ]
}

State

field	type	required	meaning
`target`	node-ref	yes	The resource the comment is about, optionally at the version the author saw.
`threadRoot`	node-ref	no	The first comment of the thread. Omitted on a top-level comment.
`replyParent`	node-ref	no	The comment this one replies to. Omitted when it equals `threadRoot`.
`body`	list of block/comment	yes	The content. Blocks may carry `hm://` embeds, links and mentions and `ipfs://` files, which the handler turns into links.

The comment's author, timestamp and identity are not in the value: the author is the Node's signer, the timestamp is the Snapshot's ts, and the identity is the node id, the CID of the comment's creating Node blob; hm://<author>/<nodeId> is the comment's URL.

Rules

A comment is a node in the author's own space whose parent is the author's root id and which has no name. Anyone may comment on anything they can read: creating the node needs write on the author's own root, which the author has.

At creation the author must be in the readers of target; a comment whose author cannot read its target is stashed, not indexed, and is retried when a grant arrives.

access is target: the comment's readers are the readers of the targeted node, evaluated at read time, plus the audiences of any grants on the comment itself. When the document becomes public, so does its discussion; when it is shared with one more key, that key sees the discussion. An author who wants a narrower audience publishes the comment with access own and a grant.

threadRoot and replyParent are dependencies: a reply is applied only after the comments it names are indexed. The thread is the set of comments sharing a threadRoot.

Editing a comment publishes a new Snapshot with the old one in prev and a new Node blob with the old Node in prev. Deleting publishes a Node with a tombstone target. Retention is latest: a following peer may keep only the newest Snapshot and what it depends on.

A comment targets a node id, so it follows the document through moves and renames. A comment pinned to a version keeps that version reference; the client shows it against the current state.

Block and range anchoring are unchanged: an Embed block in the body whose link carries a #blockId or #blockId[a:b] fragment anchors the comment, and the handler records the fragment on the embed link.

Today (HM24)

The Comment blob carried id (the TSID being replaced, on edits), space, path, version, threadRoot, replyParent, body and visibility. Identity was <author>/<tsid>, derived from the blob's bytes. Visibility was copied from the target at creation and never reconciled, so a document that changed visibility stranded or exposed its discussion. Under Stem the node id is the CID of the creating Node blob (a migrated comment takes the CID of the first blob of its TSID), space and path become the target node reference, visibility becomes the target access mode, and the edit chain becomes prev. Comments describes the rest of today's behaviour.

Example

A reply, as its Snapshot and its creating Node blob (the Node carries no id; its CID becomes the comment's id):

{
  "type": "Snapshot",
  "signer": { "/": { "bytes": "7QFo…" } },
  "sig": { "/": { "bytes": "…" } },
  "ts": 1759901000000,
  "schema": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/comment/value",
  "value": {
    "target": { "space": { "/": { "bytes": "7QHm…" } }, "node": "bafyreipgojjg5fcaioctiq3hgetmyqoaat5rup6ppb2tdbm72fqo3xo7cv", "version": "bafy2bzaced…" },
    "threadRoot": { "space": { "/": { "bytes": "7QGq…" } }, "node": "bafyrein6a6wfhym6l3vfz5zfkkibj5j6wjibagi3mnbqnspuq2idw52ijb" },
    "body": [
      { "id": "b1", "type": "Paragraph", "text": "Agreed, but see the fold rule.", "annotations": [] }
    ]
  }
}

{
  "type": "Node",
  "signer": { "/": { "bytes": "7QFo…" } },
  "sig": { "/": { "bytes": "…" } },
  "ts": 1759901000000,
  "kind": "hm://z6MkiAKDcRSzQ4zPZfnJcS5HYx5MwgN6MU9foHihJGrhqNBj/stem/kinds/comment",
  "parent": "bafyreiujzdegxdncf32epf3dhodzdocis2jhtlgmxgedn73u55xtplpft7",
  "target": { "kind": "snapshot", "snapshot": { "/": "bafy2bzacei…" } }
}

Descriptor

State

Rules

Today (HM24)

Example

See also