Exo Content Bindings

ExO Content Bindings — Data Assembly Creator

Overview

Creates Data Assemblies that connect existing Contentful entries to Experience Orchestration component types. A Data Assembly is a parametrized query with a known return type — it describes how entry fields hydrate a component’s content properties.

Mental model — four layers:

This skill operates at the Recipe layer — creating and publishing Data Assemblies.

The invariant that makes the model work: the component tree always reads through $contentProperties/... — never directly from an entry, never from $contentBindings/.... Every binding strategy exists to fill a content property. A binding that fills no content property computes data nothing reads. Use this as a correctness check on any DA you design: trace each return key to a declared content property, or delete it.

The practical consequence: from the component’s point of view, a manual value and a DA-hydrated value are indistinguishable. It just reads a content property. That is why the DA-vs-literal choice is a modeling decision, not a rendering one.

Terminology

Precise language prevents misunderstandings between these easily conflated concepts:

Tool access

This skill calls the Contentful Management API (CMA) directly. Prefer curl (via Bash) when a shell is available — the examples in references/ use it. If no shell/exec tool is available, make the equivalent calls through the contentful-mcp MCP tools instead (same endpoints and payloads, translated to whatever tool the server exposes for spaces/component types/data assemblies). If neither curl nor contentful-mcp is reachable, say so explicitly and stop — do not guess at space state or fabricate a plan without introspecting first.

Content property vs. design property

A content property is content, not presentation. Before designing any mapping, apply this test to each property:

• Changing the value changes what is said → content property (bindable; a DA may fill it)
• Changing the value changes how it looks → design property (never bind it)

Apply the test explicitly rather than guessing from the property name, and rather than relying on which array the property appears in. variant, columns, backgroundColor, showDivider, theme, alignment are design properties even when their values happen to come from the CMS. A theme: light|dark field on a content type is the classic trap: it is CMS-authored, so it looks bindable, but it changes how the component looks, so it is not a content property and must not appear in a DA’s return map.

The converse also holds: a property whose name sounds decorative (badgeText, eyebrow, label) is a content property if changing it changes what the page says.

This test governs field-mapping inference (references/api-workflow.md step 5.3). A source field that fails it is not an unmapped content property — it is correctly unmapped, and should be reported that way in the Binding Plan rather than listed as a gap.

Process overview

1. Introspect the space — fetch component types and content types. Check for a reference space with the same components already wired.
2. Classify each component type — coded (leaf, all content properties public) vs. composite (tree, mix of direct + hoisted properties). See “Public vs. private” below.
3. Design DAs for coded and composite types separately — composites need extra care around hoisting and slot boundaries.
4. Infer field mappings, gated by the content-vs-design test and the public/private golden rule, then produce a Binding Plan and get explicit user approval before creating anything.
5. Create, link, and publish each Data Assembly, then verify and produce a mandatory Complete Binding Map.

Full CMA call sequences, request/response shapes, and exact commands for every step: references/api-workflow.md (opens in a new tab). Full resolver request bodies (entity, collection, nested-DA, asset/Media, deep binding, polymorphic): references/resolver-patterns.md (opens in a new tab). Pointer expressions, GraphQL conventions, RichText handling, and the type mapping table: references/richtext-and-types.md (opens in a new tab). A complete worked example end to end: references/worked-example.md (opens in a new tab).

Public vs. private

Not every content property in a composite is reachable from outside.

Public properties are the subset exposed on the component’s surface. Only public properties can be overridden by a parent embedding this component, targeted by a Data Assembly, or seen and edited by a marketer. They are the component’s stable content input contract.

Private properties belong to child components inside the componentTree and are not exposed. There is no privateProperties array — privacy is defined by absence: a child property is private precisely because it was not hoisted. Do not go looking for a list of private properties; enumerate the tree’s children and subtract what appears in the parent’s contentProperties.

The golden rule: never bind, override, or map a property that is not public. If something must be bound, it has to be hoisted first — which is a component-type change, outside this skill’s scope.

Hoisting rules

1. Required child content properties are automatically hoisted to the parent’s public surface
2. Optional child properties are hoisted intentionally — only when the designer decides the parent should control them
3. If a needed property isn’t in the parent’s contentProperties, it’s private — the component type must be updated first (out of scope)
4. Per-property hoisting and whole-component hoisting (TypeRef) are mutually exclusive for the same child
5. De-hoisting orphans DAs — if a public property is later un-exposed, every DA referencing it breaks. This is why checking existing DAs before adding another matters.

