Chapter 5: Content Modeling & Schema Design

The modern best practice is a modular content model: break content into small, reusable types — components assembled into pages — rather than treating each content type as a monolithic page. The payoff is that "the same component can be rendered across web, mobile, regional microsites, or partner portals without duplication" (Eight25Media; Storyblok, 2026). Storyblok calls these Bloks; Contentful calls them components assembled in a Compose-style layout; Sanity models them as objects inside a pageBuilder array of references or inline objects.

A practical rule: model the nouns of your business as entity types (these earn URLs, slugs, and publish states), and model layout/presentation as blocks (these never earn their own URL). Avoid the common anti-pattern of one giant Page type with 80 optional fields — it is unqueryable, un-AI-friendly, and a localization nightmare.

Portable Text: structured rich text as JSON

Rich text is where most content models leak. A WYSIWYG that emits HTML couples your content to one presentation forever and produces exactly the "HTML soup" that breaks on the next channel. The 2026 answer is Portable Text — a published, open JSON specification for block content (github.com/portabletext/portabletext). It stores rich text as an array of blocks, each block an array of children spans, with style, marks, and markDefs describing structure and meaning rather than visual styling.

[
  {
    "_type": "block",
    "style": "h2",
    "children": [{ "_type": "span", "text": "Why structure wins" }]
  },
  {
    "_type": "block",
    "style": "normal",
    "markDefs": [{ "_key": "a1", "_type": "link", "href": "https://example.com" }],
    "children": [
      { "_type": "span", "text": "Read the " },
      { "_type": "span", "marks": ["a1"], "text": "spec" },
      { "_type": "span", "text": "." }
    ]
  },
  { "_type": "callout", "tone": "warning", "body": "Validate before publishing." }
]

Why this matters for an AI-native CMS:

• Channel-agnostic rendering. The same array serializes to HTML (web), Markdown (LLM context, email, llms.txt), plain text (voice/SSML), or native mobile components — "render the same content consistently across web, mobile, email, and any future platform" (ContentWrap; Sanity Docs).
• Custom inline objects. You can embed typed blocks — a callout, a productCard, an imageWithAlt — directly in the flow, "without needing to create specific renderers in the editor" (Sanity Docs).
• Queryable structure. Because it is JSON, you can query across rich text: "find every post with a link," or "extract all headings to generate a table of contents" (Sanity, Beginners guide to Portable Text). That same property lets an AI agent reliably extract or rewrite a single block.

Portable Text is the de facto open standard, but the principle is portable: Contentful's Rich Text and Strapi's Blocks field are also JSON-AST formats. Reject any field that stores raw HTML as a string — it is the single most expensive modeling mistake for AI and omnichannel.

References, relationships, and taxonomies

References turn isolated documents into a graph — and the graph is precisely what AI systems exploit. An entity graph is "a network of connected entities — people, organizations, products, concepts — and their relationships," and AI systems "use entity graphs to understand context, verify information, and determine citation confidence" (GEO Compass, 2026). Your reference model is your entity graph.

Reference, don't duplicate. A common pitfall is "storing slugs or categories in plain text fields instead of using reference types, which loses all the benefits of validated, queryable relationships" (Cosmic, 2025). Model author, category, and relatedProducts as references to real documents, not strings.

Reference cardinality:

In Sanity, hierarchical taxonomies are expressed with a self-reference plus a validation filter — e.g., options: { filter: 'defined(parent)' } to restrict references to child documents only — and traversed with the GROQ dereference operator -> (Sanity Docs, Creating a Parent/Child Taxonomy). Most platforms offer the equivalent: Contentful uses linked entries, Strapi uses relations, Payload uses relationship fields.

Taxonomy design tips for AI and AEO:

• Keep a controlled vocabulary for categories and tags — stable terms across channels matter, because AI engines reward consistent entity naming and you want to "choose a primary term, then use alternate terms deliberately as synonyms" (LLMrefs/ALM Corp, 2026). Model synonyms explicitly in a synonyms array rather than letting editors free-type variants.
• Add sameAs URLs (Wikipedia, Wikidata, official site) to entity types like Author, Organization, and Brand. This is both a schema.org property and an entity-graph anchor for citation confidence.

Validation: the contract editors and agents both obey

Validation is where a model stops being a suggestion and becomes a contract. In an AI-native CMS validation does double duty: it keeps humans honest and it constrains what an AI agent is allowed to write back through the API/MCP layer. An agent that can mutate content is only as safe as the schema's guardrails.

Layered validation strategy:

Two patterns worth standardizing: (1) make altText required on every image object — it is an accessibility (WCAG 2.2) and AEO requirement, not an option; (2) validate slugs at the field level (lowercase, kebab-case, unique). End-to-end type safety closes the loop on the code side: Sanity TypeGen generates TypeScript types from your schema, and Zod can validate the actual GROQ response at runtime (Chin, End-to-end type safety for Sanity GROQ queries, 2025).

