Machines Are Reading Your Content Model

How Optimizely CMS (SaaS) separates presentation intent from content — and why that now matters for AI discoverability.

Start with a requirement that looks completely reasonable

A client asks for a Heading content type. The requirements are modest:

• A field for the heading text

• A dropdown so the author can choose H1 through H6

• A toggle for an underline

• A colour choice for that underline — red or white

Nothing here is unusual. Most of us have built something close to it. It takes an afternoon, the client is happy, and the content type ships.

Before going further, the sanity checks are worth doing — because sometimes the answer is simply "this is fine":

• Is this a one-off page, or a pattern that will repeat across the site?

• If the brand colour changes next year, how many content items need editing?

For a small site updated twice a year: build the dropdown and move on. Not every project needs an abstraction layer.

But on an enterprise build with hundreds of pages and a multi-year lifespan, those questions start to sting. And there is a fourth one that has only recently become interesting:
what does a machine see when it reads this page?

The actual problem: a vocabulary mismatch

A headless CMS is designed to store meaning. Authors think and speak in appearance — bigger, bolder, red, underlined. That is not a failure on their part. It is the only vocabulary any CMS has ever offered them. Text field, dropdown, colour picker: the interface quietly teaches everyone that appearance is a thing you store.

So when an author asks for a style option, they are very often expressing a semantic fact in visual language. When we build exactly what was asked for, we store the visual consequence and throw the semantic fact away.

Look again at those three requirements. They are not three styling options — they belong to three different layers.

"H1 through H6" — when an author picks H3, they are rarely thinking about document outline. They are thinking "I want text roughly this big." A heading level is a statement about document structure. Size is a statement about visual emphasis. The author was asking for the second and we gave them control over the first. That is how pages end up with three H1s, or an outline that jumps from H2 straight to H5.

"Red or white" — ask why they want white. In my experience the answer is always: "because on the dark sections the red doesn't work." The author is not choosing a colour. They are restating the background of the section they are sitting in, by hand, on every heading. The section already knows whether it is light or dark. Let the heading inherit from that.

"Underline on or off" — this one survives. It is genuinely decorative and the author's judgement is the right input. Although even here, a name like accent travels better than underline, because it describes the role rather than the rendering.

One out of three requirements was really a style choice.

A three-layer way of thinking about it

Most teams think in two layers — content and style — and that is why the boundary collapses. There is a third layer in the middle that tends to get forgotten.

The two failure modes are collapsing the middle layer into either neighbour. Push it into content and you get colour values in your content types. Push it into implementation and authors lose all control — and start requesting new content types instead.

A practical test: would this value still mean something to a channel that has no screen? "This is the primary call to action" survives. "This is #0A2540 with 24 pixels of padding" does not.

Where Optimizely CMS (SaaS) fits

This is the part I find genuinely well designed.

In CMS (SaaS), display templates are defined separately from the content type's property schema. You define templates that carry settings, and Optimizely Graph indexes the selected template and settings alongside the content and delivers both to the front end. Each node in the composition model can carry a displayTemplateKey and a set of displaySettings — key/value pairs the front end interprets however it likes. See Configure Visual Builder and Manage styles for the details.

That separation is exactly the middle layer the three-layer model is asking for. The platform gives you a dedicated channel for presentation intent that never touches your content schema.

What the platform cannot do is police the vocabulary you put in it. A display setting choice is a string — it will happily store "primary" or "#E4002B" and return either one. Which leads to the single highest-leverage habit in this whole discussion, and it costs nothing: the stored key and the label the author sees are separate values. Let the author see "Red" and "White". Store "primary" and "inverse". The client gets precisely the choice they asked for. You keep the abstraction. When red becomes crimson, you change one token.

To make the difference concrete, here is the shape of both approaches. These are conceptual illustrations — not production schemas — but the pattern is the one worth internalising.

The approach to avoid — presentation stored directly as content type properties:

// Illustrative — shows the pattern to avoid
{
  "key": "HeadingElement",
  "properties": {
    "text":            { "type": "string" },
    "headingTag":      { "type": "string" },
    "underlineColour": { "type": "string" }
  }
}

Every channel that is not a web browser now receives a heading tag and a colour hex value it has no use for.

The cleaner approach — content type holds only content, display template carries intent:

// Content type — only what is semantically true
{
  "key": "HeadingElement",
  "properties": {
    "text":          { "type": "string" },
    "levelOverride": { "type": "string" }
  }
}

