Field types

Fields are the data an entry or a block holds: a heading, an image, a link, a price. You define them once on a content type or a component, and every entry or block of that kind gets them.

Where fields are set up

Fields live under Schema in the sidebar. You need a role with permission to change the schema. Anyone who can see the schema can read the fields.

• Schema › Content types. Choose Fields on a content type. These are the entry's own fields, such as a title, an excerpt or a date. They show in the page editor's Fields tab when no block is selected.
• Schema › Components. Choose Fields on a component. These are the values an editor fills in wherever the block is placed. They show in the Fields tab when the block is selected. A component's page also lists Where it is used, so you can see which pages a change will reach.

A block that your website shows as the page's main heading (H1), such as a page header or a legal document's title, should say so. Edit the component and choose the field under Main heading of the page, or send "mainHeading": "title" when creating or updating it through the API. SEO checks then know the page has its H1. Without it, only components with "hero" in their key are taken to provide one.

A page's body is not a field. It is the list of blocks editors build from components, set on the content type's Layout step. See How the CMS is organised.

Add a field

1. Go to Schema › Content types or Schema › Components and choose Fields on the one you want.
2. Choose New field.
3. On the About step, fill in:
   • Name: what editors see, such as Hero image.
   • Key: filled in from the name. Change it now if you want a different one, because it is fixed once saved.
   • Type: the kind of value. The list shows each type by its key, such as richtext.
   • Description: optional help text, shown to editors under the field.
4. Choose Next. On the Rules step, set what the type asks for (choices, allowed components, length limits and so on), then Required, Differs by region and Protects if you need them.
5. Choose Add field.

The field appears at the bottom of the list. Use the arrows to move it: the order here is the order editors see. Use the pencil to edit a field and the bin to delete it.

Settings every field has

Choosing a key

Keys are filled in from the name with hyphens, so Hero image becomes hero-image. Consider typing heroImage or hero_image instead:

• The delivery API's list filter, filter[<field>], only accepts keys made of letters, digits and underscores. A key with a hyphen cannot be filtered on. See Delivery API.
• Keys with hyphens need quotes in code, such as block["hero-image"].

Required fields

A required field is marked for editors and is never optional in generated types. A draft may be saved with a required field empty, since drafts are work in progress. Publishing is refused while any required field is empty, in the page's own fields or in any block: no value, empty text, blank rich text or an empty list. The publish dialog and the page checks list each one.

Fields that show only when

On the Rules step, Show only when picks another field of the same content type or component, then the value it must hold:

• Select and Multi-select: tick one or more choices. The field shows when the other field holds any of them.
• Toggle: is on or is off.
• Text and Long text: type the exact text it must hold.

Always show it removes the condition. Only those five types can decide, and a field cannot depend on itself or on a field that depends on it.

While the condition does not hold:

• Editors do not see the field. The page editor shows and hides it straight away as the other field changes, for blocks and for an entry's own fields.
• It keeps its value. Nothing is erased, so switching back brings the value back.
• It is not required and not checked. A required field is only required while it shows, and saving and publishing ignore its value.
• It is not delivered. The field is left out of the delivered fields, in published and draft answers, GraphQL and the live preview, so your website never sees an old value. See Delivery API.

A field whose own condition depends on a hidden field is hidden too. Through the Management API the condition is showWhen:

{ "key": "plan", "name": "Plan", "type": "select", "showWhen": { "field": "kind", "equals": "signUp" } }

equals is true or false for a Toggle, one value, or a list of values meaning any of them, such as ["signUp", "signIn"]. Values for a Select or Multi-select must be among its choices. Saving the schema refuses a condition on a field that is not there, on a type that cannot decide, or one that makes a loop. Deleting a field on the field screen also removes the conditions that depend on it. GET/schema gives each field's showWhen, or null.

Prices and promotions

Mark a field that holds a price, such as a price from or a was price, as protecting A price. Mark one that holds a promo code, a discount or a limited offer as protecting A promotion. Then:

