About the content model

Picked splits your content into three pieces: a Model, a Block, and a content entry. Why three, when a page editor needs only one?

Schema and data are separate

A Model is a schema. It sets which fields a piece of content can hold, and it holds no data itself. A content entry is one instance of that schema, filled with real values.

One Model backs many entries. Describe a campaign page one time, then make many pages from it. Each entry carries its own title, its own body, and its own image, but they all share the shape.

That split is also what lets your code depend on content that it never saw. Your component reads content.title because the Model promises a title. It works for every entry that comes from that Model.

A category gives a Model a role

A Model can carry a category, and the category decides what the Model gives its shape to. A page layout backs a standalone Page. A step layout backs one Step inside a Flow.

The category is fixed because it decides where the SDK renders the entry. That is not a property that you can change under an entry that exists already.

A Model can also carry no category. Such a Model has no layout role, and nothing renders its entries directly. It holds the content that other content points at, such as a product or a category of your own. See About content references.

The three roles are one machine. A layout is a Model with a job in the render path. A Model with no category is the same machine with no such job.

A Block is a schema fragment

A Model gives shape to a whole page or a whole step. A Block is a part that you put inside one or more Models.

Define a hero one time as a Block, then point at it from every Model that needs one. Change the Block and every Model that holds it changes with it.

This is the reason Blocks exist at all. Without them you must describe a common structure again in each Model, and the copies then become different. It is the same argument for one fact in one place that runs through the rest of this documentation.

A Block sits inside the entry that embeds it. It has no entry of its own, and no id that you can point at.

That is the difference between a Block and a reference. A Block is a shape that many entries hold. A reference is a pointer at one entry that many entries share.

Why a schema change does not migrate your data

Change a Model or a Block, and Picked does not rewrite the entries behind it. An entry that no longer matches its schema becomes invalid, and the dashboard shows an error on each field that does not fit.

That is deliberate. An automatic change must decide what a new required field holds for every entry that came before it. Any value that it chooses is content that nobody wrote. Picked reports the error instead, and you correct it.

The cost is real. After a schema change, check every entry that uses that Model and fix each error before you publish. Picked serves valid content only, so an entry with an error does not reach a visitor.

An error points at the exact field

A validation error carries a path in JSON style, such as sections[0].data.title. The path holds through nested groups, repeated fields, and Blocks. An error inside a repeated group therefore tells you which item in that group holds it.

Models — every field type.
Blocks — the reusable fragments.
Content entries — the editor and the validation.
About content references — how one entry points at another.
About pages and flows — which category you need.