Content Modelling

Content Model Strategies #

Before choosing base types or composition behaviors, you pick an approach for discovering the model itself. Every approach serves the same two principles: separate content from presentation (so the design can change without re-modelling) and design for reuse (so a block built once works everywhere). There are three common approaches. Docs ↗

The hybrid approach in practice - how this repo's Mosey Bank model was built:

The Three-Tier Model #

Every piece of content in Visual Builder lives at one of three levels. Knowing these levels tells you which compositionBehaviors to give a block, and how editors build pages - before you write a single line of component code. SDK docs ↗

Experience  (DynamicExperience / LandingPage)   ← the page - owns the URL and SEO metadata
└── Section  (BlankSection / FaqContainerBlock)  ← layout container - groups elements into rows/columns
    └── Element  (HeroBlock / StatsCounterBlock) ← a single block with nothing inside it

FaqContainerBlock has sectionEnabled and a type: "array" property - so editors add FaqItemBlock children directly on the section in Visual Builder. The SDK's built-in BlankSection works the same way at the layout level, but it accepts any elementEnabled block rather than a fixed list of allowed types.

Page Types - Experience vs Page #

Optimizely SaaS CMS supports two base types for pages. Which one to use determines whether a page's layout is owned by the editor in Visual Builder or by the developer in React code. SDK docs ↗

Governance - Editor Flexibility vs Lockdown #

A content model is also a set of guardrails. Too loose and editors can break brand and layout consistency; too tight and every small change needs a developer. Good modelling opens up the content - the copy and imagery editors own - while locking down the structure - the layouts and block types the brand depends on. SDK docs ↗

elementEnabled vs sectionEnabled #

compositionBehaviors is the single most important property on a content type. It controls where editors can place a block in Visual Builder and whether it can contain other blocks. SDK docs ↗

Rule of thumb: if the block has a type: "array" property → sectionEnabled. A single block with nothing inside it → elementEnabled. Unsure → both.

// src/components/blocks/StatsCounterBlock/index.tsx
export const StatsCounterBlockType = contentType({
  key: "StatsCounterBlock",
  baseType: "_component",
  compositionBehaviors: ["elementEnabled"], // leaf - no children
  properties: {
    value:  { type: "string" },
    suffix: { type: "string" },
    label:  { type: "string" },
  },
});

// src/components/blocks/FaqContainerBlock/index.tsx
export const FaqContainerBlockType = contentType({
  key: "FaqContainerBlock",
  baseType: "_component",
  compositionBehaviors: ["sectionEnabled"], // container - can hold children
  properties: {
    heading:  { type: "string" },
    faqItems: {
      type: "array",                          // content area - editors add items here
      items: { type: "content", allowedTypes: [FaqItemBlockType] },
    },
  },
});

Name for Purpose, Not Appearance #

Content type names should describe what the content is, not how it looks today. Visual names break the moment the design changes - and they mislead editors about what belongs inside a block. Display templates handle the how it looks side.

// Good - describes what the content IS
export const TestimonialBlockType = contentType({ key: "TestimonialBlock", … });
export const PricingTierBlockType  = contentType({ key: "PricingTierBlock",  … });
export const SectionHeadingBlockType = contentType({ key: "SectionHeadingBlock", … });

// Avoid - describes how it looks today (breaks after a redesign)
export const BlueCardBlockType     = contentType({ key: "BlueCardBlock",     … });
export const BigBoldHeadingType    = contentType({ key: "BigBoldHeading",    … });
export const ThreeColumnGridType   = contentType({ key: "ThreeColumnGrid",   … });

Display Template vs New Content Type #

The most common modelling decision: should a visual variation be a new content type or a display template on an existing one? It comes down to whether the fields are different. SDK docs ↗

// src/components/blocks/TestimonialBlock/index.tsx
// One content type - identical fields - two visual presentations.
export const TestimonialCardTemplate = displayTemplate({
  key: "TestimonialCardTemplate",
  displayName: "Quote in a card (boxed)",
  contentType: "TestimonialBlock",
  tag: "Card",              // links to resolver tags.Card
  settings: {
    theme: {
      editor: "select",
      choices: {
        default: { displayName: "White" },
        brand:   { displayName: "Dark blue (brand)" },
      },
    },
  },
});

export const TestimonialMinimalTemplate = displayTemplate({
  key: "TestimonialMinimalTemplate",
  displayName: "Inline quote, no background",
  contentType: "TestimonialBlock",
  tag: "Minimal",           // links to resolver tags.Minimal
  settings: { … },
});