• Changing a price needs the pricing:manage permission, and changing a promotion needs promotions:manage. See Roles and permissions.
• An AI agent is refused any change to a protected field, whatever the person it acts for may do.
• The check also covers protected fields inside blocks, and nested blocks.

While you add a field, Protects is suggested from its key: a key with price in it suggests a price, and one with promo, discount, voucher, coupon, odds or quota suggests a promotion. Change it if the suggestion is wrong. A field that was never set works the same way, so a field called price is protected until you say otherwise, and a field called cost is not until you mark it. The built-in Price fields and the promo code block's Code are marked already.

Validation rules

Rules are set on the Rules step. Which ones appear depends on the type:

Rules are checked every time a page is saved, in the editor or through the API, on the page's own fields and on every block: the type, choices, length, pattern, lowest and highest numbers, and allowed files. A field a block does not have is refused too. All problems come back at once with Some fields are invalid, each with its place, such as components[cmp_1].fields.size, and a note such as "huge" is not one of: small, medium, large.

Only new or changed values are checked. A value that was saved before a rule changed, or a field that was later removed, is left alone, so old pages stay editable. Publishing, though, is refused while a stored value breaks the current rules, so it gets fixed before it goes live.

Settings only available through the Management API

A few settings have no control on the field screen yet. Set them through the Management API:

Protects is protects in the API, one of none, price or promotion. Left out, it follows the key as described in Prices and promotions.

The types Time, Pages and sections, Taxonomy term, Taxonomy terms and Approved claims are not in the Type list either. They come with the built-in campaign and shop types, and you can add them through the API.

To change fields through the API, read the content type or component first, then send PATCH with the whole fields list to /cms/manage/v1/organisations/{organisationId}/spaces/{spaceId}/content-types/{key} or .../components/{key}. The list replaces the current one, so a field you leave out is removed. One field looks like this:

1{2  "key": "topics",3  "name": "Topics",4  "type": "taxonomyTerms",5  "taxonomyKey": "topic",6  "required": false,7  "description": "Shown as tags on the page",8  "protects": "none"9}

Editing that field later on the field screen keeps these settings.

Field types at a glance

A field can also be missing from an answer altogether, for example on an entry saved before the field was added. Treat a missing key like the empty value.

Text

Text

One line of plain text, such as a heading or a button label. Editors see a single-line box.

• Rules: Shortest, Longest, Pattern and its message.
• Arrives as: a string, such as "heading": "Find a shop".
• Generated type: string.

Long text

A few lines of plain text without formatting, such as a summary. Editors see a larger box. Line breaks are kept as typed.

• Rules: Shortest, Longest, Pattern and its message.
• Arrives as: a string, with line breaks as \n.
• Generated type: string.

Rich text

Formatted text. Editors see a small word processor. See Rich text in detail.

• Rules: none.
• Arrives as: a string of HTML, such as "<h2>Before you come</h2><p>Allow <strong>30 minutes</strong>.</p>".
• Generated type: CmsRichText, which is a string.

Where machine translation is set up, Text, Long text and Rich text fields offer a translation suggestion in the page's language.

Numbers and choices

Number

A number, such as a duration in minutes or a sort priority. Decimals are allowed.

• Rules: Lowest, Highest.
• Arrives as: a number, such as "duration": 60.
• Generated type: number.

Toggle

On or off. Editors see a switch.

• Arrives as: true or false.
• Generated type: boolean.

Select

One choice from a fixed list. Editors see a drop-down list of choice labels.

• Rules: Choices. Type a label and choose Add. The value is made from the label in lower case with hyphens, so Light background is stored as light-background. Labels and values can each be up to 120 characters. Add at least one choice.
• Arrives as: the value, not the label, such as "style": "light-background", or null.
• Generated type: a union of the values, such as "light-background" | "dark-background".

Multi-select

Any number of choices from a fixed list. Editors see the labels as buttons they switch on and off.

• Rules: Choices, as for Select.
• Arrives as: an array of values, such as "days": ["monday", "friday"].
• Generated type: an array of the union, such as ("monday" | "friday")[].

