Row scopes
A permission line reaches a whole doctype, or only the rows that match a condition. A row scope names that condition. The doctype declares its scopes once; a role references them by alias and never writes its own predicates.
When to use this
Section titled “When to use this”- A role may see or change only its own rows.
- A role may see rows that match a shared rule, for example every active project.
- Several roles share one row rule, and you want it declared once.
Before you start
Section titled “Before you start”- The grammar. You know the permission-line grammar — see Roles and permission lines.
- The declaration. The scopes must exist on the doctype definition before a role can reference them. The authoring steps live in Named scopes.
Explanation
Section titled “Explanation”Where scopes live
Section titled “Where scopes live”The doctype definition carries the scopes under scopes. Each entry is a
where filter over the doctype’s own fields:
# production.Project definitionscopes: mine: description: "Projects owned by the actioner" where: owner_id: "$self" global: description: "Projects with no owner" where: owner_id: "$null" active: description: "Projects in the active status" where: status: "active"Roles pick from this catalogue. They cannot add a predicate of their own on a
permission line. The where grammar:
| Value | Matches |
|---|---|
"active" |
The literal stored value. |
"$self" |
The acting account’s id. It matches both the reference form iam.Account.<id> and a bare id, so one scope works on reference and on string owner fields. |
"$my_teams" |
The values of a context set that the domain declares, resolved per request. An empty or unresolvable set matches no rows, also with ne. |
"$null" |
Rows where the field is absent or JSON null. Works with eq only. |
"$organizational_unit" |
The acting account’s folder-like path, for example /engineering/backend/. |
A where key can carry an operator suffix, as list filters do:
priority__gte, title__starts_with, price__between. A bare key means
equals. A field accepts exactly the operators that its declared filters
capabilities allow. Two reserved keys exist: $parent_id reads the parent
linkage, and $doc_id reads the row id. Both take eq or ne only.
What a permission line says
Section titled “What a permission line says”Read each line together with its effect:
{"action": "read", "on": "production.Project", "scope": ["$mine", "$global"]}This line lets a member read the projects they own and the projects with no owner.
{"action": "update", "on": "crm.Deal", "scope": ["$mine"]}This line lets a member update the deals they own, and no other deals.
{"action": "read", "on": "production.Project", "scope": "$all"}This line lets a member read every project. $all is the explicit
unrestricted form; an omitted scope means the same. Inside an array, $all
collapses the whole line to unrestricted.
How Facet applies a scope
Section titled “How Facet applies a scope”- Lists. The scope compiles to an SQL
WHEREfragment. A scoped list answers200with the matching rows, possibly none. Row scoping never turns into403. - Single reads, updates, deletes, and actions. The enforcer checks the row
against the scope. A row that fails answers the same
404as a missing document, so the answer never reveals that the document exists. - Create. No row exists yet, so the scope does not run at create. The scope
rides to the Lua create hook as an intent channel that can set field values,
for example the owner. The domain check reports one warning per scoped create
line on the
iamdomain. - Redefinition. Edit a scope on the doctype, and every role that references the alias uses the new predicate from the next request. No role edit is needed.
- Query-time narrowing. List and aggregate routes and the agent tools
accept
scope=<name>. It only narrows what the caller can already see. An unknown name answers422. - Credential-less requests. They run under the
anonymousrole.$selfresolves to the literal valueanonymous, which matches no account, so$selfscopes stay inert.$organizational_unitresolves to the root path/.
Example
Section titled “Example”An administrator scopes an editor role on production.Project:
- The author declares the
mine,global, andactivescopes above. - The role carries the read line with
["$mine", "$global"]and the update line with$mine, both from above. - A member with that role lists projects. Facet returns the projects the member owns plus every project with no owner, and nothing else.
- The member opens a project they own and edits it. The edit saves.
- The member opens a project another account owns. The read answers
404, although the project exists. - The member lists with
?scope=activeand gets only the active subset of what they can already see.
Troubleshooting
Section titled “Troubleshooting”A scoped list returns rows you did not expect
Section titled “A scoped list returns rows you did not expect”Aliases in an array combine with OR. Check whether one line carries more
aliases than you intended, or whether $all sits in the array.
A member gets 404 on a document that exists
Section titled “A member gets 404 on a document that exists”The row failed the scope check. This is the non-disclosing answer by design — see How Facet checks permissions.
The API answers Unknown scope
Section titled “The API answers Unknown scope”The scope name is not declared on the doctype in the line. Copy the name from the definition.
A scoped create line saves with a warning
Section titled “A scoped create line saves with a warning”Create ignores scopes by design. Move the row rule into a create hook — see Lifecycle scripts and guards.
Worked example: own projects via teams
Section titled “Worked example: own projects via teams”A project_manager role reads only the projects of the manager’s own team.
Projects belong to a team, and a team has member rows that name an account.
The rule needs two declarations — one on the domain, one on the doctype — and
then a role line names the scope.
The document model
Section titled “The document model”- Team → TeamMember is composition:
Teamis the aggregate root,TeamMemberits child (member_of: Team), and each member row holds anaccountreference toiam.Account. A dedicatedTeamMemberdoctype suits this because membership is a row with its own life and one account can sit in several teams. - Project → Team is a reference:
Project.teampoints atprojects.Team.
The diagram shows the two data relationships, the two declarations that read
them, and the role that names the scope. The authoring declarations (the
children/member_of pair, the reference field, the my_teams context set,
and the team_projects scope) are on
Named scopes.
The admin part follows.
The role line
Section titled “The role line”The project_manager role carries one read line on projects.Project:
{ "action": "read", "on": "projects.Project", "scope": ["$team_projects"]}team_projects is a scope the doctype declares, with
where: { team: "$my_teams" }. The $my_teams context set resolves, per
request, to the ids of the teams the caller belongs to.
What the manager sees
Section titled “What the manager sees”- The manager belongs to two teams. A list of
projects.Projectreturns the projects of both teams, and nothing else. - A direct read of a project in another team answers
404, although the project exists — the non-disclosing answer from How Facet checks permissions. - The manager moves to a new team. The next request resolves the new
my_teamsset and returns the new team’s projects. No role edit is needed.
Related
Section titled “Related”- Named scopes — declare scopes and their context sets on the doctype and domain.
- Roles and permission lines — the line grammar around
scope. - Field visibility with tags — narrow at the field level the same way.
- How Facet checks permissions — where the enforcers sit.
- Internals on GitHub: rbac.md.