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