Schema deployment

Deploy your schema into your dataset to enable deep integration between your content model and Sanity apps.

Since version 3.88.0, Sanity Studio has supported deploying a representation of your content model, in the form of a schema, to your dataset. The schema commands became generally available in that release. It enables integration between your studios and apps like Dashboard and Canvas.

The schema commands belong to the sanity schemas group. They let you deploy your schemas at the workspace level to the matching combination of dataset and project ID, which makes them available to Sanity apps and APIs. Requires sanity 3.88.0 or later.

If you aren't logged in with sufficient privileges, provide a deploy token. A deploy token is enough; these commands don't need a write token:

SANITY_AUTH_TOKEN=YOUR_DEPLOY_TOKEN npx sanity@latest schemas deploy

Deploys schema documents to workspace datasets. If you've already run sanity login, you typically have deploy permission by default. In CI environments where sanity login hasn't been executed, you'll need to provide a deploy token.

Options:

• --workspace <name>: Deploy only the named workspace.
• --tag <tag>: Add a tag suffix to the schema ID, so you can test without overwriting an existing schema.
• --verbose: Show detailed deployment information, including the schemaId.

Examples:

# Deploy all workspace schemas
npx sanity@latest schemas deploy

# Deploy the schema for a specific workspace
npx sanity@latest schemas deploy --workspace default

# Deploy all workspace schemas
pnpm dlx sanity@latest schemas deploy

# Deploy the schema for a specific workspace
pnpm dlx sanity@latest schemas deploy --workspace default

# Deploy all workspace schemas
yarn dlx sanity@latest schemas deploy

# Deploy the schema for a specific workspace
yarn dlx sanity@latest schemas deploy --workspace default

# Deploy all workspace schemas
bunx sanity@latest schemas deploy

# Deploy the schema for a specific workspace
bunx sanity@latest schemas deploy --workspace default

Lists all schemas in the current dataset. Use it to find the schemaId that Agent Actions needs.

Options:

• --json: Get the schema as JSON.
• --id <schema_id>: Fetch a single schema by ID.

Examples:

# List all schemas
npx sanity@latest schemas list

# Get a specific schema
npx sanity@latest schemas list --id _.schemas.workspaceName

# Get schemas as JSON
npx sanity@latest schemas list --json

# List all schemas
pnpm dlx sanity@latest schemas list

# Get a specific schema
pnpm dlx sanity@latest schemas list --id _.schemas.workspaceName

# Get schemas as JSON
pnpm dlx sanity@latest schemas list --json

# List all schemas
yarn dlx sanity@latest schemas list

# Get a specific schema
yarn dlx sanity@latest schemas list --id _.schemas.workspaceName

# Get schemas as JSON
yarn dlx sanity@latest schemas list --json

# List all schemas
bunx sanity@latest schemas list

# Get a specific schema
bunx sanity@latest schemas list --id _.schemas.workspaceName

# Get schemas as JSON
bunx sanity@latest schemas list --json

Removes schema documents by ID. Useful when you need to remove schemas from Canvas or Agent Actions.

Options:

• --ids <schema_id_1,schema_id_2,...>: Comma-separated list of schema IDs to delete.
• --dataset <dataset_name>: Delete schemas from a specific dataset.
• --yes (-y): Delete schemas without prompting for confirmation. Required when the command runs without an interactive terminal, such as in CI; without it, the command fails.

Examples:

# Delete a single schema
npx sanity@latest schemas delete --ids _.schemas.workspaceName

# Delete multiple schemas
npx sanity@latest schemas delete --ids _.schemas.workspaceName,_.schemas.otherWorkspace.tag.taggedSchema

# Delete a single schema
pnpm dlx sanity@latest schemas delete --ids _.schemas.workspaceName

# Delete multiple schemas
pnpm dlx sanity@latest schemas delete --ids _.schemas.workspaceName,_.schemas.otherWorkspace.tag.taggedSchema

# Delete a single schema
yarn dlx sanity@latest schemas delete --ids _.schemas.workspaceName

# Delete multiple schemas
yarn dlx sanity@latest schemas delete --ids _.schemas.workspaceName,_.schemas.otherWorkspace.tag.taggedSchema

# Delete a single schema
bunx sanity@latest schemas delete --ids _.schemas.workspaceName

# Delete multiple schemas
bunx sanity@latest schemas delete --ids _.schemas.workspaceName,_.schemas.otherWorkspace.tag.taggedSchema

The --help output for this command still shows IDs in the form sanity.workspace.schema.workspaceName. That form is rejected. Use _.schemas.<workspaceName> or _.schemas.<workspaceName>.tag.<tag> instead.

