SpiceDB v1.0 wildcard permissions now require namespace scoping — how should legacy schemas be migrated without silent access changes?

Answer to the Core Question

SpiceDB v1.0 no longer treats an unscoped wildcard permission: * as a global default. The server now requires an explicit namespace prefix. Legacy schemas that still contain permission: * will either be rejected as a syntax error or, if accepted, will be interpreted as permission:current-namespace:*, which usually results in UNKNOWN or DENIED responses. To avoid silent access changes you must:

1. Locate every permission: * declaration.
2. Replace it with permission:namespace:* where namespace is the intended scope.
3. Validate the updated schema with the v1.0 engine (see zed schema validate).
4. Perform a dry-run against your existing relationship tuples.
5. Ensure client libraries are at least the v1.0 release that aligns with the server's wildcard semantics.

Legacy Patterns: Rejected vs. Silently Re-evaluated

• Rejected outright: A top-level permission: * without a namespace prefix that violates the new syntax rules. The server returns a SCHEMA_ERROR during validation.
• Silently re-evaluated: A wildcard that is syntactically valid but implicitly scoped to the current namespace. This often turns a previously granted permission into DENIED because the namespace scope is now narrower.

Dry-Run & Validation Strategy

1. Schema validation:

   zed schema validate --schema updated_schema.zed
   

   This checks syntax against the v1.0 engine and will surface any outright rejections.
2. Tuple consistency test: Create a temporary SpiceDB instance with the same tuples as production:

   zed server --data-dir tmp-data && zed relation-tuple import --file tuples.json
   

   Then run a set of representative Check calls that previously succeeded:

   zed check "user:alice" "resource:doc1" "read"
   

   Compare the result to the same call against a v0.9.x instance.
3. API side-by-side comparison: Use a lightweight script that sends identical requests to both versions and logs any divergence. A difference in ALLOW vs. DENIED indicates a silent change.

Client Library Compatibility

Wildcards are interpreted on the client side when building requests. The v1.0 server expects the client to send the fully-qualified permission string (e.g., project:read). Client libraries older than 1.0 may still send read alone, which the server will treat as a namespace-scoped wildcard, leading to denial. Therefore, upgrade all client SDKs to the latest 1.0.x release or later, and verify that the library's wildcard handling matches the server's expectations.

Practical Checklist

• Run zed schema list-permissions to find all wildcard uses.
• Update each to include the correct namespace.
• Validate with zed schema validate.
• Deploy to a staging environment and run the dry-run tests.
• Once all tests pass, promote the schema to production.

One Missing Diagnostic Detail

To fine-tune the migration you'll need to know which namespaces are actually in use for each permission that is currently wildcarded. If you can provide a mapping of permission names to their intended namespaces, the replacement step can be automated more precisely.