Slugs, URLs, and redirects

Slugs are deceptively load-bearing — they are the public identity of a document and a ranking/citation signal. Best practices:

• Store slugs as a dedicated slug field (with a source field for auto-generation and a uniqueness validation), not a free-text string.
• For nested content, compute the full path from the taxonomy graph rather than hardcoding it, so moving a node updates its descendants.
• Preserve slug history. When a published slug changes, save the old one and 301-redirect it to the new URL. Kontent.ai recommends a "URL slug history" mechanism that "tracks when a published URL slug changes and automatically saves the old one," then the site "processes both current and old slugs and redirects old to new" (Kontent.ai, 2025).

A robust pattern is a dedicated redirect content type (from, to, statusCode 301/302/410, isActive) that your edge/middleware reads. This keeps redirects as content — editable, auditable, and exportable to llms.txt-style discovery — instead of buried in code deploys.

Draft / published state and editorial workflow

Every entity type needs a lifecycle. The minimum is draft vs. published; mature teams model a state machine: Draft → In Review → Approved → Published → (Archived). Modeling it as a state machine "prevents invalid changes — for instance, content can't go from Draft straight to Published without passing Review" (Afteractive, 2025).

Implementation patterns differ by platform philosophy:

For an AI-native CMS, three additions are non-negotiable:

1. An aiGenerated/reviewStatus field so machine-authored content is flagged and never auto-published without a human gate — agentic platforms "generate, audit, and publish with minimal human review," which makes the review gate the safety mechanism (CMS Critic, 2026).
2. Versioning/history so an agent's edit can be diffed and rolled back.
3. Scheduled publishing as content (a publishAt timestamp) rather than a side-channel cron.

Modeling for the four consumers

This is the section that distinguishes an AI-native model from a merely headless one. The same schema must satisfy four audiences simultaneously.

1. Humans (editors). Field descriptions, sensible grouping, conditional fields, previews. Good descriptions are now dual-purpose — see consumer 2.

2. AI generation & agents. The breakthrough insight of 2025–26 is that your schema is the prompt. Sanity's Content Agent and Agent Context work by "compressing the Sanity schema" so an agent understands "field descriptions, document relationships, required vs. optional fields, and the semantic meaning of content," then translates natural-language requests into precise mutations (Sanity, Agent Context; CMS Critic, 2026). Practical implications for your model:

• Write field descriptions for the machine, not just the human ("One-sentence summary, max 160 chars, used as the meta description and the answer-engine snippet").
• Provide discrete fields an agent can target: headline, summary, keyPoints[], targetAudience, relatedProducts[]. A structured model "gives AI agents everything they need" to generate and audit (Sanity, 2026).
• Co-locate embeddings with content if your platform supports it — Sanity stores vectors in the Content Lake "alongside content," so "when a price changes, embeddings update automatically with no reindexing pipeline" (Sanity, 2026). Otherwise model an external embedding pipeline keyed to document IDs and _updatedAt.
• Expose the model via MCP (Model Context Protocol), the 2026 standard integration layer that lets AI tools "read CMS schemas and perform mutations through a standardized interface" (llmcms.org, 2026). Design the schema knowing an MCP server will surface it to agents.

3. Omnichannel delivery. Because content is structured and presentation is decoupled (Portable Text + blocks), the same documents render to web, native app, email, voice, and in-store screens. The model rule: no presentation-only fields on entity types (no "background color of the third paragraph"). Layout choices live in blocks; meaning lives in fields.

4. Answer engines (AEO/GEO). This is the newest consumer and reshapes the model in concrete ways:

• Bake schema.org into the model. Map fields to JSON-LD types — Article/BlogPosting, Product/Offer, FAQPage, HowTo, Organization, Person. Pages with FAQPage schema appear in Google AI Overviews ~3.2× more often, and "search engines use schema as a signal, while AI engines use schema as a source" (AirOps; SearchAtlas, 2026). Don't bolt JSON-LD on in templates — generate it deterministically from the model so it can never drift from the content.
• Model Q&A explicitly. Add an faq[] array (question, answer as Portable Text) and consider a keyTakeaways[] field; AI engines cite content that "ranks for the sub-queries the AI generates" (LLMrefs, 2026).
• speakable candidates. Mark which fields are voice-suitable.
• llms.txt output. Your model should be exportable as the emerging llms.txt format — a root Markdown file with an H1 (site name), a blockquote summary, and H2 sections of annotated links to your most important content (codersera, llms.txt Explained May 2026). As of 2026 "no major AI platform has officially committed to reading llms.txt as a first-class input," but Anthropic, OpenAI, and Perplexity retrieval pipelines can be prompted to fetch it, and Mintlify auto-generates it for thousands of docs sites including Anthropic, Cursor, and Pinecone. Treat it as low-cost insurance: because content is structured, generating llms.txt (and per-page .md variants) is a serialization, not a rewrite.

