Skip to content

Commit ded56ab

Browse files
ivanauthclaude
andcommitted
docs: add underscore prefix convention for private identifiers
Document the ability to use underscore prefixes for definitions, relations, and permissions to signal that they are private/internal. This is a naming convention that helps developers distinguish between public API and internal implementation details in their schemas. Related: authzed/spicedb#2733 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
1 parent f18bbfb commit ded56ab

File tree

1 file changed

+40
-0
lines changed

1 file changed

+40
-0
lines changed

pages/spicedb/concepts/schema.mdx

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -437,6 +437,46 @@ Examples:
437437
to a _computed_ set of subjects.
438438
</Callout>
439439

440+
### Private/Internal Identifiers
441+
442+
SpiceDB supports using an underscore (`_`) prefix for identifiers to establish a convention for marking definitions, relations, or permissions as "private" or "internal". This is a naming convention only—it does not enforce any access restrictions.
443+
444+
This convention is useful for:
445+
446+
- **Synthetic permissions**: Permissions that exist only to compose other permissions
447+
- **Internal relations**: Relations not meant to be directly referenced by application code
448+
- **Implementation details**: Parts of your schema that may change without affecting the public API
449+
450+
```zed
451+
definition document {
452+
relation viewer: user
453+
454+
// Private relation - used internally for permission composition
455+
relation _internal_viewer: user
456+
457+
// Private synthetic permission
458+
permission _can_view = viewer + _internal_viewer
459+
460+
// Public permission built on private components
461+
permission view = _can_view
462+
}
463+
```
464+
465+
<Callout type="info">
466+
The underscore prefix is purely a naming convention to signal intent to other
467+
developers. SpiceDB does not treat underscore-prefixed identifiers differently
468+
at runtime—they can still be used in relationships and permission checks like
469+
any other identifier.
470+
</Callout>
471+
472+
#### Identifier Rules
473+
474+
- Identifiers can begin with a lowercase letter (`a-z`) or underscore (`_`)
475+
- After the first character, identifiers can contain lowercase letters, numbers, and underscores
476+
- Identifiers must be 4-64 characters long and end with an alphanumeric character
477+
- Valid: `_private`, `_internal_relation`, `_helper123`
478+
- Invalid: `_` (too short), `_trailing_` (cannot end with underscore)
479+
440480
## Comments
441481

442482
### Documentation Comments

0 commit comments

Comments
 (0)