By the end of this chapter you can

• Say what a headless content model is and which tools the module replaces.
• Place a piece of content in one of the five spaces and say which neighbouring module owns what this one leaves out.
• Explain why versions are never edited and what the two version pointers on an entry mean.

What the module does

The module runs the public website, the product catalogue, the careers pages and an internal knowledge base from one content model. Content has drafts, versions, an editorial workflow, scheduled publishing, preview, languages, search engine data, and forms that feed the CRM and the help desk. It replaces content tools such as WordPress (hosted), Webflow, Contentful, Sanity, Storyblok, Strapi Cloud, Payload and HubSpot CMS, and internal page tools such as Confluence, Notion and SharePoint pages. Independent write-ups compare the headless systems among them ^[1][2][4]. Treat them as opinion and read every price on the vendor's own page.

Headless means the place where content is written (the back end) is separate from the place where it is shown (the front end). The back end stores content and serves it through a read API (a web address that returns content as data). The front end, which may be a website, a phone app or a kiosk, asks for what it needs and decides how it looks.

What is in, and what is not

• In: content types defined as schema; entries with versions; editorial workflow, scheduling and preview; a media library with transforms and alt text; localisation with fallbacks; SEO (metadata, JSON-LD, sitemap, redirects); navigation, web forms and search; internal knowledge-base spaces with permissions.
• Out: controlled documents such as SOPs (M06 Document Control); email campaigns (M16); e-commerce checkout (the catalogue, in a later wave).

Every content type belongs to one of five spaces: public_site, catalog, careers, knowledge_base or internal. The space decides who may read the content, so a knowledge-base article about an internal procedure never shows on the public site.

Content types are schema, not pages

A content type (table cms_content_type) is a named list of fields with rules: a unique key, a name, a schema written as JSON, whether it is a singleton (is_singleton: one entry only, such as site settings), whether it is translated (localized) and its space. The fields are text, rich text, number, date, media, reference to another entry, and component blocks (small reusable groups of fields), each with validation such as required, maximum length or allowed values.

Entries and versions

An entry (cms_entry) is the content of one type, in one locale, at one address (slug). Its words are not stored on the entry itself but in versions (cms_entry_version), each holding the field data as JSON, a version_no and a change_note. A version is immutable: editing creates version number plus one, so history cannot be rewritten, and rollback means copying an old version into a new one.

Entries that point to other entries (an article that features three products) are recorded in cms_entry_reference. This reference graph is how the module knows which pages to refresh when a product changes.

The twelve tables, column by column

The table below is the full definition from the module specification: every column the module adds to the standard ones, with its type and whether it is required (marked req). Types are written as in the specification: text, int, bool, ts (a timestamp with time zone), uuid and json (jsonb in Postgres); an arrow means a foreign key to that table. It is what your agent builds from in Session 2.

The standards the module is built against

Exercise · Model one real content type15 minutes

You need: Your inventory from Session 1 (docs/cms-inventory.md), one real page of your site and your AI coding agent

Choose a kind of content from your own site that appears in more than one place, for example a service, a product or a job posting. Work on paper or in a text file first.

1. 1. Name the content type and choose its space from the five. Write one line on why that space decides who may read it.
2. 2. List the fields the content really has (name, summary, price or area, image, status). Give each a type from the list in this chapter and mark which are required.
3. 3. Cross out every field whose only job is to place something on one page, such as "left column". Move what it holds into a real field or into the front end.
4. 4. Decide if the type is a singleton and whether it needs translating. Write the answers with a reason.
5. 5. Write two entries on paper, each with a slug, and one reference from one entry to another.
6. 6. Ask your agent: "Write the JSON for the schema column of a cms_content_type row with these fields, and two cms_entry_version data values." Read it back against your list.

Outcome: A one-page content type design for a real kind of content: space, fields with types and required flags, no layout fields, singleton and localisation decided, plus the JSON your agent produced and you checked.

References

1. Cosmic: Sanity vs Contentful 2026. https://www.cosmicjs.com/blog/sanity-vs-contentful
2. CoderCops: Sanity, Contentful, Strapi and Payload compared (2026). https://blog.codercops.com/blog/headless-cms-comparison-sanity-contentful-strapi-payload-2026
3. W3C: Web Content Accessibility Guidelines (WCAG) 2.2. https://www.w3.org/TR/WCAG22/
4. Techsy: Contentful CMS guide 2026. https://techsy.io/en/blog/contentful-guide

By the end of this chapter you can

