From 4221f9d5aaa3345092d60e896ea58f7e5788a30d Mon Sep 17 00:00:00 2001 From: ivanauth Date: Mon, 1 Dec 2025 15:39:25 -0500 Subject: [PATCH] docs: add underscore prefix convention for private identifiers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- pages/spicedb/concepts/schema.mdx | 35 +++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) diff --git a/pages/spicedb/concepts/schema.mdx b/pages/spicedb/concepts/schema.mdx index e0c80791..fa2f8bf8 100644 --- a/pages/spicedb/concepts/schema.mdx +++ b/pages/spicedb/concepts/schema.mdx @@ -437,6 +437,41 @@ Examples: to a _computed_ set of subjects. +### Private/Internal Identifiers + +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. + +This convention is useful for: + +- **Synthetic permissions**: Permissions that exist only to compose other permissions +- **Internal relations**: Relations not meant to be directly referenced by application code +- **Implementation details**: Parts of your schema that may change without affecting the public API + +```zed +definition document { + relation viewer: user + relation _internal_viewer: user // private: internal use only + + permission _can_view = viewer + _internal_viewer // private: synthetic + permission view = _can_view // public API +} +``` + + + The underscore prefix is purely a naming convention to signal intent to other + developers. SpiceDB does not treat underscore-prefixed identifiers differently + at runtime—they can still be used in relationships and permission checks like + any other identifier. + + +#### Identifier Rules + +- Identifiers can begin with a lowercase letter (`a-z`) or underscore (`_`) +- After the first character, identifiers can contain lowercase letters, numbers, and underscores +- Identifiers must be 3-64 characters long and end with an alphanumeric character +- Valid: `_ab`, `_private`, `_internal_relation`, `_helper123` +- Invalid: `_` (too short), `_a` (too short), `_trailing_` (cannot end with underscore) + ## Comments ### Documentation Comments