You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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]>
Copy file name to clipboardExpand all lines: pages/spicedb/concepts/schema.mdx
+40Lines changed: 40 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -437,6 +437,46 @@ Examples:
437
437
to a _computed_ set of subjects.
438
438
</Callout>
439
439
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
+
<Callouttype="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
0 commit comments