• Name the six statuses of an entry and who moves it between them.
• Explain how preview differs from the delivery API and why the delivery API must never return draft content.
• Say what a revalidation webhook does and what alt text is required for.

The editorial workflow

An entry's status is one of six values: draft, in_review, approved, scheduled, published, archived. People move it along with rights that follow their job. In this course the roles are author (writes), editor (reviews and approves), publisher (schedules, publishes and unpublishes) and site administrator (content types, locales, forms and menu structure). Reviewers leave comments (core_comment) and each approval step is a row in core_approval, so who approved what, and when, is recorded.

Scheduling

An entry has two timestamps, publish_at and unpublish_at. A scheduled run publishes at the first and takes the entry down at the second, for example a seasonal offer or a closing date on a job posting. The run acts as its own named login with rights only to do that. The specification has each change publish an event, cms.entry.published or cms.entry.unpublished, so other modules and the front end can react; the course builds these as an optional extension in Session 4, as rows in an event outbox.

Preview and delivery are different paths

Editors need to see a draft inside the real page, with the real design. The Next.js feature for this is draft mode ^[1]: a route checks that the person may read the entry and then sets a cookie that makes the page show the current version instead of the published one. Readers never get that cookie. They go through the delivery API, which filters on the published version pointer and returns the published version only.

Keeping pages fresh

Pages are built ahead of time and kept in a cache so they load fast. When content changes, the front end must be told. A webhook (a web address the module calls when something happens) tells the front end which pages changed, and the front end revalidates them: it rebuilds just those pages, not the whole site ^[2][3]. This is what the specification calls ISR (incremental static regeneration). The reference graph from chapter 1 supplies the list: when a product changes, every entry that references it is revalidated too.

The media library

Images, video and documents sit in cms_media_asset, which points to a file in core_attachment and adds a title, a focal point (the part of the image that must stay in frame when it is cropped), width and height, responsive variants (the same image at several sizes; the column exists, but the course does not build image transforms), a licence and a credit. Alt text is required at upload, and a blank value is refused by the database. Alt text is the short written description a screen reader speaks in place of an image; WCAG success criterion 1.1.1 asks for a text alternative for non-text content ^[4]. Accessibility is a legal exposure in many places, and the module's rule is that an image cannot enter the library without it.

Exercise · Walk one entry through the workflow20 minutes

You need: A development copy of your platform with the seed from Session 2, two test users with different roles, and your AI coding agent

Do not use live data. The aim is to see each status change and prove readers never see a draft.

1. 1. Sign in as the author. Create an entry of a type from Session 2 with a slug and a first version. Write down its status.
2. 2. Move it to in_review. Sign in as the editor, leave one comment, and return it to draft. Write down who could do each step and who could not.
3. 3. Move it through in_review and approved again, then, as the publisher, publish it. Write down which pointer changed.
4. 4. Edit the published entry so it has a newer draft version. Open the delivery API address for the entry in a private browser window with no session and write down which text you see.
5. 5. Open the preview route as the editor. Write down which text you see and whether anyone without a session can reach the same route.
6. 6. Schedule a second entry for two minutes ahead and watch the scheduler publish it, or press Run scheduled publishing now. Then ask your agent to write the test: the delivery API returns no text from a draft, in_review or archived entry.

Outcome: A written trace of one entry through draft, review, approval and publication, a proof that a private window sees only the published text, and a passing test that the delivery API never returns draft content.

References

1. Next.js: How to preview content with Draft Mode. https://nextjs.org/docs/app/guides/draft-mode
2. Next.js: Revalidating. https://nextjs.org/docs/app/getting-started/revalidating
3. Next.js: revalidateTag. https://nextjs.org/docs/app/api-reference/functions/revalidateTag
4. W3C: Understanding Success Criterion 1.1.1, Non-text Content (WCAG 2.2). https://www.w3.org/WAI/WCAG22/Understanding/non-text-content.html

By the end of this chapter you can

• Explain how a locale falls back to another and why a locale can never fall back to itself.
• Name what a page's seo data produces and choose the right redirect code for a given case.
• State the three Core Web Vitals and their good thresholds.

Localisation with fallbacks

Each locale (table cms_locale) has a code written as a BCP 47 language tag ^[1], a name, an optional fallback_code and a flag for the default. A tag such as es names a language; es-MX adds a region. Entries in different languages are linked by a shared translation_group_id, so the front end can offer the same page in another language.

The module tracks translation status for each entry. It can also draft a translation with AI, but a person must review it before it goes live: an AI draft is a draft, and never skips the workflow in chapter 2.

What search engines read

