Extends
| type Blob type tag, always `Ref`. | Ref | optional |
| signer Public key of the account or device that signed the blob. | inherited | |
| sig Signature over the canonical DAG-CBOR of the blob with `sig` set to 64 zero bytes. | inherited | |
| ts When the signer says the blob was made, in Unix milliseconds; not checked against real time. | inherited | |
| space Space the path belongs to; omitted when the signer is the space owner. | optional | |
| path Document path within the space, starting with `/`; empty for the home document. | optional | |
| genesisBlob CID of the genesis Change of the document at this address. | optional | |
| capability Informational CID of the capability authorizing the signer; the daemon ignores it. | optional | |
| heads CIDs of the document's current head Changes; empty for a tombstone or redirect. | of | |
| redirect Where readers are sent instead, making this Ref a redirect. | optional | |
| generation Orders the lives of an address: the highest generation wins; clients use the current time in ms for a new document. | optional | |
| visibility Empty for public or `Private`; a private Ref must have a single-segment path. | optional |
A Ref is the blob that gives a document an address. Changes describe history. A Ref says "this path in this space currently shows these heads". The daemon checks Refs for permission. A Ref is what makes a document appear in listings and search, and you publish one to branch, delete, move or redirect a document.
This page defines the ref blob type, a Hypermedia network blob that extends the signed blob envelope. Its formal schema is attached as the schemaDefinition in this document's metadata, so the app can show it and sign values of this type.
Three shapes are valid. A version Ref has genesisBlob and one or more heads, and asserts a version. A tombstone has genesisBlob and no heads, and deletes the document at that path once it is newer than the last live Ref of the same generation. A redirect has genesisBlob, no heads and a redirect target. With republish set, a redirect keeps showing the target's content under this address and does not count as a deletion. The home document (empty path) may be neither a tombstone nor a redirect.
space is omitted when the signer is the space owner. Otherwise the signer must hold a capability for the path, or the Ref is stashed and has no effect. The capability field is informational only and the daemon ignores it, so publish the Capability blob itself. generation orders the lives of an address: the highest generation wins. The daemon's CreateRef asks for a higher generation before it replaces a document with a different genesis, and clients use the current time in milliseconds for a new document. visibility is empty for public or Private, and a private Ref must have a single-segment path. Paths must start with /, must not end with /, and may not contain single or double quotes, backslashes, NUL, tab, CR or LF. Documents gives the reasoning behind each rule.
See also
Documents: heads and versions, generations and takeover, branching, deleting, moving.
Permissions: who may sign a Ref for a path.
Privacy: what a private Ref means.
Seed API: Resource returns a document, a redirect or a tombstone.
change: the blobs a Ref's heads point at.
ref/redirect-target: where a redirect sends readers.
Do you like what you are reading? Subscribe to receive updates.
Unsubscribe anytime