// Registry maps both tags to the SAME component - it reads displayTemplateKey
// to switch rendering logic internally.
TestimonialBlock: {
  default: TestimonialBlock,
  tags: { Card: TestimonialBlock, Minimal: TestimonialBlock },
}

Content Reuse: Inline vs Referenced #

Blocks can be composed inline - created inside a page's Visual Builder session - or referenced - existing as independent CMS items linked from multiple pages. The choice affects how Graph fetches the data and how editors manage it. SDK docs ↗

// Inline composition - content lives inside the page composition.
// Graph inline-expands type:"array" automatically. No extra fetch needed.
export const ProductHeroBlockType = contentType({
  properties: {
    title:    { type: "string" },
    features: {
      type: "array",
      items: { type: "content", allowedTypes: [FeatureItemBlockType] },
    },
  },
});

// type: "contentReference" - the one type Graph does NOT inline-expand.
// The field is typed "ContentReference" in Graph: you get { key, url } only,
// and inline fragments are rejected. Resolve the full item in the PARENT.

// src/components/pages/ArticlePage.tsx
export default async function ArticlePage({ content }) {
  // content.author is a type:"contentReference" - only { key, url } arrived
  const author = content.author?._metadata?.key
    ? await getClient()
        .getContent({ key: content.author._metadata.key }, { next: { revalidate: 300 } })
        .catch(() => null)
    : null;

  return (
    // author is now the full AuthorBlock - render its name, bio, avatar
    <article>
      {author && <OptimizelyComponent content={author} />}
    </article>
  );
}

The four ways to relate content #

The inline-vs-referenced choice above is really a spectrum of four property types. They differ in how tightly the child is coupled to its parent, how Graph resolves them in queries, and whether editing the child affects every parent that uses it. SDK docs ↗

// type: "component" - inline embed
// The child is stored inside the parent record. No independent CMS identity.
cta: {
  type: "component",
  contentType: ButtonComponentType,
  displayName: "CTA Button",
}

// type: "content" - Content Area Item (single slot)
// The parent stores a pointer to an independent content item.
// Graph DOES inline-expand it - the SDK generates a fragment per allowed
// type, so all fields arrive in the page query. No self-fetch needed.
featuredBlock: {
  type: "content",
  allowedTypes: [FaqContainerBlockType],
  displayName: "Featured FAQ Block",
}

// type: "array" - Content Area (ordered list)
// Graph DOES inline-expand these - all item fields arrive in the page query.
faqItems: {
  type: "array",
  items: { type: "content", allowedTypes: [FaqItemBlockType] },
  displayName: "FAQ Items",
}

// type: "contentReference" - reference to existing content only
// Editors pick from the content tree - they cannot create inline.
// With allowedTypes: Graph returns _metadata (key + url) only.
// With contentType (specific type): Graph returns the full object.
backgroundImage: {
  type: "contentReference",
  allowedTypes: ["_image"],
  displayName: "Background Image",
  indexingType: "disabled",
}

CMS terminology vs SDK types

The Optimizely CMS UI and the official docs use different names than the SDK property types. This table maps them so you can read either without confusion.

Content drift and single source of truth #

The reason the reference-vs-embed choice matters editorially: embedded content diverges over time. The more pages that hold their own copy of a piece of content, the higher the chance that some copies get updated and others don't. This is content drift - an editorial risk, not a developer bug.

When to reference vs embed

Choosing the Right Property Type #

Each property type gives the editor a different input in the CMS, and comes back in a different shape from Graph. Choosing the right one affects both the editing experience and how you render the field in React.

// string - short text, no formatting
headline:  { type: "string", displayName: "Headline", indexingType: "searchable", isLocalized: true },
badge:     { type: "string", displayName: "Badge Label",   isLocalized: true },
ctaText:   { type: "string", displayName: "Button Label",  isLocalized: true },

// richText - long-form, editor gets a formatting toolbar
// Graph returns { json: {...} } - render with <RichText content={bio.json} />
bio:  { type: "richText", displayName: "Author Bio",    indexingType: "searchable", isLocalized: true },
body: { type: "richText", displayName: "Article Body",  indexingType: "searchable", isLocalized: true },

// url - Graph returns { default: "https://…" }
// Unwrap with: const href = value?.default ?? value
ctaLink:     { type: "url", displayName: "Button URL" },
linkedinUrl: { type: "url", displayName: "LinkedIn Profile" },

