Spaces and Paths
A space is all the documents that one account key owns, and this page covers paths, the home document, directories and the path rules that clients follow.

A space is the set of documents that one account owns. Every address in it has the form hm://<account>/<path>. For example, hm://z6Mk…/notes/sushi is the document at the path /notes/sushi in the space of the account z6Mk…. The account and the space are the same key seen from two sides: the identity that signs, and the place where its documents live.

This page explains how documents are named inside a space.

Spaces, paths and the home document

Every address is hm://<space>/<path>. The home document is the address with an empty path.

Paths are plain strings. /cars and /cars/honda are two independent documents, and the daemon keeps no tree of documents. A directory listing is a query for all addresses that start with a path. A parent gets no authority over its children from the path alone. There are two exceptions:

    Capabilities apply by path segment. A grant at /a covers /a/b and does not cover /ab.

    Typed documents apply their childAttributesSchema to children by path; see Typed documents.

Clients follow these path rules:

    A path starts with / and does not end with /. It may not contain single or double quotes, backslashes, NUL, tab, CR or LF. The daemon rejects any Ref that breaks these rules.

    The daemon reads a path that is a single segment decoding as a TSID (14 or 15 base58 characters) as a comment or contact record.

    A private document must use a single path segment.

    The apps use a leading - for local draft paths.

    The apps refuse to publish a path that starts with -, . or _.

The exact path rules are in the path row of the ref type page. The first segments that a site reserves are in URLs.

The home document

The home document is the document at the empty path of a space, hm://<account>. Its first change, the genesis, is an empty Change with ts 0. Every device of the account computes the same one; see Documents. A home document may not be deleted (a tombstone) and may not be a redirect. It can never be private. When the space is published as a site, the home document names the web address in its siteUrl metadata key.

The home document is separate from the profile. The profile gives the account its name and picture. The home document gives the space its content.

Directories

A directory is the set of documents whose paths sit under a given path. A query by path prefix finds them. The daemon stores no tree, so a directory is only a listing. A query block shows such a listing inside a document, and the /:directory view suffix in URLs asks for one.

Who may write in a space

By default only the key that owns the space can publish into it. The owner lets other keys write with capabilities, each limited to a path. Joining or following a space grants nothing; see Contacts.

Working with spaces

seed-cli document create -f page.md -p /notes/sushi --name "Sushi" # publish at a path in your space seed-cli children <uid> -p /notes # the documents one level under /notes seed-cli query <uid> -p /notes -m AllDescendants # everything under /notes seed-cli document get hm://<uid>/notes/:directory # the same listing as a document view


    Seed app. In the Seed app, the /:directory view of a document lists the documents under its path.

    CLI. The commands above are in Seed CLI.

    Seed API. The Query request lists the documents of a space by path prefix, with a mode of Children or AllDescendants. See Seed API and the query type page.

See also

    Identity: the key behind a space.

    Documents: Changes, Refs, versions and generations.

    URLs: how a space and a path appear in a link.

    Permissions: who may publish at a path.

    Sites: a space published at a web domain.

    ref: the blob that places a document at a path.

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

Unsubscribe anytime

Attributes
name
Spaces and Paths
summary
A space is all the documents that one account key owns, and this page covers paths, the home document, directories and the path rules that clients follow.