Rules 1 and 3 can contradict each other — say so when they do. If a child property is required on the child but absent from the parent’s contentProperties, rule 1 says it should have been hoisted automatically. Do not silently record it as “intentionally private.” Report it as a possible modeling or auto-hoisting defect for the component-type owner, alongside the blocked mapping. A required-but-unreachable property means the composite cannot render correctly from any binding.

Should a property be public?

You cannot change hoisting from this skill, but you will be asked whether something should be hoisted. Recommend hoisting when any of these hold:

• it is required by the child (automatic — see the contradiction rule above),
• a marketer must control it per instance,
• a DA needs to fill it — only public properties are bindable,
• a parent must override it when embedding the child.

Recommend keeping it private when:

• it is an internal implementation detail (a computed alt text, a layout-only string),
• exposing it adds noise without editorial value — hoisting every child property produces text1, text2, url1, url2… clutter, which is explicitly discouraged,
• nothing outside the child will ever bind to or override it.

Default posture: hoist the minimum that satisfies the four triggers; leave everything else private. A small, intentional public surface is the goal.

Slot boundaries

Slots create a hard DA ownership boundary:

Parent DA scope:
├── parent's contentProperties (direct + hoisted) ← DA targets these
├── componentTree children read via $contentProperties/... ← fed by parent DA
└── [SLOT: "main"]
    └── Child components placed here ← SEPARATE DAs, not parent's

Never attempt to map fields into a slot child’s properties from the parent’s DA.

Slot vs. content binding — the distinction that decides scope

Both are reference-shaped. They mean opposite things, and confusing them produces a structurally wrong experience.

How to tell: look at what the reference actually points to. If the target has its own visual structure (layout fields, design properties, nested presentational references), it is a slot. If it is flat domain data — categories, tags, profiles, events — referenced by many different types as a shared source, it is a binding.

The same distinction routes the request you were given. “Fill the slots” is ambiguous and resolves by context:

• Assembly — placing fragments/components into a template’s structural slots. Only when the user is actively building or changing a tree.
• Content binding — linking CMS entries to binding parameters on an already-assembled experience. The signal: the user is not asking to change layout, they want content connected to what already exists.

Phrases like “fill unlinked slots”, “populate empty slots”, “fill in missing entries” with no structural intent mean content binding on instances, not assembly — and not this skill either. This skill builds the recipes; it does not attach bindings to Experience or Fragment instances (see Limitations).

So when a request contains that phrasing, name it rather than only declaring it out of scope. Say which layer it belongs to, confirm that the DAs this skill creates are the prerequisite for it, and state what remains to be done afterwards — per instance, in the editor or via the instance API. Answering “out of scope” without naming the layer leaves the user unable to act.

You MUST produce a complete binding plan and get user approval before creating any Data Assemblies. Do not skip this step. Do not create DAs incrementally without a plan. See references/api-workflow.md (opens in a new tab) §5.4–5.5 for the plan format.

Quick Decision Guide

Steps 0a and 0b decide whether to bind. Steps 1–3 decide how. Do not start at Step 1.

Step 0a: Is this request even about Data Assemblies?
  "Bind entries to components" / "wire up content" / "create DA"
    → YES, this skill. Continue.
  "Fill the empty slots" / "populate this page" / "fill in missing entries"
    → Instance-layer content binding. This skill creates the prerequisite
      recipes but does NOT attach bindings to instances. Name the layer,
      create the DAs, then say what remains per instance.
  "Place these components into the template" / "build the tree"
    → Assembly, not binding. Not this skill.

