English for Sanity CMS Developers
Vocabulary for developers using Sanity, the structured content platform — schemas, GROQ queries, the content lake, and real-time collaboration — for cross-functional teams working in English.
Sanity positions itself as a “structured content platform” rather than a traditional CMS — content is stored in a hosted, real-time database (the content lake) and queried with its own query language, GROQ. Because Sanity has genuinely different concepts from a typical CMS, and because content teams and engineers both work in Sanity Studio daily, precise English vocabulary avoids a lot of cross-functional confusion. This guide covers the terms.
Foundational Concepts
Structured content — content modeled as discrete, typed fields (not one big HTML blob), so the same content can be rendered differently across web, mobile, and other channels. “Because our product descriptions are structured content, not raw HTML, we can render the same data as a web page, an app screen, or an email — without duplicating anything.”
Content lake — Sanity’s hosted, real-time datastore where all your content lives, queryable from anywhere via API. “Every edit hits the content lake immediately — if two editors have the studio open, they see each other’s changes appear in real time.”
Sanity Studio — the open-source, customisable admin interface where editors create and manage content; it’s a React application you can extend with custom input components.
“We built a custom input component in Studio for our pricing table field — the default array editor wasn’t giving editors a clear enough preview.”
Schema and Content Modeling
Schema Type
A schema type defines the shape of a document or object — its fields, validation rules, and how it appears in Studio.
“We defined a new
caseStudyschema type with a reference field back toclient, so editors can link a case study to the right customer record.”
Document
A document is a top-level, independently publishable piece of content — like a blog post or a product — each with its own ID and revision history.
Reference
A reference field links one document to another (for example, a blog post referencing its author document), keeping content normalised rather than duplicated.
“Instead of retyping the author’s bio on every post, we use a reference field pointing to a single
authordocument — updating the bio once updates it everywhere.”
Portable Text
Portable Text is Sanity’s JSON-based format for rich text, designed to be renderable across any framework or channel, unlike HTML which is tied to the web.
“Because our body content is Portable Text, not HTML, the same field renders correctly in our Next.js site, our React Native app, and our email templates.”
Querying with GROQ
GROQ (Graph-Relational Object Queries) — Sanity’s own query language, designed for filtering, joining, and projecting structured content in a single expressive query.
“The GROQ query joins the blog post with its author and category in one round trip — no separate API calls needed.”
Projection — the part of a GROQ query that shapes exactly which fields (and nested references) come back in the response.
“We trimmed the projection to only the fields the homepage actually renders — it cut the payload size significantly.”
Dataset — a named, isolated instance of your content (commonly production and staging), letting you test schema changes without touching live content.
“We tested the new schema field against the staging dataset first, then migrated production once we confirmed nothing broke.”
Editorial and Collaboration Features
Real-time collaboration — multiple editors can work in the same document simultaneously, seeing each other’s cursor and changes live, similar to a collaborative document editor.
“Two writers were editing the same landing page at once, and neither one overwrote the other’s work — Sanity merges changes in real time.”
Draft and published states — every document can have an unpublished draft version alongside its live, published version, letting editors work on changes without affecting the live site.
“The draft has three new paragraphs the marketing team is still reviewing — the published version customers see hasn’t changed yet.”
Content release — a way to group multiple document changes together and publish them all at once, useful for coordinated launches spanning many pieces of content.
“We bundled the new pricing page, the updated FAQ, and the banner copy into one content release, so they all go live together at 9am.”
Explaining Sanity to Stakeholders
| Situation | Phrase |
|---|---|
| Explaining structured content’s value | ”Because the content is structured rather than one HTML blob, we can reuse the same product data across the website, the app, and our marketing emails.” |
| Describing draft/published separation | ”Your changes are saved as a draft immediately, but customers won’t see them until you explicitly publish.” |
| Justifying GROQ over REST | ”One GROQ query gets us the post, its author, and its category together — with REST we’d need three separate round trips.” |
| Explaining real-time collaboration | ”You can both be in the same document at once — Sanity will merge your changes instead of one of you overwriting the other.” |
Common Mistakes
- Calling Portable Text “just JSON” — it’s a structured rich-text format with a defined spec for rendering, not arbitrary JSON.
- Saying “the CMS database” when the more accurate Sanity term is the content lake — it’s a specific, real-time datastore, not a generic database.
- Referring to any content query as “GraphQL” — Sanity’s native query language is GROQ; GraphQL is available as a separate, optional API layer.
Practice Exercise
- Explain, in two sentences, why structured content lets the same data render differently across channels.
- Write a short message to a content editor explaining the difference between a draft and a published document.
- Draft a code review comment suggesting a GROQ projection be trimmed to only the fields actually used on a page.