> For the complete documentation index, see [llms.txt](https://docs.scaleflex.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.scaleflex.com/portals/portal-settings/datasets/fields.md).

# Fields

Define the shape of a record — what columns a dataset has, and what each one holds.

The **Fields** tab describes what one record looks like. Everything else depends on it: the Items table draws a column per field, and a section binds its row template to field *keys*.

Define the fields first — the [Items](https://docs.scaleflex.com/portals/portal-settings/datasets/items.md) tab has nothing to show until you do, and says so.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FzD3ZB0kYmOjsyFCCLPoz%2Fimage.png?alt=media&#x26;token=607f803c-580b-4dad-8676-3c9c513f211b" alt=""><figcaption><p>The <strong>Fields</strong> tab of a dataset.</p></figcaption></figure>

## Adding a field

**Add field** asks for four things, and a fifth when the type needs it.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FmJH2ZtPMx4Wrb7oSRMXN%2Fimage.png?alt=media&#x26;token=2aa97f49-7c70-4803-b8ce-393b3fb9df07" alt="" width="375"><figcaption><p>Adding a field: label, key, type, and whether it is required or translatable.</p></figcaption></figure>

| Setting          | What it's for                                                                         |
| ---------------- | ------------------------------------------------------------------------------------- |
| **Label**        | What you see in the table header and the item form.                                   |
| **Key**          | The name sections bind to. Starts with a letter, then letters, digits or underscores. |
| **Type**         | What the field holds — see below.                                                     |
| **Required**     | An item can't be saved without a value.                                               |
| **Translatable** | The value is held per language. **Text** and **Rich text** only.                      |

{% hint style="warning" %}
The **Key** can't be changed once the field is saved. Every section that reads the field binds to that key, so renaming it would orphan them all. Choose it deliberately; the **Label** stays editable if the wording turns out wrong.
{% endhint %}

Drag fields to reorder them, then **Save** — or **Discard** to drop the changes.

## Field types

| Type                | Holds                                                                         |
| ------------------- | ----------------------------------------------------------------------------- |
| **Text**            | A single line. Can be translatable.                                           |
| **Rich text**       | Formatted copy, with its own small editor. Can be translatable.               |
| **Number**          | A number.                                                                     |
| **Date**            | A date.                                                                       |
| **Yes / no**        | A switch.                                                                     |
| **Media**           | An image, a video or a Spotlight experience, with alt text and a cover image. |
| **Link**            | A **URL**, an optional **Link label**, and **Open in a new tab**.             |
| **Single choice**   | One value from a list you define.                                             |
| **Multiple choice** | Any number of values from a list you define.                                  |
| **Portal page**     | One of this Portal's own pages, picked from a list.                           |
| **DAM assets**      | Which assets in your DAM this row stands for.                                 |

**Single choice** and **Multiple choice** take an **Options** list, each option with a **Label**, a **Value** and optionally a **Color**. The list's order is the order visitors see when a list is grouped by that field — see **Option order** below for how to set it.

**Portal page** is what lets each row link somewhere different: a row's own page, rather than one page the whole list points at. A row naming a page that no longer exists reads as *(page not found)* in the cell.

## DAM assets

Most fields hold a value you typed. **DAM assets** holds a question your DAM answers: *which assets does this row stand for?*

That is what lets one row — a destination, a product line, a campaign — open a gallery of its own photographs without anyone attaching them by hand.

| Setting            | What it does                                                                                                |
| ------------------ | ----------------------------------------------------------------------------------------------------------- |
| **Look in**        | Where to search: **All assets**, or narrow it to **Labels**, **Folders** or **Collections**.                |
| **Where metadata** | Optional rules, each a **Field** and a **Value**. **Add metadata rule** adds another, **Remove** drops one. |

The set is worked out when a visitor opens it, not when you save the row. Upload an asset that matches the rule and it joins that row's assets on its own — which is the point of describing them rather than listing them.

Unlike most fields, a **DAM assets** value is not carried into the next row you add. Each row usually points somewhere of its own, and inheriting the last one's rule would quietly give every new destination the same photographs.

## Option order

**Option order** sets how a choice field's options are arranged:

| Setting                 | The options are                                              |
| ----------------------- | ------------------------------------------------------------ |
| **Manual order**        | In the order you put them in. The default.                   |
| **Alphabetical (auto)** | Kept A–Z by label, in the language your interface is set to. |

### Manual order

Drag an option by its handle to move it. From the keyboard, focus the handle, press Space to pick it up, the arrow keys to move it, and Space again to drop it. Escape cancels the move without closing the dialog.

**Sort A–Z** puts the list in alphabetical order once, and leaves it yours to rearrange afterwards. When the options already read A–Z, the button becomes **Sort Z–A** and reverses them.

### Alphabetical (auto)

The list stays sorted for you, so a new option lands in its place rather than at the bottom — the setting for long lists such as destinations or products.

The drag handles and the sort button go away, and the heading reads **Options (sorted A–Z when you apply)**: options you add or rename move into place when you click **Apply**. Alphabetical fields applied from the JSON view are sorted the same way.

Sorting ignores capitals and accents — *Éclair* sits among the Es — and reads numbers as numbers, so *Item 2* comes before *Item 10*. It follows the alphabet of your interface language, so in Swedish *Åland* comes after *Z*.

{% hint style="info" %}
The order is fixed when you save, in your language. Visitors see that same order in every language they browse in.
{% endhint %}

## The type decides what a section can do with it

Worth knowing before you design the schema, because a field of the wrong type simply isn't offered later:

| To let a section…                                               | The field must be                                   |
| --------------------------------------------------------------- | --------------------------------------------------- |
| **Sort** the list by it                                         | **Text**, **Number**, **Date** or **Single choice** |
| **Group** the list under headings by it                         | **Date** or **Single choice**                       |
| Offer it as a **visitor filter**                                | **Single choice** or **Multiple choice**            |
| Use it as the **row anchor**, or label **content tree** entries | **Text**                                            |
| Send a row to **its own assets**                                | **DAM assets**                                      |

So a changelog meant to be filtered by product and grouped by month wants its product as a **Single choice** rather than free text, and its date as a **Date** rather than a string. All of these are explained where they're used, in [Connect to dataset](https://docs.scaleflex.com/portals/portal-settings/datasets/connect-to-dataset.md).

## Deleting a field

**Delete** on a field opens a confirmation that first tells you what depends on it: every place in the Portal that reads the field — as a **Bound component**, **Filter**, **Visitor filter**, **Sort**, **Grouping**, **Row anchor** or **Content tree** — and how many items hold a value for it.

Confirming clears the value from every item, in one go. It deliberately does **not** repoint the sections that referenced the field — that's the list you were shown, and yours to fix. Work through it before deleting, not after.

## Editor and JSON

The **Editor / JSON** switch above the tab swaps the field list for the same thing as a JSON document: *this dataset without its items — name, handle and fields*. Applying it saves those and leaves the items alone.

It's the quick way to add a dozen fields at once, or to copy a schema from one dataset into another.

<figure><img src="https://2536208400-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fqsq2dR7Fjagf5eTifWZx%2Fuploads%2FwiGrsmUVxw1GYtDuRc7v%2Fimage.png?alt=media&#x26;token=c3d6cec3-d9a7-429a-bab4-3362a29ee017" alt=""><figcaption><p>The same fields in <strong>JSON</strong> view, where a whole schema can be pasted in at once.</p></figcaption></figure>

| Control                           | Does                                                                |
| --------------------------------- | ------------------------------------------------------------------- |
| **Import JSON**                   | Loads a file into the editor. *File loaded. Review it, then apply.* |
| **Export JSON**                   | Downloads the document as `<handle>-fields.json`.                   |
| **Expand all** / **Collapse all** | Opens or folds the tree, for a long schema.                         |
| **Apply**                         | Saves it. **Discard** drops your edits.                             |

A document that isn't valid JSON is refused as **Invalid document** before anything is sent.

{% hint style="warning" %}
**You can't delete a field from JSON.** Removing one here is refused, naming the keys you took out, because deleting a field also has to clear its value from every item — which a schema save can't do. Delete it from the Editor view instead.

Some other changes are rejected too, with **This change is not allowed yet**, followed by the reason. Adding fields always works; reshaping existing ones may not.
{% endhint %}

The Items tab has its own, separate JSON view — neither document reaches into the other, so a rejected item list can't leave you with half-saved fields.