Every entry has an seo field: title, description, canonical address (the one address you want search engines to list for the page) and a social image. From it the module produces four things.

• JSON-LD is a block of structured data in the page that tells search engines what the page is, using types from schema.org such as WebPage or Product ^[2][3]. It describes the visible page; it does not replace it.
• sitemap.xml lists the addresses of your pages for search engines. The protocol limits one file to 50,000 addresses and 50 MB uncompressed, after which you use several files and an index ^[4]. Only published entries belong in it.
• Broken-link checks find links inside content that point to an entry that is archived or gone, before a reader finds them.

Redirects, and the code you choose

When an address moves, a redirect (table cms_redirect) sends the visitor and the search engine to the new one. The code says how long the move lasts. HTTP semantics are defined in RFC 9110 ^[5].

The hits counter on each redirect shows which old addresses are still used, so you know what is safe to retire.

Speed, measured on real visits

Google's Core Web Vitals are three measures of how a page feels ^[6]: Largest Contentful Paint (LCP, how long until the main content shows), Interaction to Next Paint (INP, how quickly the page responds after a tap or click) and Cumulative Layout Shift (CLS, how much the layout jumps while loading). A page passes when at least 75 percent of real visits meet the good threshold for each.

Lighthouse, a tool built into the Chrome developer tools ^[7], gives a score for accessibility and performance on one page in one test. The module's own bar for accessibility is a Lighthouse accessibility score of at least 95 on the seeded templates. A score is only a first check: it cannot see whether alt text makes sense.

Exercise · Audit one page for search and speed15 minutes

You need: A page of your site, Chrome with its developer tools, your sitemap.xml and your AI coding agent

Use a real page from the inventory you made in Session 1. You only read; change nothing on the live site.

1. 1. View the page source. Write down the title, description and canonical address, and whether the page has a JSON-LD block (a script of type application/ld+json).
2. 2. Run Lighthouse on the page. Write down the accessibility score and the images it lists without alt text.
3. 3. Open the sitemap.xml and find the page. Write down whether it appears and how many addresses the whole file lists.
4. 4. Request one old address you know has moved. Write down each address it passes through and the status code of each hop.
5. 5. For that address, write the one redirect you would keep, from the old address to the final page, with the right code from the table and a reason.
6. 6. Ask your agent: "Write the cms_redirect row and the seo JSON for this entry, with a title under 60 characters and a canonical address." Check it against what you found.

Outcome: A one-page audit of a real page: its seo data, accessibility score, sitemap status, the redirect hops for one moved address, and the single redirect row that replaces the chain.

References

1. IETF BCP 47: Tags for Identifying Languages. https://www.rfc-editor.org/info/bcp47
2. schema.org. https://schema.org/
3. W3C: JSON-LD 1.1. https://www.w3.org/TR/json-ld11/
4. sitemaps.org: The Sitemaps protocol. https://www.sitemaps.org/protocol.html
5. IETF RFC 9110: HTTP Semantics. https://www.rfc-editor.org/rfc/rfc9110.html
6. web.dev: Web Vitals. https://web.dev/articles/vitals
7. Chrome for Developers: Lighthouse overview. https://developer.chrome.com/docs/lighthouse/overview

By the end of this chapter you can

• Describe how a web form submission is checked, stored with its consent text, and routed.
• Explain how the knowledge base is structured, permissioned and measured.
• Plan a migration so that every old address resolves in one hop or fewer before the domain moves.

Web forms that create records

A web form (table cms_web_form) has a unique key, its fields, a target, the consent_text shown to the visitor, a success_message and a spam_protection choice. The target is one of crm_lead, helpdesk_ticket, email or webhook. Each submission (cms_web_form_submission) stores the payload, the campaign tags from the address (utm), a hashed form of the visitor's network address (ip_hash, a one-way scrambled value, so the raw address is not kept), the time, and a status: received, routed, spam or failed. The consent text shown and the form's version are kept inside the payload, because the table has no separate columns for them.

The free way comes first: start with a honeypot, measure how much spam still gets through, and move to a provider's challenge only if it does.

The internal knowledge base

The knowledge base is a set of internal spaces. Its pages form a tree through parent_entry_id, its permissions follow the space, and each article collects feedback in cms_kb_feedback: helpful or not, an optional comment, who and when. Help-desk tickets link to articles, and a signal from the help desk, svc.kb_gap.detected, tells the module that people keep asking something no article answers. In the optional extension the catalogue also reacts to plm.part.released: a released part drafts a new version of its product entry for review, never a published change.

The four measures

