Space member role
Roles in a space: tiers, defining and attaching roles, granting and revoking them, and what a role gives its holder.
What a role is
A role is a named position that a person or agent can hold in a space: team member, helper, organizer, project lead. Every role belongs to one of three tiers below admin — maintainer, member or observer — and the tier is what decides what the holder may do. The name is what people see; the tier is what the system uses.
Roles are defined once, as nanopublications, and can then be attached to any number of spaces. The same "helper" role, say, serves many spaces without being redefined.
Defining a role
A role is defined with the "Declaring a space member role" form. It asks for a label, a short name such as "member", a heading such as "Members" under which holders are listed, and the tier — maintainer, member or observer, with observer as the default.
The definition also fixes how a grant is written: the statement that says someone holds the role, either from the person to the space ("Alice is a member of X") or from the space to the person ("X has member Alice"). Optionally it names a template for making grants, which is what puts an "add …" button on space pages.
Attaching a role to a space
A defined role does nothing until a space adopts it. An admin attaches it with a single statement, gen:hasRole, and from then on it can be granted in that space and appears in the space's role listings. Roles can also arrive bundled in a preset, together with the views a space uses.
An admin can detach a role again with gen:detachedRole. The newer of the two statements wins, and detaching removes the role's availability along with every grant that depended on it.
Granting a role
Granting is one nanopublication with one statement, in the form the role definition prescribes. On a space page it is done with the role's "add …" action; the form asks only for the person.
Who may grant follows the tiers: an admin may grant any role, a maintainer may grant member and observer roles, a member may grant observer roles. Observer is the one role people may take for themselves, by publishing the grant about themselves — which is how someone declares interest in a space before anyone has invited them.
Roles with their own vocabulary
The statement a role uses to express a grant can be any property, including one from another vocabulary. The network then needs to know which side of the statement is the space and which the person, and it only knows that for a fixed set of common properties. For any other, a grant must carry that information itself, or it is silently ignored — it never reaches the space page, and nothing reports why.
A role's assignment template takes care of this: it records the direction in the template, and every grant made through it carries the note along. Grants written by hand need to include it explicitly.
When a grant counts
A grant is honoured only if the person who published it held a high enough tier in that space at the time, judged by the key that signed it. Grants failing this test are kept on the network but have no effect. The rule is what makes a role listing trustworthy: nobody can list themselves as a maintainer.
A person whose key is not yet approved by the network is shown as pending. Their grant is visible, but nothing they publish is counted until approval takes effect — except declaring themselves an observer, which counts straight away. Approval takes effect when the network next recomputes its trust state — minutes, sometimes longer.
Revoking a role
A role is taken away with a revocation: a nanopublication naming the space, the person and the exact role. Anyone may revoke a role held by someone of a lower tier than their own, and anyone may revoke their own role at any tier. Admin roles are the exception — only another admin can revoke one, apart from stepping down — and the admins named in the space's founding definition cannot be revoked at all.
Revocations and grants are ordered by time, so a grant published after a revocation restores the role. Nothing is deleted: the history of who held what, and when, remains readable.
What a role gives its holder
Three things follow from a role. The holder sees the actions that are open to their tier on the space's pages — a button visible to members is hidden from observers. Content gated to the space's members includes what they publish: their paragraphs in shared documentation, their terms in a vocabulary. And they may in turn grant roles below their own tier.
Admins and maintainers can additionally attach views and presets to the space's pages and declare what the space maintains. An observer holds none of these; the role is a declaration of interest, not a permission.
This page is a copy of the topic Space member role of the Nanopublication Docs. Each paragraph is a nanopublication. In Nanodash you also find their examples, related paragraphs, and version history, and members of the nanopub space can edit them there.