Field visibility with tags
A field can carry one or more sensitivity tags. A role declares which tags it
may see with its visible_tags list. Facet hides every other field on reads,
refuses writes into hidden fields, and removes their values from the audit
log. The rule fails closed: a tag that no role grants hides the field from
everyone.
When to use this
Section titled “When to use this”- A field holds data that only some roles may see, for example a salary.
- You want one visibility rule that every surface applies the same way.
- You need the same hiding in the audit log, not only in live reads.
Before you start
Section titled “Before you start”- Field definitions. You edit them — see Designing doctypes.
- Role content. You edit it — see Roles and permission lines.
1. Tag the field
Section titled “1. Tag the field”# hr.Employee definitionfields: name: type: string salary: type: money currency: EUR tags: ["salary"]A field without tags carries the tag default.
2. Grant the tag on a role
Section titled “2. Grant the tag on a role”{ "name": "hr_partner", "visible_tags": ["default", "salary"]}A role that must not see the field keeps the default visible_tags of
["default"].
3. Check what each role sees
Section titled “3. Check what each role sees”| Caller | Reads name |
Reads salary |
|---|---|---|
hr_partner (["default", "salary"]) |
yes | yes, with its value |
team_lead (["default"]) |
yes | the field is absent from the response |
Explanation
Section titled “Explanation”The visibility rule
Section titled “The visibility rule”A field is visible when every one of its tags sits in the role’s
visible_tags. The wildcard list ["*"] sees every field. Everything else
fails closed.
Read masking
Section titled “Read masking”Facet omits invisible fields at every nesting level: object properties, array items, and dictionary values. An invisible parent hides its whole subtree. Content keys that the definition does not know are omitted too, for every real principal.
Write guards
Section titled “Write guards”- A write into an invisible field is refused with
403. The error names the content path. An explicitnullcounts as a write. - The guard runs on the raw submitted body before format validation. A caller
that cannot see a field never learns its type contract from a
422. - A transition guard compares the state before and after the write. It resolves members inside object values, dictionary keys, and secret markers to the field that owns them. A change that lands inside an invisible field is refused.
- Trusted lifecycle work still populates invisible fields: defaults, computed fields, and hooks.
Audit redaction
Section titled “Audit redaction”The mutation log stores real values. Facet removes invisible values per
calling principal when it reads the log. The response lists the removed
content paths in a redacted metadata block. Each entry is an array of path
segments — the same shape the diff paths use.
| Row shape | What the caller sees |
|---|---|
| Full content row (create, snapshot, delete tombstone) | invisible values removed at every level; a visible parent keeps its visible part |
| Update diff | a set entry at an invisible path keeps its path but loses its value |
| Missing definition | all values removed — fail closed |
No marker enters the stored content. The redacted list is the only trace of
the removal.
Tags are not secrets
Section titled “Tags are not secrets”Tags hide a field per role. Two field kinds hide from everyone:
- A
secretfield never stores its value in a document or in the log. - A
write_onlyfield accepts input and never comes back on reads.
See Secret and write-only fields.
Example
Section titled “Example”An employee record carries name and the tagged salary field from step 1.
hr_partnerreads the employee. The response holdsnameandsalarywith its value.team_leadreads the same employee. The response holdsnameonly. There is nosalarykey, not a null.team_leadsends a patch that setssalarytonull. Facet answers403and names the path: an explicit null is a write.team_leadopens the employee history. The salary rows show without values, and theredactedblock names the paths.hr_partnerreads the same history and sees the values.
Troubleshooting
Section titled “Troubleshooting”A field is missing from a response
Section titled “A field is missing from a response”Check the field’s tags and the role’s visible_tags. A tag that the role
does not list hides the field.
A write answers 403 for a field you did not intend to touch
Section titled “A write answers 403 for a field you did not intend to touch”An explicit null in the body counts as a write. Omit the key instead.
A history row shows no value
Section titled “A history row shows no value”Redaction for your role. A role with the tag reads the value in the same row.
A hook fills an invisible field and works
Section titled “A hook fills an invisible field and works”Lifecycle work is trusted. Only caller writes and caller-driven transitions are guarded.
Related
Section titled “Related”- Roles and permission lines — where
visible_tagslives. - Row scopes — narrow rows the same way tags narrow fields.
- Auditing activity — where the
redactedblock appears. - Secret and write-only fields — hiding from everyone, not per role.
- Internals on GitHub: rbac.md, audit.md.