Colour

A colour. Editors see a colour picker.

• Rules: Palette. Give each colour a name, such as Sale red, and pick it. With no palette, the picker offers its default colours. With a palette, those colours are offered first, and editors can still choose any other colour.
• Arrives as: a hex code: #RGB, #RRGGBB or #RRGGBBAA, such as "#4B2A85", or null.
• Generated type: string.

Dates and times

Date

A day without a time. Editors see a date picker.

• Arrives as: YYYY-MM-DD, such as "2026-11-01", or null.
• Generated type: string.

Time

A time of day without a date, in 24-hour form. Editors see a time picker.

• Arrives as: HH:MM, such as "09:00", or null. On an entry's own fields, other values are refused with Use a 24-hour time such as 09:00.
• Generated type: string.

Date and time

A moment in time. Editors pick a date and a time.

• Arrives as: an ISO 8601 timestamp in UTC, such as "2026-11-01T09:00:00.000Z", or null. Convert it to the visitor's or the region's time zone for display.
• Generated type: string.

Media

Asset

One file from the media library, usually an image. Editors pick or upload it. See Media.

• Rules: Allowed files: tick Images (JPEG, PNG, WebP, AVIF, GIF and SVG), PDF or Video (MP4 and WebM). Nothing ticked allows any file. Other files are refused when the entry is saved.
• Arrives as: an image object, or null. See Images and files in detail.
• Generated type: CmsImage | null.

Assets

Several files from the media library, such as a gallery. Editors pick them in order.

• Rules: Allowed files, as for Asset.
• Arrives as: an array of image objects, in the editor's order.
• Generated type: CmsImage[].

Links and relations

Link

A link to a page on the site or to any address. Editors choose A page and search the pages by name or address, or choose An address and type one, such as https://example.com, /products/hiking-boots or an email address. A link to a page follows the page when it moves. Link text and new tab sets the optional label and target. See Links in detail.

• Allowed content types: limits A page to entries of those types, such as only blog posts for a "Featured post" field. Editors see only those entries in the list, and the API refuses a link to anything else. Empty allows any page. Addresses typed in by hand are not limited.
• Arrives as: a link object, or null.
• Generated type: CmsLink | null.

Pages and sections

Pages or whole sections of the site, such as where a banner shows. Editors pick pages or type addresses.

• Arrives as: an array of addresses, such as ["/products/hiking-boots", "/offers/*"]. Addresses are stored in lower case, without the domain, query or # part. An address ending in /* means that section and every page in it; /* alone means the whole site. Up to 100 addresses.
• Generated type: string[].

Reference

Another entry, such as an author or a follow-up banner. Editors pick it from a list.

• Rules: Allowed content types. The picker only offers entries of those types. Leave it empty to allow any.
• Arrives as: the entry's id, a 24-character string, or null.
• Generated type: string | null.

References

Several other entries, such as related articles.

• Rules: Allowed content types, as for Reference.
• Arrives as: an array of entry ids.
• Generated type: string[].

Ask the delivery API with include=references and both arrive as the entries they point at, with their fields, instead of ids. See References in the Delivery API. Generate types with npx cms-orbit generate --include references to match. For a link to a page, a Link field is usually the better choice, since it always carries the page's current address.

Taxonomies

See Taxonomies.

Taxonomy term

One term from a taxonomy, such as a brand. Editors search the terms by label.

• Settings: taxonomyKey, the taxonomy to draw from. Set it through the API.
• Arrives as: the term's value, such as "hiking", or null. Read the labels from GET/taxonomies/{key}.
• Generated type: string | null.

Taxonomy terms

Several terms from a taxonomy, such as activities.

• Arrives as: an array of term values, such as ["hiking", "climbing"].
• Generated type: string[].

Entries store the term's value. If you later change a term's value, entries keep the old one until an editor picks the term again.

Approved claims

Approved claims and disclaimers from the region's library. Editors pick them by name. Up to 20 per field. See Use approved claims and disclaimers.

• Arrives as: an array of claim objects with the current wording in the entry's region:

