Document form and Transit form

[chee]

Two different concepts are blurred together in Content Tree, and I think they should be teased apart.

I’m calling them "document form" and "transit form". Definitions:

• Document form :: The full ContentTree used to render a document, with all the external fields such as image.picture satisfied.
• Transit form :: The sparse ContentTree used when the ContentTree is in transit. All external fields are null or undefined.

1. Spark creates a Document form ContentTree for Preview, sends to Spark API
2. Spark API converts that to the Transit form for Content API
3. Content API stores & sends in Transit form
4. Customer Products Content Pipeline API receives Transit form, fetches externals
5. Customer Products Content Pipeline UI receives Transit form and external, builds Document form before render

You always have one or the other, never any mix.
image.picture is marked “optional” in ContentTree but it’s not optional! It must always be nullish in Transit form, and must always be a Picture in Document form.

Do you have any ideas on how to express this? Does it need to be expressed (i think yes)?