Blueprints scopes reference

Project versus organization scope, which resource types need which scope, and how the CLI resolves scope.

The blueprint file doesn't encode scope. Scope lives in .sanity/blueprint.config.json and is derived from which ID it holds.

Most resource types are project-scoped: they belong to a single project, and on an organization-scoped stack you give each one a project. A few require organization scope, such as scheduled (cron) functions. Roles are unscoped.

Deploying an organization-scoped type to a project-scoped stack fails; promote the stack first (see Promote a stack to organization scope). For the current scope of each resource type, see the typed API reference.

For each of organizationId, projectId, and stackId, the CLI takes the first source that resolves, in this order:

• Command-line flags (--organization-id, --project-id, --stack)
• Environment variables (SANITY_ORGANIZATION_ID, SANITY_PROJECT_ID, SANITY_BLUEPRINT_STACK_ID)
• IDs exported from the blueprint file module
• The local config file, .sanity/blueprint.config.json

Scope is derived as specifically as possible: if a project ID resolves, the scope is project; otherwise, if an organization ID resolves, the scope is organization.

When you promote a stack to organization scope, it remembers its original project. Project-scoped resources that don't set a project fall back to that project automatically, so your existing resources keep working. Set an explicit project on a resource to target a different one.