Schema Deployment

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

With the launch of version 3.88.0, Sanity Studio gains support for deploying a representation of your content model, in the form of a schema, to your dataset. This allows for robust integration between your finely tuned studios and apps like Dashboard and Canvas.

The schema commands belong to the sanity schema group. They allow you to deploy your schemas at the workspace level to your corresponding combination of dataset and projectId, making them accessible to various Sanity apps and APIs.

For commands requiring a deploy token (when not logged in with proper privileges), use:

SANITY_AUTH_TOKEN=<your-deploy-token> sanity schema <command>

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 <workspace_name> - Deploy for a specific workspace. Essential for studios with multiple projectIds.
• --tag <tag> - Add a tag suffix to the schema id for testing without overwriting existing schemas.
• --manifest-dir <directory> - Directory with manifest file (default: ./dist/static). Crucial for embedded studios.
• --no-extract-manifest - Skip manifest generation when nothing has changed.
• --verbose - Show detailed deployment information, including the schemaId.

Examples:

# Deploy all workspace schemas
npx sanity schemas deploy

# Deploy schema for specific workspace
npx sanity schemas deploy --workspace default

# Use existing manifest file
npx sanity schemas deploy --no-extract-manifest

# Deploy all workspace schemas
pnpm dlx sanity schemas deploy

# Deploy schema for specific workspace
pnpm dlx sanity schemas deploy --workspace default

# Use existing manifest file
pnpm dlx sanity schemas deploy --no-extract-manifest

# Deploy all workspace schemas
yarn dlx sanity schemas deploy

# Deploy schema for specific workspace
yarn dlx sanity schemas deploy --workspace default

# Use existing manifest file
yarn dlx sanity schemas deploy --no-extract-manifest

# Deploy all workspace schemas
bunx sanity schemas deploy

# Deploy schema for specific workspace
bunx sanity schemas deploy --workspace default

# Use existing manifest file
bunx sanity schemas deploy --no-extract-manifest

Lists all schemas in the current dataset. This is important for identifying the schema id needed for agent actions.

Options:

• --json - Get schema as JSON
• --id <schema_id> - Fetch a single schema by id
• --manifest-dir <directory> - Directory containing manifest file (default: ./dist/static)
• --no-extract-manifest - Skip manifest generation

Examples:

# List all schemas
npx sanity schemas list

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

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

# List all schemas
pnpm dlx sanity schemas list

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

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

# List all schemas
yarn dlx sanity schemas list

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

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

# List all schemas
bunx sanity schemas list

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

# Get schemas as JSON
bunx sanity 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
• --manifest-dir <directory> - Directory containing manifest file (default: ./dist/static)
• --no-extract-manifest - Skip manifest generation

Examples:

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

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

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

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

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

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

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

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

Extracts studio configuration as JSON files, which are used by other Sanity tools to understand your studio setup.

Options:

• --path <directory>: Custom destination directory for manifest files (default: /dist/static)
• —-watch: Run watch mode to run extract as changes to the schema occur.
• --workspace <name>: The name of the workspace to generate a schema for.
• --path: Optional path to specify destination of the schema file.
• --enforce-required-fields: Makes the schema generated treat fields marked as required as non-optional. Defaults to false.
• --format=[groq-type-nodes]: Format the schema as GROQ type nodes. Only available format at the moment.
• --watch: Enable watch mode to re-extract schema on file changes.
• --watch-patterns <glob>: Additional glob pattern(s) to watch (can be specified multiple times).

Examples:

# Extract schema to default location
npx sanity schemas extract

# Extract to custom directory
npx sanity schemas extract --path /public/static

# Extract to a directory with watch
npx sanity schemas extract --path /public/static --watch

# Extract schema to default location
pnpm dlx sanity schemas extract

# Extract to custom directory
pnpm dlx sanity schemas extract --path /public/static

# Extract to a directory with watch
pnpm dlx sanity schemas extract --path /public/static --watch

# Extract schema to default location
yarn dlx sanity schemas extract

# Extract to custom directory
yarn dlx sanity schemas extract --path /public/static

# Extract to a directory with watch
yarn dlx sanity schemas extract --path /public/static --watch

# Extract schema to default location
bunx sanity schemas extract

# Extract to custom directory
bunx sanity schemas extract --path /public/static

# Extract to a directory with watch
bunx sanity schemas extract --path /public/static --watch

The extracted manifest follows this structure:

interface CreateManifest {
  version: number        // Current version: 2
  createdAt: string      // ISO timestamp
  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
}

The manifest system works with several Sanity CLI commands:

• Schema Commands: deploy, list, and delete use the manifest to identify schemas.
• Build Process: The manifest is generated during builds and used by Sanity tools.

The following commands are only relevant for Typegen and don't impact server-side schema functionality or compatibility with Dashboard, Canvas, or Agent Actions:

Validates schema types in a workspace.

Options:

• --workspace <name> - Workspace to validate
• --format <pretty|ndjson|json> - Output format
• --level <error|warning> - Minimum reporting level (default: warning)

Extracts the studio configuration as one or more JSON manifest files.

Options:

• --path: Optional path to specify destination directory of the manifest files. Default: /dist/static

• sanity deploy - Includes schema deployment in the process
• 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, ensure your manifest is located at <studio-url>/static/create-manifest.json. You can specify this using the --path option.
• Most commands regenerate manifests by default. Use --no-extract-manifest to use existing files.
• All schema commands require appropriate project permissions.

• Manifest Not Found: Workspace schema file doesn't exist at specified path.
• Invalid Manifest Format: The manifest file has formatting issues.
• Permission Errors: Insufficient permissions to read schema from project/dataset.