// contentReference - single image or content item
// Graph returns only base metadata (_metadata.url, displayName, key).
// If you need full field data → resolve in the parent page component.
authorImage:     { type: "contentReference", allowedTypes: ["_image"],   indexingType: "disabled" },
backgroundImage: { type: "contentReference", allowedTypes: ["_image"],   indexingType: "disabled" },

// array - ordered list, inline-expanded by Graph automatically
// Use this for content areas editors populate in Visual Builder.
faqItems: {
  type: "array",
  items: { type: "content", allowedTypes: [FaqItemBlockType] },
},
logos: {
  type: "array",
  items: { type: "content", allowedTypes: ["_image"] },
},

Fetching Referenced Content #

For most blocks you do not write a GraphQL query at all. client.getContentByPath() in the catch-all page route fetches the full composition - every section, every inline element - in one request automatically.

The exception is referenced content. Graph does not include the full data for single type: "contentReference" properties - the component receives just the basics (the item's key). To get the full field data, call getClient().getContent({ key }) directly inside the component. No GraphQL query, no fragment file needed. SDK docs ↗

// src/components/pages/ArticlePage.tsx
// The page receives an author contentReference - Graph returns only its key.
// getClient().getContent() fetches the full item without writing a query.
import { getClient } from "@optimizely/cms-sdk";

const author = await getClient().getContent(
  { key: content.author._metadata.key },
  { next: { revalidate: 300 } }
);

// src/components/blocks/TimelineBlock/index.tsx
// milestones is a contentReference array - each item arrives as a key only.
// Fetch all in parallel; order is preserved by Promise.all.
import { getClient } from "@optimizely/cms-sdk";

const milestones = await Promise.all(
  keys.map((key) =>
    getClient().getContent({ key }, { next: { revalidate: 300 } })
  )
);

Graph Indexing and Localization #

Two per-field settings control how Graph stores and serves your content: indexingType decides whether a field can be searched or filtered in Graph queries, and isLocalized tells the CMS to store a separate value for each language.

indexingType

Only three values exist. The main rule: "searchable" and "queryable" work on basic value fields only (string, richText, integer, dateTime, boolean). The CMS rejects them on contentReference fields - those only accept "disabled".

// indexingType controls how Graph indexes a property.
// Only three values exist - and not all are valid on every type.

// "searchable" - full-text search. Apply to prose a user would type.
headline:    { type: "string",   displayName: "Headline",     indexingType: "searchable" },
bio:         { type: "richText", displayName: "Author Bio",   indexingType: "searchable" },
question:    { type: "string",   displayName: "Question",     indexingType: "searchable" },

// "queryable" - filter / sort in Graph. Apply to metadata, not prose.
publishDate: { type: "dateTime", displayName: "Publish Date", indexingType: "queryable" },
category:    { type: "string",   displayName: "Category",     indexingType: "queryable" },
navOrder:    { type: "integer",  displayName: "Nav Order",    indexingType: "queryable" },

// "disabled" - exclude from the index. Required on image contentReferences.
// contentReference fields only accept "disabled" - "searchable" / "queryable"
// are not valid on reference types and will be rejected by the CMS on push.
heroImage:   { type: "contentReference", allowedTypes: ["_image"], indexingType: "disabled" },

// omitting indexingType entirely - fine for fields you never query
ctaText:     { type: "string",   displayName: "CTA Text" },

isLocalized

When isLocalized: true is set, the CMS stores a separate value for each language - editors can provide a French headline and an English headline for the same block. Without it, all languages share a single value.

// isLocalized: true - editor stores a separate value per language.
// Add to every field a site visitor reads. Omit from structural fields.

// Localize: all user-visible text
headline:    { type: "string",   displayName: "Headline",  indexingType: "searchable", isLocalized: true },
body:        { type: "richText", displayName: "Body",      indexingType: "searchable", isLocalized: true },
columns:     { type: "json",     displayName: "Columns",                               isLocalized: true },
altText:     { type: "string",   displayName: "Alt Text",                              isLocalized: true },

// Do NOT localize: URLs, booleans, integers, dates, enums, identifiers
ctaLink:     { type: "url",      displayName: "CTA URL" },     // same URL for all locales
highlighted: { type: "boolean",  displayName: "Recommended" }, // structural flag
navOrder:    { type: "integer",  displayName: "Nav Order" },   // sort order
publishDate: { type: "dateTime", displayName: "Publish Date" }, // same timestamp
category:    { type: "string",   displayName: "Category",  indexingType: "queryable" }, // enum key