Content Modelling

The Three-Tier Model #

Every piece of content in Visual Builder lives at one of three levels. Understanding this hierarchy determines what compositionBehaviors to assign and how editors build pages - before writing 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) ← leaf block - pure content, no children

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 accepts any elementEnabled block rather than a typed list.

Page Types - DynamicExperience vs TraditionalPage #

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 ↗

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. Pure content, no children → 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? The answer hinges on whether the fields differ. 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] },
    },
  },
});

// Referenced content - block exists independently, linked from many pages.
// Graph returns only base metadata (_Content) for type:"content" single references.
// Resolve the full item in the PARENT PAGE before passing it down.

// src/components/pages/TraditionalPage.tsx
export default async function TraditionalPage({ content }) {
  let featuredBlock = content.featuredBlock ?? null;

  // featuredBlock came back as _Content (base metadata only) - fetch the full item
  if (featuredBlock?.__typename === "_Content" && featuredBlock?._metadata?.key) {
    featuredBlock = await getClient()
      .getContent({ key: featuredBlock._metadata.key }, { next: { revalidate: 60 } })
      .catch(() => null);
  }

  return (
    // featuredBlock is now fully resolved - OptimizelyComponent can dispatch it
    <div>
      {featuredBlock && featuredBlock.__typename !== "_Content" && (
        <OptimizelyComponent content={featuredBlock} />
      )}
    </div>
  );
}

Choosing the Right Property Type #

Each property type maps to a different editor experience in the CMS and a different shape in the Graph response. Choosing correctly affects both the editing UX 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 inline-expand single type: "contentReference" properties - the component receives only base metadata (the item's key). To get 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 property-level settings control how Graph stores and exposes your content: indexingType determines whether a field can be searched or filtered in Graph queries, and isLocalized tells the CMS to store a separate value per language.

indexingType

Only three values exist. The key constraint: "searchable" and "queryable" are valid on primitive 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