Extracts the studio schema as a single JSON file, schema.json in the project root by default. It is the prerequisite for sanity typegen generate, which reads that file. See TypeGen. It does not write manifest files.

Options:

• --path <path>: Destination for the extracted schema file. Defaults to schema.json in the project root, or to schemaExtraction.path from sanity.cli.ts when that is set.
• --watch: Re-run the extraction as the schema changes.
• --workspace <name>: The workspace to generate a schema for.
• --enforce-required-fields: Treat fields marked as required as non-optional. Defaults to false.
• --force: Overwrite an existing schema file without prompting. Without it, an existing file prompts for confirmation, and the command fails outright when it runs without an interactive terminal, such as in CI.
• --format <groq-type-nodes>: Output format. groq-type-nodes is both the default and the only available format.
• --watch-patterns <glob>: Additional glob patterns to watch. Can be specified multiple times.

Examples:

# Extract the schema to schema.json in the project root
npx sanity@latest schemas extract

# Extract to a specific path
npx sanity@latest schemas extract --path ./src/sanity/schema.json

# Extract and re-run on schema changes
npx sanity@latest schemas extract --watch

# Extract the schema to schema.json in the project root
pnpm dlx sanity@latest schemas extract

# Extract to a specific path
pnpm dlx sanity@latest schemas extract --path ./src/sanity/schema.json

# Extract and re-run on schema changes
pnpm dlx sanity@latest schemas extract --watch

# Extract the schema to schema.json in the project root
yarn dlx sanity@latest schemas extract

# Extract to a specific path
yarn dlx sanity@latest schemas extract --path ./src/sanity/schema.json

# Extract and re-run on schema changes
yarn dlx sanity@latest schemas extract --watch

# Extract the schema to schema.json in the project root
bunx sanity@latest schemas extract

# Extract to a specific path
bunx sanity@latest schemas extract --path ./src/sanity/schema.json

# Extract and re-run on schema changes
bunx sanity@latest schemas extract --watch

The extracted manifest follows this structure:

interface CreateManifest {
  version: number        // Current version: 3
  createdAt: string      // ISO timestamp
  studioVersion: string | null  // installed sanity version
  workspaces: ManifestWorkspaceFile[]
}

interface ManifestWorkspaceFile {
  name: string
  title?: string
  subtitle?: string
  basePath: string
  dataset: string
  projectId: string
  schema: string        // filename with serialized schema
  tools: string         // filename
  icon: string | null
}

Two commands write manifest files:

• sanity deploy: Writes manifest files into your build output when deploying to Sanity hosting. It skips that step for --external deployments.
• sanity manifest extract: Writes manifest files to a directory you choose with --path. This is the only way to produce them without deploying to Sanity hosting.

Two more commands work with schemas and manifests:

Validates schema types in a workspace. sanity schemas deploy runs the same validation before deploying and reports the same output, so a schema error here also blocks a deployment.

Options:

• --workspace <name>: The workspace to validate.
• --format <pretty|ndjson|json>: Output format. Default: pretty.
• --level <error|warning>: Minimum reporting level. Default: warning.

Extracts the studio configuration as one or more JSON manifest files. This is the only command that writes manifest files without deploying to Sanity hosting, and it is intended for use with Create.

Options:

• --path: Destination directory for the manifest files. Default: dist/static.

• sanity deploy: Deploys a studio to Sanity hosting and includes schema deployment in the process. Use sanity deploy --external to register a studio you host yourself.
• sanity typegen generate: Creates TypeScript types from schema types and GROQ queries.

• You don't need to keep your manifest in version control since it's derived from your codebase.
• For embedded studios, the manifest has to be served at <studio-url>/static/create-manifest.json. Write it there with npx sanity@latest manifest extract --path. No other command writes those files.
• Serving the manifest at your own domain does not register the studio. An externally hosted studio has to be registered with npx sanity@latest deploy --external before Dashboard and Media Library can resolve its workspaces.
• Deploying, listing, and deleting schemas requires the deployStudio grant on sanity.project. A deploy token carries it; a write token isn't required. Extracting and validating schemas run locally and need no token.

• Failed to deploy schemas: The deployment failed. The underlying reason follows on the next line of output.
• Failed to deploy 1/3 schemas. Successfully deployed 2/3 schemas. Some workspaces deployed and others didn't. The output names which ones failed.
• No permissions to write schema for workspace "..." in dataset "...". For multi-project workspaces, set SANITY_AUTH_TOKEN environment variable to a token with access to the workspace projects. The token lacks the deployStudio grant, or it doesn't cover every project a multi-project workspace spans.