Sanity Studio schema deployment and GraphQL API synchronization

Answering the Core Questions

1. Pipeline strategy – Deploy the Studio bundle and the GraphQL schema from the same commit, and run sanity graphql deploy immediately after a successful Studio deployment. This guarantees that the API schema is always a faithful snapshot of the authoring schema that Studio is currently validating.

2. Pre‑deployment validation – Sanity itself does not ship a built‑in scanner that walks every document and reports incompatibilities before the bundle is live. The usual workaround is to run a custom script (or a dataset query) against the target dataset to surface validation errors before you push the new Studio bundle.

Confirmed Facts

• Studio schema changes are code‑deployed with the Studio bundle and take effect immediately in the UI.
• GraphQL schema is a separate artifact; it must be redeployed with sanity graphql deploy to stay in sync.
• There is no native pre‑deploy compatibility check for existing documents.
• Breaking changes (e.g., making a field required or changing its type) instantly invalidate existing documents once the Studio bundle is live.

Recommended Pipeline Workflow

1. Commit the schema change – All schema files in schemas/ should be version‑controlled and part of the same git commit that will be deployed.
2. Build and deploy Studio – Use your CI/CD tool to run:

   sanity deploy --dataset production --project my-project
   

   This updates the Studio bundle and immediately starts validating documents in the production dataset.
3. Run a pre‑deploy document scan (optional but recommended) – Execute a script that queries all documents of the affected types and checks for validation errors:

   sanity dataset query production "*[_type=='article']{_id, title, body}" | jq 'select(.body==null)'
   

   If any errors surface, pause the pipeline and backfill or adjust the schema.
4. Deploy GraphQL – Immediately after the Studio deploy succeeds, run:

   sanity graphql deploy --dataset production --project my-project
   

   This publishes a GraphQL schema that matches the newly deployed Studio schema.
5. Canary test – Point a staging or canary environment at the same dataset and run a few GraphQL queries to confirm no 404s or type mismatches.
6. Promote to production – If the canary passes, merge the commit into the main branch and let the pipeline run the above steps on the real production environment.

Two‑Phase Additive Migration for Breaking Changes

When you must make a field required or change its type:

• Phase 1 – Add the new field as optional, backfill existing documents with a migration script, and keep the old field as read‑only.
• Phase 2 – After a successful rollout and confirmation that all documents contain valid data, make the field required (or drop the old field) and redeploy Studio and GraphQL.

Client‑Side Considerations

Because the GraphQL schema can be ahead of Studio (if you deploy GraphQL first) or behind (if you deploy Studio first), clients may experience temporary query failures. The safest approach is:

• Keep GraphQL changes backward compatible – never remove a field that clients might still query.
• Use GraphQL schema versioning or tag the GraphQL endpoint with a version header so clients can migrate gradually.

Missing Diagnostic Detail

To tailor the recommendation more precisely, could you confirm whether the planned schema changes are additive (new fields, optional changes) or involve destructive operations (removing or renaming fields, making required)?

Verification Checklist

• Verify your sanity.json points to the correct project and dataset.
• Run sanity graphql schema preview locally to spot obvious type mismatches before deployment.
• After production deploy, query _schema via GraphQL to ensure the new types are present.
• Monitor Studio for validation errors and GraphQL for 400/404 responses during the first 24 hours.