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
sanity schema deploy

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

# Use existing manifest file
sanity schema 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
sanity schema list

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

# Get schemas as JSON
sanity schema 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
sanity schema delete --ids _.schemas.workspaceName

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

Extracts studio configuration as JSON manifest 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)

Examples:

# Extract manifests to default location
sanity manifest extract

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

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 a JSON representation of a Sanity schema.

Options:

• --workspace <name> - Workspace for schema generation
• --path - Custom destination for the schema file
• --enforce-required-fields - Makes required fields non-optional (default: false)
• --format=[groq-type-nodes] - Format schema as GROQ type nodes

• 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