"claims": [  { "key": "results-vary", "kind": "disclaimer", "text": "Results vary from person to person." }]

• Claims the region does not have, or has archived, are left out, so the website never shows wording that is not approved there.
• Generated type: the type generator writes unknown for this field today. Use { key: string; kind: "claim" | "disclaimer"; text: string }[] in your code.

Components and slots

Component and Components

A Component field is a slot for one block, such as a button inside a hero. A Components field is a slot for a list of blocks, such as the cards in a card grid. Use them on components. A content type's own fields do not offer a slot editor, because the page body already holds the blocks.

• Rules: Allowed components. On a component, list at least one: a slot with none listed cannot be saved. Deprecated components are not offered in the slot.
• What editors see: the slot appears under the block in the page's block tree, with an Add menu of the allowed components. A Component slot holds one block, so its Add menu goes away once the slot is filled.

The slot's Allowed components decide what may go in it. The component's What may go inside it setting only applies to blocks placed outside its slots.

Where nested blocks are stored

The CMS stores nested blocks in one place: the parent block's children, under the slot field's key. Pages saved in the editor, through the Management API, MCP or an import all end up the same way. If you send a nested block in the field instead, as fields.cards, the CMS moves it into children.cards when it saves, gives it an id if it has none, and checks it against the slot's allowed components. If you send blocks in both places for the same slot, the ones in children are kept and the field is ignored.

How slots arrive

Every block arrives with the same shape: id, type, schemaVersion, fields, children and variant. A slot arrives twice: in the parent's children, under the slot field's key, and as the field itself, so either way of reading it works. A Component field holds the block or null; a Components field holds the list, or [] when it is empty:

1{2  "id": "c1",3  "type": "card-grid",4  "schemaVersion": 3,5  "fields": {6    "heading": "Our services",7    "cards": [8      {9        "id": "c2",10        "type": "card",11        "schemaVersion": 2,12        "fields": {13          "title": "Hiking boots",14          "link": { "kind": "url", "href": "/products/hiking-boots", "contentId": null, "assetId": null, "label": null, "target": null }15        },16        "children": {},17        "variant": null18      }19    ]20  },21  "children": {22    "cards": [23      { "id": "c2", "type": "card", "schemaVersion": 2, "fields": { "title": "Hiking boots", "link": { "...": "the same block as above" } }, "children": {}, "variant": null }24    ]25  },26  "variant": null27}

With the SDK, a component can read the field, such as block.cards, which is what the generated types describe, or let CmsBlocks render the children for it and use slots.cards. Live preview and drafts arrive the same way. Fields inside nested blocks are expanded the same way as everywhere else: images become image objects and links carry current addresses.

schemaVersion is the component's version when the page was last saved. Deprecated components are left out of GET/schema and generated types, but pages that still use them keep delivering them. Leave them out of your registry only once no page uses them.

Rich text in detail

The editor offers Bold, Italic, Heading 2, Heading 3, Bulleted list, Numbered list, Quote, Table and Link. Addresses typed into text become links automatically.

Every rich text value is cleaned when it is saved, in the editor or through the API. What is kept:

Everything else is removed: scripts, styles, style attributes, column sizes, images and embedded frames. Links may use http, https, mailto and tel, or an address on the site such as /products/hiking-boots. Any other kind of link is removed. A link that opens in a new tab gets rel="noopener noreferrer nofollow". A value that is only an empty paragraph is saved as "".

Links inside rich text are stored as typed. They do not follow a page that moves, so moved pages rely on redirects. For a link that must follow the page, use a Link field.

To render rich text, insert the HTML as it is. With the SDK, use <RichText value={block.description} />. Style the elements above in your own CSS.

Links in detail

A link field arrives as an object:

1"cta": {2  "kind": "content",3  "href": "/products/hiking-boots",4  "contentId": "6650c1f2a9e4b1c0d2e3f4a5",5  "assetId": null,6  "label": null,7  "target": null8}

How href is filled in:

