Custom fields (ACF)
When Advanced Custom Fields is active, a record’s custom fields become the fields object of the document. Reading a record exports the current field values, and writing sets them.
Requirements
Section titled “Requirements”ACF must be installed and active. The fields block that renders these values on the front-end needs ACF Pro.
How fields map
Section titled “How fields map”fields is a map of field name to value, mirroring the field group the theme defines.
- A group is a nested object.
- A repeater is a list of row objects, and you can add or remove rows freely.
- Flexible content is a list of sections, each tagged with
acf_fc_layout. You may only use layouts that already exist. - A simple field is a string, number or boolean.
Values are the stored ones, not the ones the theme displays, so a document exported and imported without edits changes nothing. In practice this means the following.
- A WYSIWYG field holds the HTML from the editor. WordPress display filters such as automatic paragraphs and smart quotes are not applied, and shortcodes stay as text.
- A date picker holds its storage format,
YYYYMMDD(for example"20261006"), whatever display format the field uses. - A true/false field is
trueorfalse. A value ACF never writes (left by an import or a changed field type) stays as stored, so it can never pass for the value a save would put in its place. - An image or file field holds the attachment id, or
nullwhen empty. A gallery or relationship holds a list of ids, and a post object holds an id (or a list when it allows several). - An empty repeater or flexible content field is an empty list,
[]. - A clone field is a nested object, like a group, keyed by the names of the cloned fields. The cloned fields appear only there, also when the clone does not prefix their names.
- A list field (a multiple select, checkboxes, a gallery) sent as an object with numbered keys, such as
{"1": "a", "0": "c"}, is saved as a list in the order the values arrive.
A document never holds a WordPress object. A user, post or term always appears as its id, so reading a record cannot expose another user’s account details or the body of a post you cannot see.
Keys come out in the order set in the field group configuration, matching the wp-admin edit screen. Order carries no meaning on write.
When a record changes, only the fields whose value differs are written. Editing a title leaves every custom field untouched.
Hidden flexible content layouts
Section titled “Hidden flexible content layouts”ACF 6.5 and later can disable a flexible content layout in wp-admin, which hides that section on the site without deleting it, and give a section its own label. The document carries both: a hidden section comes with "acf_fc_layout_disabled": true and a renamed one with "acf_fc_layout_custom_label". Hidden sections appear in the document like the others, so editing a page never loses them.
Keep the flags as they are. A section sent without acf_fc_layout_disabled is shown on the site again, and adding the flag hides one.
Field names
Section titled “Field names”Field names must match the definition exactly. An unknown key raises octa_unknown_field and is dropped, so the safest approach is to start from an exported record and change only the values.
Relations
Section titled “Relations”A relation field (post object or relationship) is written as a list of "{post_type}/{slug}" strings, which stay portable across installs.
"fields": { "related_offers": ["offer/service-5", "offer/service-7"] }The full field rules, including nested keys and warnings, live in Preparing JSON files.