Read shape vs write shape
Many fields are written in one shape and read back in another. You write a reference as the target's id and read back the whole entry; you write an option as its key, slug, or label and read back its key with the label and slug. Send what the field expects on write, and never send a read value back without converting it.
Many fields are written in one shape and read back in another. You write a reference as the target's id and read back the whole entry; you write an option as its key, slug, or label and read back its key with the label and slug. Send what the field expects on write, and never send a read value back without converting it.
Requirements
None to read. For the exact write shape of each field in a collection, ask the agent to describe the collection first; see What the tools cover.
Why the shapes differ
The write shape is the smallest thing that identifies a value: an id, a key, a pointer. The read shape is what a person or an agent needs to use the value without another lookup: the referenced entry itself, the option's label, the image's address and size. Writing the rich form back would duplicate data that lives elsewhere; reading the bare form would force a second request for every value.
Field by field
| Field | You write | You read |
|---|---|---|
| Text, number, price, switch, link, date | The value | The same value |
| Option | A list of the option's key, slug, or label | Each chosen option by its key, with its label and slug |
| List | A list of text values | Each value with its label and slug |
| Reference | The target entry's id | The whole referenced entry, or empty if it was archived |
| Multi-reference | A list of entry ids | The referenced entries; archived ones drop out |
| People | A list of user identifiers | Each user's name, username, and email |
| Image, gallery, file | A pointer to an asset in the library | The file's address, type, size, and for images the dimensions |
| Location | Locations and their departments | Each location in full, with address, timezone, country, and departments |
| Parent | The parent entry's slug | The slug, plus the parent's name alongside |
| Email, phone, address groups | Items keyed by their sub-field | The same |
Notes and limitations
- Option keys can change. Editing an option field's list of choices regenerates the keys of every option. The slug stays stable, so store and compare options by slug.
- Secret fields. A password field is never returned at all; leaving it out on write keeps the stored value. A field declared secret is returned only to members of the business, never to the website, exports, or AI views.
- Computed fields. Rollups and lookups appear on read and are refused on write.
- A third spelling. A CSV export writes values for a person: option labels, reference names, dates in the field's own format. It is neither the read nor the write shape.
- What the save changes. On save, a missing slug is generated from the name, some booking times are aligned to their slot, and field rules can fill or clear fields. Read the saved entry back rather than assuming it matches what you sent.
Related
For how references behave, see How references connect entries; for field types in general, Fields: built-in and your own.