• url and email: the address as saved. An address typed in the editor is saved as email when it is an email address, with or without mailto:, and as url otherwise.
• content: the linked page's current address, looked up on every request. When the page moves, the link follows. In published answers, href is null while the linked page is unpublished or in the bin. In draft answers it is the page's current address even before it is published. A page promoted to another environment keeps its links, and each one opens that environment's copy of the linked page, in the region and language with the same key and code.
• asset: the file's current address, or null once the file is in the bin.

The editor offers the pages that have an address in the same region and language. Saving refuses a content link whose contentId is not a page in this space, or is in the bin, and a content or asset link without its id. Links of kind asset can be saved through the Management API; the editor shows them as a file and keeps them until an editor picks a page or types an address instead. The editor keeps label and target when the destination changes.

Images and files in detail

Asset and Assets fields, and files inside links, arrive as image objects:

1"heroImage": {2  "id": "6650c1f2a9e4b1c0d2e3f4a6",3  "url": "https://assets.example.com/media/hero.jpg",4  "mimeType": "image/jpeg",5  "width": 1600,6  "height": 900,7  "alt": "A bright shop floor",8  "title": null,9  "subtitles": null10}

A file that has been moved to the bin arrives as null in an Asset field and is left out of an Assets list. With the SDK, render images with <CmsImage image={block.heroImage} sizes="100vw" />, which uses the width, height and alt text. See SDK.

Regional and shared fields

Regions each have their own copy of a page. A copy is linked to its source, and Update from source brings later changes in. See Copy a page to another region or language.

• Shared fields are the default. Updating a copy from its source replaces their values with the source's.
• Regional fields have Differs by region switched on. Updating from the source keeps the copy's own value. Use it for prices, shops, phone numbers and legal text.

Regional fields work inside blocks too. A block in the copy keeps its regional values when it lines up with a block of the same component in the source: the first hero with the first hero, the second card with the second card, and so on. If editors reorder or remove blocks in one region, check the regional values after the update.

Some types behave regionally on their own:

• Approved claims store keys, so each region shows its own approved wording without the field being regional.
• Asset and Assets are copied only when the editor chooses to copy images. Otherwise they start empty in the copy.
• Link, Reference and References keep pointing at the same entries. When several pages are copied together, links between them point at the new copies instead.

Languages work differently. Each language version of a page is its own entry, so every field holds text in that entry's language. There is no per-field language setting. Alt text and titles on files are kept per language in the media library.

Generated TypeScript types

The SDK writes one type per component and content type from GET/schema:

npx cms-orbit generate --out src/cms/types.ts

A component card-grid becomes CardGridBlock and a content type page becomes PageFields. Each field becomes a property named by its key. A required field is not optional; other fields end in ?. A field with Show only when always ends in ?, since it is left out while its condition does not hold. The description becomes a comment, followed by the condition, such as Only delivered when Goes to is Start free trial.

1export interface HeroBlock {2  type: "hero"3  /** The main line, kept short */4  heading: string5  description?: CmsRichText6  image?: CmsImage | null7  style?: "light-background" | "dark-background"8  cta?: CmsLink | null9  "hero-badges"?: string[]10}

Slot fields are typed from their allowed components, such as CmsNode<CardBlock>[]. With no allowed components, they accept any Block. Hidden fields and deprecated components are left out. Run the generator in CI so a schema change that would break the website fails the build. See SDK.

Change or remove a field safely

Every change to a content type's or a component's fields moves its schema version. Entries keep every value they already hold. Nothing is converted or erased, so most changes are safe for content. What can break is your website, if it meets a value it does not expect.

When you delete a field, the CMS asks first: entries keep whatever they hold for it. Adding a field with the same key again brings those values back. Because the values are kept, they can still appear in delivery answers: under the old key on an entry's own fields, and inside blocks under __orphaned in the block's fields once the page has been saved again. Your website should ignore keys it does not know.

After any change, run npx cms-orbit generate again and fix what the compiler finds before you deploy.

All field types

The list below comes from the CMS itself, so it always matches what your space can use.