English for Contentful CMS Developers
Vocabulary for developers integrating Contentful, the headless CMS platform — content models, entries, rich text, webhooks, and environments — for teams working across marketing and engineering in English.
Contentful is one of the most widely used enterprise headless CMS platforms — content teams manage entries through its web app, while engineers pull that content into websites and apps through its APIs. Because marketing, content, and engineering teams all use the same tool with different vocabularies in mind, being precise in English about “content models,” “entries,” and “spaces” avoids a lot of miscommunication in cross-functional meetings. This guide covers the terms.
Organisational Structure
Space — the top-level container in Contentful holding a content model, entries, and assets — roughly equivalent to a single project or environment for a specific app. “We have separate spaces for our marketing site and our product documentation — they don’t share content models at all.”
Environment — a version of a space’s content and schema you can work in independently, commonly used for testing schema changes before applying them to the live master environment.
“We built the new content model in a sandbox environment first, tested it thoroughly, then merged those changes into master.”
Organisation — the billing and user-management layer above spaces, typically shared across all the spaces a company owns.
Content Modeling
Content Type
A content type defines the schema for a category of content — its fields, validations, and appearance in the entry editor. It’s the Contentful term for what other CMSs call a “collection” or “schema.”
“We added a
relatedArticlesfield to theBlogPostcontent type — every existing entry now shows that field, empty until an editor fills it in.”
Entry
An entry is a single piece of content created from a content type — one instance, like one specific blog post created from the BlogPost content type.
“This entry has been sitting in draft for two weeks — can you check with the author whether it’s ready to publish?”
Asset
An asset is a media file (image, PDF, video) stored in Contentful, referenced by entries rather than duplicated per entry.
“We’re reusing the same hero asset across three campaign pages — updating the file once updates it everywhere it’s referenced.”
Rich Text Field
A rich text field stores structured, nested content (headings, lists, embedded entries) as JSON, rendered into HTML or React components by your app’s rendering logic.
“The rich text field lets editors embed a product entry directly inside an article — our renderer knows how to turn that reference into a product card.”
API and Delivery Vocabulary
Content Delivery API (CDA) — the read-only API serving published content, used by production apps.
Content Preview API (CPA) — a parallel API serving draft, unpublished content, used to preview changes before they go live.
“We point our preview deployments at the Content Preview API so editors can see unpublished changes before approving them.”
Content Management API (CMA) — the API used to programmatically create, update, or migrate content and content types, as opposed to just reading it.
“We wrote a migration script against the Content Management API to backfill the new
excerptfield across 400 existing entries.”
Localisation — Contentful’s built-in support for maintaining separate field values per locale within the same entry, rather than duplicating whole entries per language.
“The French and German versions of this entry share the same images and structure — only the localised text fields differ.”
Publishing Workflow
Published vs. draft state — an entry can have unpublished changes sitting alongside its live, published version; only the published version is served by the Content Delivery API.
Webhook — a configured callback Contentful fires when content changes (published, archived, deleted), commonly used to trigger a rebuild of a static site.
“Every time an editor publishes a change, the webhook fires and triggers our static site rebuild automatically — no manual deploy step.”
Content model migration — a scripted, versioned change to the content model (adding/removing fields, changing validations), run through the Management API rather than manually clicked through the UI, so changes are repeatable across environments.
“We wrote the field rename as a migration script and ran it against the sandbox environment first — that way the same script applies cleanly to master later.”
Explaining Contentful to a Cross-Functional Team
| Situation | Phrase |
|---|---|
| Explaining preview vs. live | ”What you see in the preview link includes your unpublished draft changes — customers won’t see any of it until you hit publish.” |
| Describing a webhook-triggered deploy | ”As soon as this entry is published, the webhook triggers a rebuild — the live site should update within about two minutes.” |
| Justifying environment-based testing | ”We test schema changes in a sandbox environment first, so a mistake in the field configuration never touches the live content model.” |
| Explaining localisation | ”You only need to translate the text fields — the layout and images are shared automatically across all locales.” |
Common Mistakes
- Calling a content type a “template” — a content type defines the schema/fields; a template usually implies a fixed visual layout, which is a separate concern.
- Confusing the Content Delivery API (published only) with the Content Preview API (includes drafts) — mixing them up in a bug report sends engineers looking in the wrong place.
- Saying “the CMS crashed” when an editor really means “the entry failed validation” — being specific about what actually happened saves debugging time.
Practice Exercise
- Explain, in two sentences, the difference between the Content Delivery API and the Content Preview API to a new engineer.
- Write a short note to a content editor explaining why their unpublished changes aren’t showing on the live site.
- Draft a migration plan summary for adding a new required field to an existing content type with 500 entries.
Related Resources
- English for Sanity CMS Developers
- English for Keystatic CMS Developers
- How to Write an API Deprecation Notice in English
Navigating Feedback Loops – A Practical Approach
As developers working with Contentful, it’s inevitable that feedback will flow from various sources: your team, clients, and even automated checks. Understanding nuanced phrasing around these interactions is crucial not just for clear communication but also for ensuring alignment on priorities and expectations. Often, the most challenging part isn’t the technical implementation itself, but articulating why something was done or proposing a change – particularly when dealing with stakeholders who may have different perspectives on what constitutes “good” content or a “successful” integration. Specifically around Contentful, you’ll frequently encounter discussions about ‘schemas’, ‘entry structures’, and ‘content models’ - these terms are essentially blueprints for your data, so it’s vital to speak about them with precision.
One common scenario is receiving a review comment on a pull request describing an issue with the content structure. Instead of simply saying “fix this,” a more effective approach involves clearly articulating the problem and suggesting a solution. For instance, a developer might respond to a reviewer’s comment: “Regarding the inconsistent use of rich text formatting across entries, I’ve adjusted the entry schema to enforce a standard block type for all content elements. This reduces ambiguity and ensures a consistent user experience.” Another example would be in a Slack conversation discussing upcoming changes: “We need to discuss how these new field types will impact the Contentful environment – are there any potential conflicts with our existing workflows?” It’s critical to move beyond just stating what you did and demonstrate why it was necessary, linking back to broader goals like improved content quality or reduced development time. Ultimately, clear and precise communication builds trust and fosters collaboration within a team.
Furthermore, when describing the changes being proposed in a PR description, technical accuracy combined with stakeholder understanding is paramount. For example, “This PR updates the Contentful entry model to include a featured_image field at the top level for improved SEO performance.” This doesn’t just state what was changed; it explains why – linking directly to a business objective (SEO). Remember, stakeholders aren’t necessarily technical experts, so simplifying complex concepts and focusing on the benefits is key.
# Example using Contentful's Management API to update an entry field value:
curl -X PATCH --url "https://api.contentful.com/spaces/{space_id}/entries/{entry_id}" \
--header 'Authorization: Bearer {your_api_key}' \
--header 'Content-Type: application/json' \
-d '{
"fields": {
"title": {
"value": "Updated Title - v2"
}
}
}'This example demonstrates a simple API call to update the title field of an entry, showcasing how technical commands translate into practical actions within Contentful. This command highlights the core function of updating content – something developers will frequently need to manage and communicate about.