Measure the first number before you change anything. The baseline from Session 1 is what lets you say, at the end, that publishing got faster.

Moving from the old tool

The old content comes out as files: WordPress through its REST API ^[2] or an export file, Webflow as CMS CSV files, and Contentful as an export. Each maps to your content types; comparisons of the systems you may be leaving or joining are in ^[5]. The import creates drafts only, so nothing reaches the public site except through the review in chapter 2.

Search engines publish guidance on moving a site ^[3][4]: keep a permanent redirect from every old address to its new equivalent, and keep the redirects in place long after the move. Your definition of done has three checks you can run by script.

• The published API never returns draft content (a test).
• Every migrated address resolves with at most one redirect hop (a script that follows each one).
• A Lighthouse accessibility score of at least 95 on the seeded templates.

Exercise · Build and check a redirect map20 minutes

You need: The list of public addresses saved in Session 1, a list of the new addresses, a spreadsheet or text file and your AI coding agent

Work on a copy of the lists. Nothing here touches the live site.

1. 1. Open the saved list of old addresses and count them. Write the count at the top.
2. 2. For each old address, write its new address, or "retired" with a reason. Do this for the 20 most visited first, by your analytics if you have it, and for the rest by pattern.
3. 3. Choose a code for each from chapter 3 (usually 301) and mark any that are temporary.
4. 4. Look for chains: where a new address is itself an old address, point the first one at the final page instead.
5. 5. Ask your agent: "Write a script that reads the map, requests each old address on the staging site without following redirects, and prints any address that does not resolve to a live page in one hop or fewer." Run it.
6. 6. Fix every address the script flags, run it again until the list is empty, and save the map as a file in your repository through a pull request.

Outcome: A redirect map covering every old address (or retiring it with a reason), no chains, a script result showing every address resolves in one hop or fewer, and the map merged on main.

References

1. Cloudflare: Turnstile documentation. https://developers.cloudflare.com/turnstile/
2. WordPress Developer Resources: REST API Handbook. https://developer.wordpress.org/rest-api/
3. Google Search Central: Site moves with URL changes. https://developers.google.com/search/docs/crawling-indexing/site-move-with-url-changes
4. Google Search Central: Redirects and Google Search. https://developers.google.com/search/docs/crawling-indexing/301-redirects
5. Rajesh Kumar: Top 10 headless CMS. https://www.rajeshkumar.xyz/blog/?p=1145

Choose one answer for each question, then submit. You will see the right answer and why for every question.

1. What does "headless" mean for a content system?

AContent is stored apart from the front end that shows it, and delivered through an APIBIt has no loginCIt has no databaseDIt can only serve one website

2. Which is the best way to design a content type for a product?

AFields named for page areas, such as left_columnBFields for what a product is, such as name, price and imageCOne large text box for the whole pageDA separate type for each page layout

3. An editor changes a published entry. What does the module do?

AIt edits the existing version in placeBIt deletes the old versionCIt creates a new version and leaves the earlier ones unchangedDIt publishes the change at once

4. What do published_version_id and current_version_id on an entry mean?

ABoth name the version readers seeBThe first is the oldest, the second the newestCThey are the author's and the editor's draftsDThe first is what readers see, the second the newest

5. A visitor opens an entry that has a newer, unapproved version. Which text appears?

AThe newest versionBThe published versionCAn error pageDA blank page until approval

6. What does a revalidation webhook do after an entry is published?

ATells the front end which pages changed so it refreshes just thoseBDeletes the old cache for the whole siteCEmails the authorDMakes drafts visible

7. An image is uploaded to the media library with blank alt text. What should happen?

AIt is accepted and fixed laterBThe file name is used insteadCIt is accepted if the page is privateDIt is refused, because alt text is required

8. A reader asks for the page in es-MX, which has no entry, but its fallback_code is es and es has one. What do they get?

AAn errorBThe English pageCThe es entryDA machine translation shown live

9. Which redirect code fits a page that has moved for good, when its method may change?

A302B307C301D304

10. Why are redirect chains a problem after a migration?

AThey make the database largerBBrowsers refuse themCThe sitemap rejects themDEach hop slows the visit and can lose search standing

11. Which statement about Core Web Vitals is right?

ALCP is good up to 2.5 seconds, INP up to 200 milliseconds and CLS up to 0.1BLCP is good up to 10 secondsCCLS is measured in secondsDThey are measured on one lab test only

12. Why is the consent text stored with each form submission?

ATo speed up the formBTo show what the visitor agreed to on the dayCBecause spam protection needs itDTo make CRM routing faster

Submit answers