A single schema works beautifully right up to the point where the documents team, the billing team and the platform team all need to change it in the same sprint. Then it becomes a merge conflict with a review queue. Composable schemas split it into files with owners, share the common shapes as partials, and assemble the whole thing at deploy time.
generated from the files on the left — this is what gets deployed
Each file has a team on it. The billing team changes billing's file and ships, without a platform engineer reviewing a diff they have no context for.
The review that matters still happens — on the shared file, which is exactly where you want the scrutiny concentrated.
Ownership, audit access, tenancy, soft-delete — the same handful of shapes recur across every object a
platform has. A partial is written once and imported.
When compliance changes what auditors may reach, it changes in one place instead of in eleven definitions that were supposed to match.
Composition happens before deployment. SpiceDB serves a single assembled schema, so nothing about the runtime, the checks or the consistency model changes.
This is a source-organisation feature, not a distributed one — which is why it is safe to adopt incrementally.
Check the current syntax against the docs. The partial and from … import
forms shown here illustrate the idea; composable schemas have moved as the feature matured, so take the
specification from authzed.com/docs rather than from this page.
It does not make the model simpler, only the source. The composed schema is exactly as complex as the one you would have written by hand. If a schema is hard to reason about, splitting it across files will not fix that — and can hide it.
A shared partial is a shared dependency. Changing one changes every definition importing it, which is the point and also the risk. Treat the common file the way you would treat a shared library: fewer owners, more review, and a test that exercises the composed result.