When to Use

Verify a composition actually resolves (a 200 does not mean it does), and the full pitfall table for API-authored compositions.

Part of the API-authoring set. Start at author-composition-via-api, which routes to this one.

Verify the write: a 200 does not mean the composition resolves

Nothing validates that a static_value key on a node exists in the entry’s bucket. Write half the pair and the CMA still returns 200. The canvas then renders every affected prop as its registration defaultValue, which looks like a working section made of placeholder copy.

Worked failure. A hero was authored with all seven props stripped to static_value. The write returned 200. The canvas showed “Your headline here” and two buttons both reading “Get started”, indistinguishable from a deliberate skeleton. The entry actually held:

"static_value": {
  "boolean": [ { "value": false, "_metadata": { … } } ],   // ⛔ no "key"
  "href":    [ { "value": "#",   "_metadata": { … } } ],   // ⛔ no "key"
  "choice":  [], "imageurl": [], "number": [], "object": []
}                                                          // ⛔ no "text" bucket at all

Every item was missing its key, and the bucket holding the headline and button labels was never written. Zero of the bindings could resolve, and nothing anywhere reported it.

Run this check after every write. It is three lines and catches the entire class:

1. Re-fetch the entry and decompress ui.
2. Walk the tree collecting every (props.<name>.type, binding.value) pair where binding.type === "static_value".
3. Assert each one has a matching {key} in static_value[<bucket-for-that-type>]. Any miss is a prop that will silently render its default.

Do the same before writing, against the payload you are about to send. On the corrected hero the counts read refs=26 statics=26 missing=[]. The original would have reported 7 missing keys and 1 absent bucket.

The same discipline applies to template bindings: decompose-design § Step 8b is this check at plan time, and build-section § Field-existence gate is it at bind time. A prop that silently falls back to defaultValue is the single failure mode all three exist to catch.

Preflight: assert the envelope on every node before you write

The rule above is stated. Nothing enforces it. A sweep of one live stack found 54 nodes across 10 compositions missing slots (the whole pricing family plus two carousels), every one authored by tooling that skipped it on leaves. They rendered fine for months and only surfaced as a white screen when someone opened the Data tab.

So check the payload you are about to send, and the entry after you write it:

for every node in the ui tree:
  assert all of ("uid","type","props","metadata","slots","attrs","styles") are present and non-null

Three lines, catches the entire class. Run it in the same pass as the static_value key check, same idea, different envelope. On a correct composition it reports zero. On the pricing sections above it would have reported 4, 8, 11.

Repairing existing data is additive: insert "slots": {} where the key is absent, leave everything else untouched. Note it creates an unpublished version on a published composition, so republish afterwards or the live entry keeps the old shape.

Common Pitfalls