A concrete example schema

Below is a vendor-neutral model for an editorial + product site, expressed in a Sanity-style schema (the concepts map directly to Contentful/Strapi/Payload). It demonstrates entity types, blocks, references, taxonomy, validation, slug+redirect, lifecycle, and AI/AEO fields.

// ---------- Entity type: Article ----------
export const article = {
  name: 'article', type: 'document', title: 'Article',
  groups: [{ name: 'content' }, { name: 'seo' }, { name: 'ai' }],
  fields: [
    { name: 'title', type: 'string', group: 'content',
      validation: r => r.required().max(120) },
    { name: 'slug', type: 'slug', group: 'seo',
      options: { source: 'title', maxLength: 96 },
      validation: r => r.required() },               // lowercase/unique enforced
    { name: 'summary', type: 'text', rows: 2, group: 'seo',
      description: 'One-sentence summary, max 160 chars. Used as meta description AND the answer-engine snippet.',
      validation: r => r.required().max(160) },
    { name: 'author', type: 'reference', to: [{ type: 'author' }],
      group: 'content', validation: r => r.required() },
    { name: 'categories', type: 'array', group: 'content',
      of: [{ type: 'reference', to: [{ type: 'category' }] }],
      validation: r => r.min(1).max(3) },
    // Portable Text body with custom inline blocks
    { name: 'body', type: 'array', group: 'content',
      of: [
        { type: 'block' },                            // standard rich text
        { type: 'imageWithAlt' },                      // alt text required (see below)
        { type: 'callout' },
        { type: 'productCard' },                       // reference-backed block
      ] },
    // AEO: explicit Q&A → maps to schema.org FAQPage
    { name: 'faq', type: 'array', group: 'ai',
      of: [{ type: 'object', fields: [
        { name: 'question', type: 'string' },
        { name: 'answer', type: 'array', of: [{ type: 'block' }] },
      ] }] },
    { name: 'keyTakeaways', type: 'array', of: [{ type: 'string' }], group: 'ai' },
    // AI governance
    { name: 'aiGenerated', type: 'boolean', initialValue: false, group: 'ai' },
    { name: 'reviewStatus', type: 'string', group: 'ai',
      options: { list: ['draft', 'in_review', 'approved', 'published'] },
      initialValue: 'draft' },
    { name: 'publishAt', type: 'datetime', group: 'seo' },
    // schema.org mapping hint (deterministic JSON-LD generation)
    { name: 'schemaType', type: 'string', group: 'seo',
      options: { list: ['Article', 'BlogPosting', 'NewsArticle'] },
      initialValue: 'BlogPosting' },
  ],
};

// ---------- Reusable block: image with required alt ----------
export const imageWithAlt = {
  name: 'imageWithAlt', type: 'image', title: 'Image',
  fields: [
    { name: 'alt', type: 'string', title: 'Alt text',
      description: 'Required for WCAG 2.2 + answer-engine indexing.',
      validation: r => r.required().max(125) },
  ],
};

// ---------- Taxonomy: hierarchical Category ----------
export const category = {
  name: 'category', type: 'document', title: 'Category',
  fields: [
    { name: 'title', type: 'string', validation: r => r.required() },
    { name: 'slug', type: 'slug', options: { source: 'title' },
      validation: r => r.required() },
    { name: 'parent', type: 'reference', to: [{ type: 'category' }],
      options: { filter: 'defined(parent) || _id != _id' } }, // restrict graph
    { name: 'synonyms', type: 'array', of: [{ type: 'string' }],
      description: 'Alternate terms for AEO entity consistency.' },
  ],
};

// ---------- Redirects as content ----------
export const redirect = {
  name: 'redirect', type: 'document', title: 'Redirect',
  fields: [
    { name: 'from', type: 'string', validation: r => r.required() },
    { name: 'to', type: 'string', validation: r => r.required() },
    { name: 'statusCode', type: 'number', initialValue: 301,
      options: { list: [301, 302, 410] } },
    { name: 'isActive', type: 'boolean', initialValue: true },
  ],
};

The corresponding GROQ query shows how references collapse into a clean, AI-ready payload via the dereference operator:

*[_type == "article" && slug.current == $slug && reviewStatus == "published"][0]{
  title, summary, body, faq, keyTakeaways, schemaType,
  "author": author->{name, "sameAs": sameAs},
  "categories": categories[]->{title, "slug": slug.current}
}