// Display template — semantic intent, not visual values
// The author sees "Red" / "White". Graph stores "primary" / "inverse".
{
  "key": "HeadingStyle",
  "contentType": "HeadingElement",
  "settings": {
    "size":         { "choices": { "large":   { "displayName": "Large"      },
                                   "medium":  { "displayName": "Medium"     } } },
    "accent":       { "choices": { "none":    { "displayName": "None"       },
                                   "rule":    { "displayName": "Underlined" } } },
    "accentColour": { "choices": { "primary": { "displayName": "Red"        },
                                   "inverse": { "displayName": "White"      } } }
  }
}

The author gets the control they asked for. Graph delivers clean semantic keys. The front end resolves the token. The heading arrives usable on every channel.

Conceptually, the front end then owns a single mapping from semantic intent to channel-specific implementation — the only place that knows what "prominent" actually looks like on this channel. That is the pattern worth establishing, whatever your stack.

If you would rather not hand-write display template payloads, Opal Chat exposes tools for listing, retrieving, creating and updating them conversationally — which also makes auditing straightforward. Asking for a list of every display template and its choice keys is a quick way to spot hex values that have crept in.

The part that has changed recently

Until recently, the argument for keeping presentation out of content ran into a simple objection: "we are a web-only business." And the counter-argument — hypothetical future channels — never beats a delivery date.

That objection is weaker now, because there is a channel already consuming this content that nobody commissioned.

When an AI system reads a page — for a summary, an answer, a citation — it works primarily with text and structure. A red underline communicates nothing to it. Heading hierarchy, on the other hand, is one of the main signals for understanding how a document is organised and where one idea ends and the next begins. That H1-to-H6 dropdown, built in good faith as a small author convenience, is quietly working against discoverability in a channel the client does care about.

I want to be careful not to overstate this. Crawlers vary in sophistication, and large language models are genuinely capable of extracting meaning from messy documents. This is not a claim that a disorganised heading structure makes you invisible. It is a claim about direction: the more meaning that lives in structure rather than appearance, the more of it survives into a system that cannot see your stylesheet. The general guidance for AI-era discoverability — crawlability, clear structure, structured data — is the same advice good content modelling has always produced as a by-product.

Look at how Optimizely's own Opal agents interact with this, because their operational requirements illustrate the point clearly.

The GEO Schema Optimization agent analyzes page content and preview URLs to generate JSON-LD schema markup, which it writes directly back into a schema property in CMS. While the agent can parse rendered HTML, the output needs a structured home. If your content model provides explicit metadata fields and a designated schema property, the workflow is automated and durable. When metadata has to be reverse-engineered from visual text styles, the process becomes lossy.

Similarly, the SEO Metadata Implementation agent evaluates SEO properties and updates metadata fields in CMS (SaaS). For an agent to push automated improvements, the destination fields must exist in the content model. If title or description semantics are treated merely as visual heading blocks rather than typed metadata, automated governance has nowhere to land its changes.

The Content Model Creation agent takes a URL or image and suggests a content model, specifically comparing its recommendations against your existing content types to classify them as "New" or "Modified". This is where content modeling habits compound: the agent references what is already registered in your CMS instance. If your existing models are already cleanly separated into content fields and display templates, new recommendations naturally align with that standard. If existing types mix styling flags into content properties, extending them propagates that debt.

AI agents are effective at analyzing and automating workflows across your CMS, but their leverage depends on the clarity of the underlying schema. Clean structure gives automation clean inputs and reliable destinations.

Honest limitations

This model is not complete, and it is worth saying so before someone else does.

• Reused content across surfaces — "the parent owns surface, the child owns emphasis" works well in hierarchical composition. When a block genuinely appears in both a light section and a dark one, inheritance is not enough, and I do not think there is one settled answer yet.

• Vocabulary discipline — a semantic layer is only as stable as the names in it. Someone has to own that vocabulary across teams and years. A hex value is at least unambiguous.

• Scale — most of this assumes an enterprise build with a long life and multiple teams. For smaller projects the machinery can outweigh the problem.

The question that does most of the work

If there is one thing worth taking from this, it is a question to ask in the next content modelling session, whenever someone requests a visual option:

"Why do you want to be able to choose that?"

The answer is usually a semantic fact wearing visual clothing.

• "H1 through H6" → I want it this big → that is size

• "Red or white" → the background is dark → that is theme

• "Underline it" → sometimes it really is just decoration, and that is fine

One of those three was a genuine style choice. Finding out which is the whole exercise.

Your content model is a contract. You have always been signing it on behalf of your authors and your developers. The new part is that you are now also signing it on behalf of every machine that helps decide whether anyone finds you.