Skip to main content

0035: Permissions Schema vs. Data Management

Date: 2025-11-08

Status: Proposed

Context​

Zanzibar-style systems like SpiceDB operate on two distinct concepts: a "schema" (or permission model) and "relationship data" (tuples).

  • The schema defines the types of objects, their possible relationships, and how permissions are computed (e.g., "an editor of a folder is also a viewer of any document within that folder").
  • The data consists of the actual relationship tuples (e.g., "user:alice is an editor of folder:marketing").

We need to decide how these two types of information are managed. Allowing tenants to modify the core permission schema at runtime could lead to security vulnerabilities, unpredictable system behavior, and make the permission logic difficult to reason about.

Decision​

We will enforce a strict separation between the management of schemas and data.

  1. Schema is Static and Developer-Defined: The permission schema will be treated as a static artifact, defined in code (e.g., a .zed file for SpiceDB). It will be loaded into the ReBAC engine at deployment time by a trusted, internal process. The schema is part of the application's definition and is not exposed or modifiable via a public API.

  2. Data is Dynamic and API-Managed: Relationship data (tuples) is dynamic. It will be created, read, and deleted at runtime via the permissions-service's public API (e.g., POST /relationships/write). The service will enforce business logic (like multi-tenancy checks) before writing these tuples to the ReBAC engine.

Consequences​

Positive​

  • Security & Stability: Prevents tenants from altering the fundamental permission logic of the platform, which could otherwise lead to privilege escalation.
  • Predictability: The rules for how permissions are calculated are consistent and version-controlled with the application code.
  • Clear Separation of Concerns: Creates a clear boundary. Developers define how permissions work; users and services define who has what permission.

Negative​

  • Less Flexibility for Tenants: Tenants cannot define their own custom object types or complex permission inheritance rules. This is an acceptable trade-off for platform stability and security.
  • Deployment Coordination: Changes to the permission model require a new deployment to apply the schema changes. This is the desired behavior, as schema changes should be treated with the same rigor as code changes.