This single document now feeds the website, an email digest, an llms.txt entry, a JSON-LD BlogPosting + FAQPage block, and an MCP-exposed tool an agent can read or update — from one schema, with validation enforced for both humans and machines.

Key Takeaways

• Schema-first is non-negotiable in 2026: structured content is now the primary input layer for AI search, and the schema is effectively an API for reasoning machines.
• Use both axes: model the nouns of your domain as entity types (with URLs, slugs, lifecycle) and model layout as reusable blocks/components assembled in a page-builder array.
• Never store raw HTML: use Portable Text or an equivalent JSON-AST rich-text format so content serializes to web, Markdown, email, and voice — and stays queryable block-by-block.
• Reference, don't duplicate: references form your entity graph, which is exactly what AI systems use to verify context and decide citation confidence; add sameAs and explicit synonyms.
• Validation is a dual contract: it guards human editors and constrains what AI agents may write back through the API/MCP layer; make alt text and slugs validated, required fields.
• Slugs and redirects are content: store slug history, 301 old → new, and model redirects as an editable type, not a code deploy.
• Model a publish state machine plus AI-specific governance: aiGenerated, reviewStatus, versioning, and a human gate before machine-authored content goes live.
• Design for four consumers at once: humans, AI agents (write machine-readable field descriptions; co-locate embeddings; expose via MCP), omnichannel delivery, and answer engines (generate schema.org JSON-LD and llms.txt deterministically from the model).

Key References

• Storyblok. Structured Content for the AI Era. 2026. https://www.storyblok.com/mp/structured-content — Frames structured content as the primary input layer for AI search and modular reuse across channels.
• Sanity. Your CMS Is Already an AI Backend. 2025. https://www.sanity.io/your-cms-is-already-an-ai-backend — Argues structured schemas make a CMS directly consumable by AI; basis for the "schema is the prompt" thesis.
• portabletext (GitHub). Portable Text Specification. 2025. https://github.com/portabletext/portabletext — The open JSON spec for block content used throughout the chapter.
• Sanity Docs. Beginners Guide to Portable Text. 2025. https://www.sanity.io/docs/developer-guides/beginners-guide-to-portable-text — Block/span/markDefs structure and queryability of rich text.
• Sanity Docs. Creating a Parent/Child Taxonomy. 2025. https://www.sanity.io/docs/developer-guides/parent-child-taxonomy — Hierarchical references with validation filters and the -> dereference operator.
• Cosmic. Content Modeling Best Practices: Designing Scalable Headless CMS Architectures. 2025. https://www.cosmicjs.com/blog/content-modeling-best-practices-designing-scalable-headless-cms-architectures — References vs. plain-text fields, additive-change discipline.
• Kontent.ai. URL Redirects in Headless CMS: Code Samples. 2025. https://kontent.ai/blog/how-to-handle-url-redirects-with-headless-cms/ — Slug-history pattern and old→new redirect handling.
• Afteractive. Best Practices for Structuring Content in a Headless CMS. 2025. https://www.afteractive.com/blog/best-practices-for-structuring-content-in-a-headless-cms — Draft→Review→Published state-machine modeling.
• Sanity. Agent Context: Structured Context for AI Agents. 2026. https://www.sanity.io/agent-context — Schema compression, field descriptions, and MCP for agent comprehension.
• CMS Critic. Sanity's AI Content Operating System Powers Intelligence with Structure. 2026. https://cmscritic.com/sanitys-ai-content-operating-system-powers-intelligence-with-structure-and-agents-with-context — Embeddings co-located in the Content Lake; agentic generation/audit/publish.
• llmcms.org. 7 CMS Platforms With the Best MCP Server Support for AI Agents in 2026. 2026. https://www.llmcms.org/guides/best-cms-mcp-server-support-ai-agents-2026 — MCP as the 2026 standard integration layer for schema reading and mutations.
• GEO Compass. Schema.org for AEO and GEO: Which Structured Data Actually Matters. 2026. https://guptadeepak.com/geo-compass/guides/schema-for-aeo-and-geo/ — Entity graphs, citation confidence, schema-as-source vs. schema-as-signal.
• AirOps. How to Implement Schema Markup for Answer Engine Optimization. 2026. https://www.airops.com/blog/schema-markup-aeo — FAQPage uplift in AI Overviews and JSON-LD as the scalable format.
• Codersera. llms.txt Explained (May 2026): The Spec, Adoption, and How to Ship One. 2026. https://codersera.com/blog/llms-txt-complete-guide-2026/ — Current llms.txt format, adoption status, and Mintlify auto-generation.
• Chin, Tristan. End-to-End Type Safety for Sanity GROQ Queries. 2025. https://www.chintristan.io/blog/end-to-end-type-safety-for-sanity-groq-queries — TypeGen + Zod validation across the schema→query→app boundary.