English for Sanity CMS Developers

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 caseStudy schema type with a reference field back to client, 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 author document — 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

1. Explain, in two sentences, why structured content lets the same data render differently across channels.
2. Write a short message to a content editor explaining the difference between a draft and a published document.
3. Draft a code review comment suggesting a GROQ projection be trimmed to only the fields actually used on a page.

Related Resources

• English for Keystatic CMS Developers
• English for GraphQL Federation
• English for Contentful CMS Developers

Navigating Nuance: Beyond Literal Translation

Sanity’s strength lies in its ability to facilitate clear communication across diverse teams – a crucial element when dealing with differing levels of native-English proficiency. It’s not just about knowing the definitions of terms like “schema” or “GROQ,” but understanding how they’re used within the workflow, and importantly, how you’ll articulate your intentions to others. Many developers initially focus on direct translations from their first language, which can lead to ambiguity and misunderstandings. For example, a developer accustomed to a more verbose approach might instinctively describe a complex query as “retrieving all data related to…” when a concise phrasing like “fetching content with this GROQ query” is far more effective in a Sanity context.

The key difference often lies in the expected level of detail and the implied understanding within the team. In code reviews, for instance, receiving a comment like “This query seems inefficient” needs careful unpacking. It’s not necessarily an accusation; it could be a genuine observation about performance or a suggestion for optimization. A productive response isn’t simply “It’s fine,” but rather, “I considered using [alternative technique] to improve the initial load time, but I prioritized speed here because…” – demonstrating understanding of why the current approach was chosen and acknowledging potential concerns. Similarly, in Slack conversations when discussing a PR description, clarity is paramount. A vague description like “Updated content” is insufficient; instead, “Implemented schema changes for product pages, incorporating new image assets and updating metadata using GROQ” communicates precisely what’s been done and why it matters to the larger project.

Furthermore, embracing active phrasing – asking clarifying questions rather than assuming understanding – is invaluable. Instead of passively accepting a suggestion, ask “Could you elaborate on what you mean by ‘optimizing this query’?” or “Can you show me an example of how that approach would look in GROQ?”. These small shifts in communication can dramatically reduce friction and improve collaboration. Don’t be afraid to politely request context; it’s far better than struggling with unspoken assumptions.

Here’s a simple example using Sanity CLI to demonstrate fetching content:

sanity fetch-one --id product/12345

This command, when explained, is more than just the literal action of retrieving an item – it’s about accessing a specific piece of structured content within the Sanity content lake based on its unique identifier. It’s a small snippet, but illustrates how even seemingly straightforward commands require clear articulation and understanding within the broader development process.