Permission line syntax
Use this page to write a permission line and check what each form grants.
A permission line is one JSON object in the permissions array of an
iam.Roles document. The line grants one action on one doctype path,
with an optional row scope and an optional path subtraction.
This page gives the exact grammar the parser accepts and the effect of each form.
Line structure
Section titled “Line structure”A line carries four parts. action and on are required; scope and
except are optional.
{ "action": "<action>", "on": "<domain>.<path>", "scope": ["$<alias>"], "except": ["<domain>.<Doctype>"] }| Part | Required | Form |
|---|---|---|
action |
yes | read, create, update, delete, * (all actions), or a named action such as activate or publish_artifact. Matching is exact; only * is a wildcard. |
on |
yes | A dot-separated path: domain, then doctype segments. Domain names are lowercase with dashes; doctype segments are CamelCase. |
scope |
no | An array of $<alias> strings. Each alias names a scope declared on the leaf doctype. Aliases combine with OR. |
except |
no | An array of concrete domain.Doctype paths. Each entry removes its subtree from the line. |
The parser normalizes every line to this shape. Three rules apply to all forms:
- A missing
scopemeans every row. $allin ascopearray collapses the line to unrestricted.- An
exceptentry never grants anything. It only shrinks the line it sits on.
The on path
Section titled “The on path”| Form | Matches |
|---|---|
crm.Deal |
The crm.Deal doctype. |
crm.Deal.Comment |
The nested child doctype only. |
crm |
Every doctype in the crm domain. |
crm.Project |
crm.Project and every nested child such as crm.Project.Comment — a parent path covers its subtree. |
*.* |
Every doctype in every domain. The only wildcard form. |
Rules the validator enforces:
- The domain segment must match
[a-z][a-z0-9-]*. Path segments must match[A-Z][a-zA-Z0-9]*(CamelCase). - The wildcard domain
*is valid only with the wildcard doctype: the full path must be*.*. A mixed form such as*.Dealis an error. - A
*.*line is a wildcard line. The role-authority guard lets only a caller whose own role reaches*.*write one.
The scope field
Section titled “The scope field”The array form is required on every write path. The single-string form
("scope": "$mine") is a legacy shape that stored roles may still
carry; a role write with a string scope fails with must be an array.
| Form | Rows the line reaches |
|---|---|
| absent | Every row. |
"$all" |
Every row. Same as absent. |
["$mine"] |
Rows that match the mine scope declared on the leaf doctype. |
["$mine", "$global"] |
Rows that match mine or global — the aliases OR together. |
["$all", "$mine"] |
Every row. Any $all entry collapses the whole array. |
Each alias must be declared in the scopes: block of the leaf doctype.
The validator rejects an unknown alias at authoring time; enforcement
expands it against the live definition at request time. A role never
writes its own query predicate. See Row scopes
for the declaration grammar.
The except field
Section titled “The except field”| Rule | Detail |
|---|---|
| Entry form | A concrete domain.Doctype path. At least two segments; no * anywhere. |
| Matching | An entry prefix-matches like on: an entry on core.DocType also excludes core.DocType.Comment. |
| Effect | A target that matches any entry never matches the line, even when it matches on. |
| Validation | Entries are checked at parse time. A malformed entry fails the role write. |
except is path arithmetic, not a deny system. It lets a scoped
re-grant on the same paths apply next to a blanket line.
Examples and effects
Section titled “Examples and effects”| Permission line | Effect |
|---|---|
{"action": "read", "on": "production.Project"} |
Read every row of production.Project, and of its nested child doctypes. |
{"action": "read", "on": "production.Project", "scope": ["$mine"]} |
Read only rows that match the mine scope. A list shows only those rows. A read of another row answers 404. |
{"action": "read", "on": "production.Project", "scope": ["$mine", "$global"]} |
Read rows the actioner owns, plus rows with no owner. |
{"action": "read", "on": "production.Project", "scope": "$all"} |
Read every row — the explicit form of an omitted scope. Legacy string form; use the array form in writes. |
{"action": "read", "on": "hr"} |
Read every doctype in the hr domain. |
{"action": "update", "on": "*.*", "except": ["core.Domain", "core.DocType"]} |
Update every document except the two definition surfaces and their nested children. |
{"action": "*", "on": "*.*"} |
Every action on every doctype. The seeded admin role holds this line. |
{"action": "activate", "on": "core.DomainGrant"} |
Run the named action activate on core.DomainGrant. Reads, creates, updates, and deletes stay ungranted. |
{"action": "create", "on": "crm.Deal", "scope": ["$mine"]} |
Create a deal. The scope is not enforced at create time — no row exists to check. It is an intent channel that a Lua create hook reads through ctx.actor.scope. The domain check reports a warning for such lines. |
Enforcement answers differ by denial class:
- No line matches the action and doctype at all →
403on the gated surface. - A line matches, but the row misses its scope (single-document
operations) → the non-disclosing
404. - A list query → the scope compiles into the query. The list stays
scope-narrowed, possibly empty. A scoped list never turns into a
403.
Complete example
Section titled “Complete example”A role for a helpdesk team. The helpdesk.Ticket doctype declares the
named scope unresolved; helpdesk.Ticket.Comment declares mine.
{ "name": "support_agent", "level": 20, "visible_tags": ["default"], "permissions": [ { "action": "read", "on": "helpdesk.Ticket" }, { "action": "create", "on": "helpdesk.Ticket" }, { "action": "update", "on": "helpdesk.Ticket", "scope": ["$unresolved"] }, { "action": "delete", "on": "helpdesk.Ticket.Comment", "scope": ["$mine"] } ]}A holder of this role can:
-
Read every ticket, including every ticket’s comments — the
readline covers the child doctype through prefix matching. -
Create tickets. The create is unrestricted.
-
Update a ticket while the row matches the
unresolvedscope, for example a ticket whosestatusis notclosed. An update to a closed ticket answers404. -
Delete their own comments — rows where the comment’s
minescope matches, for example rows the holder authored.The same holder cannot:
-
Delete tickets — no
deleteline reacheshelpdesk.Ticket, and a delete never rides theupdateline. -
Delete another agent’s comment — the
minescope misses, so the answer is404. -
Update a closed ticket — the
unresolvedscope misses. -
Read or write anything outside
helpdesk.Ticketand its children — any other doctype answers403. -
See fields tagged beyond
default—visible_tagsis["default"].
Field visibility
Section titled “Field visibility”Field visibility is not part of a permission line. The role carries one
visible_tags array; each field carries tags. A field is visible
when all of its tags sit in the role’s tags. The default role tags are
["default"]; the wildcard tag ["*"] sees every field. A write into
an invisible field answers 403. See
Field visibility with tags.
Related
Section titled “Related”- Roles and permission lines — edit role documents.
- Row scopes — declare and reference the scopes.
- Field visibility with tags — the per-field mask.