Skip to content

Commit 4221f9d

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 <noreply@anthropic.com>
1 parent f18bbfb commit 4221f9d

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

pages/spicedb/concepts/schema.mdx

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -437,6 +437,41 @@ 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+
relation _internal_viewer: user // private: internal use only
454+
455+
permission _can_view = viewer + _internal_viewer // private: synthetic
456+
permission view = _can_view // public API
457+
}
458+
```
459+
460+
<Callout type="info">
461+
The underscore prefix is purely a naming convention to signal intent to other
462+
developers. SpiceDB does not treat underscore-prefixed identifiers differently
463+
at runtime—they can still be used in relationships and permission checks like
464+
any other identifier.
465+
</Callout>
466+
467+
#### Identifier Rules
468+
469+
- Identifiers can begin with a lowercase letter (`a-z`) or underscore (`_`)
470+
- After the first character, identifiers can contain lowercase letters, numbers, and underscores
471+
- Identifiers must be 3-64 characters long and end with an alphanumeric character
472+
- Valid: `_ab`, `_private`, `_internal_relation`, `_helper123`
473+
- Invalid: `_` (too short), `_a` (too short), `_trailing_` (cannot end with underscore)
474+
440475
## Comments
441476

442477
### Documentation Comments

0 commit comments

Comments
 (0)