Step 0b: Is this property a content property?
  Changing the value changes WHAT IS SAID   → content property, continue
  Changing the value changes HOW IT LOOKS   → design property, STOP.
      Never bind it. Report as correctly-unmapped, not as a gap.
      (theme, variant, columns, alignment, backgroundColor, showDivider —
       still design properties when the value comes from the CMS)
  Is it public (present in the component type's contentProperties)?
    NO → STOP. Golden rule: never bind a non-public property.
         Required on the child but absent here? → flag as a possible
         auto-hoisting defect, not as intentionally private.

Step 1: What kind of component type?
  CODED → all contentProperties are public, go to Step 2
  COMPOSITE → check contentProperties list:
    Has contentProperties? → go to Step 2 (they're all public/hoisted)
    No contentProperties? → this composite doesn't need a DA
      (content arrives via slot children, each with their own DA)

Step 2: What feeds this content property?
  Single entry's field(s)?
    YES → Entity resolver (kind: "entity", _node query)
      Needs fields from a linked entry (reference)?
        YES → How complex is the linked entry?
          Simple (1-2 fields) → Scalar deep bind (traverse ref in GraphQL query)
          Complex (own component) → TypeRef deep bind (nested DA)
          Limit: ≤ 3 hops from root entry
        NO  → Single GraphQL resolver (shallow bind)
  Array of entries?
    YES → Collection resolver (kind: "collection", ...Collection query)
  Fixed value?
    YES → Use $literal in return (no resolver needed)
  Polymorphic source (multiple possible types)?
    YES → Use $on to branch on __typename

Step 3: Is this property on a slot child?
  YES → Create a SEPARATE DA for that child (do not include in parent DA)
  NO  → Include in the component's own DA

Common Mistakes

Operating Principles

1. Introspect before designing — do not invent content-type fields, content properties, or IDs. The space’s schemas are the source of truth.
2. Content properties ≠ content-type fields — a content property is the target (on the component); a content-type field is the source (on the entry). They often have different names.
3. Validate paths against content-type metadata — a return mapping like _node/headline must correspond to an actual field on the source content type.
4. IDs are stable contracts — DA IDs, parameter IDs, and dataType IDs form contracts. Display names can change; IDs cannot after publication without a migration.
5. Reference traversal is typed — _node/author/name means “follow the author reference, then read name“. Each segment must be a valid field on the resolved type at that depth.
6. Only public properties are bindable — if a property isn’t in the component type’s contentProperties array, it cannot be targeted regardless of whether it exists internally. Never bind, override, or map a property that is not public.
7. Propose before creating — if the mapping between source fields and target properties is ambiguous (similar names, multiple candidates), present options and confirm.
8. Content, not presentation — a mapping target must pass the what-is-said / how-it-looks test. CMS-authored design values (theme, variant) are still design properties.
9. Every return key fills a declared content property — the tree reads only through $contentProperties/..., so a mapping that fills nothing is dead weight, not a spare.
10. An absent mapping beats a wrong one — leave low-confidence properties unmapped and name them in the Binding Plan. Wrong mappings produce plausible content in the right shape and are hard to spot.
11. Never claim to have unbound, replaced, or rewired anything — existing DAs are reused or extended, never silently displaced.

Limitations

• This skill creates Data Assemblies and links them to component types — it does not attach content bindings to experience/fragment instances
• GraphQL introspection not available via CMA — field names inferred from content type definitions
• Nested DA composition requires the referenced DA to already exist and be published
• $on type discriminator uses GraphQL __typename (PascalCase of content type ID)
• If a needed property is not hoisted (private), this skill cannot fix it — component type must be updated first
• Composites with no contentProperties don’t need DAs — all content flows through slot children
• The pointer language has no coalesce operator, so per-value fallbacks (e.g. asset description → title) cannot be expressed in a DA. They are resolved at design time by sampling; see references/resolver-patterns.md (opens in a new tab) “Asset (Media) fields”
• The CMA returns both drafts and published entries with no preference between them. Nothing in a DA’s parameter definition can express “prefer published” — allowedTypes filters by content type only. If publication state matters for a component, it has to be handled by the marketer at bind time or by the source content model, not here

Related Skills

• the contentful-guide skill — general Contentful concepts and API routing
• the contentful-migration skill — content model/schema changes (hoisting a property requires a component-type change, which is out of this skill’s scope)

Provenance

The procedure, resolver patterns, GraphQL conventions, and API call sequences here were developed and validated against live Contentful spaces. The judgment layer — the content-vs-design test, the public/private golden rule, “should a property be public?”, the slot-vs-content-binding distinction and request routing, and source-selection confidence — reflects hoisting and content-binding rules defined by Contentful’s Experience Orchestration platform. Where this file and the platform’s own behavior disagree, the platform wins — report the discrepancy rather than following this file.