# Reference: Client fields JSON (`custom_fields_json`)

This page lists **properties of a single field object** in **Client Fields** (`/settings-page/client-fields`). The saved configuration includes a wrapper with the key `custom_fields_json`; inside it, each **key** is the field’s technical name (Latin), and the **value** is the field definition.

Step-by-step: [How to configure client fields](/en/settings/how-to/configure-client-fields.md). Visibility can be changed there (one header Save) or on the [op-settings page](/en/settings/how-to/configure-client-card-fields.md) — same block, different save affordance.

---

## Saved data shape

After saving to instance settings, the payload uses `client_fields_json`, which contains `custom_fields_json`:

```json
{
  "custom_fields_json": {
    "department": {
      "type": "STRING",
      "label": "Department"
    }
  }
}
```

Values that operators enter in the client card are stored in the client’s `extra_data` under these field keys.

---

## Core field properties

| Property | Required | Description |
|----------|----------|-------------|
| `type` | Effectively required | Data type. See the table below. |
| `label` | Recommended | Label shown in the UI (client card, tables). |

### Allowed `type` values

| Value | Purpose |
|-------|---------|
| `STRING` | Short text |
| `TEXT` | Multiline text |
| `SELECT` | Fixed list selection |
| `SELECTAPI` | Selection from an API-backed source |
| `FILE` | File |
| `INTEGER` | Integer |
| `BIGINT` | Large integer |
| `FLOAT` | Decimal number |
| `DATE` | Date |
| `BOOLEAN` | Yes / no |

---

## Additional properties (form and JSON)

On the **Client Fields** page, many options can be set in the field card (form sections); everything can also be edited in **raw JSON**. In the saved JSON, most toggles are stored as the string `"true"`; when off, the key is usually **omitted**.

### General and editing

| Key | JSON type | What it does |
|-----|-----------|--------------|
| `default` | string | Default value on create / fallback (depending on UI behavior). |
| `unique` | `"true"` | Disallow duplicate values for this field (enforcement depends on usage). |
| `non_editable` | `"true"` | Read-only for operators in the UI. |

### Table display

| Key | JSON type | What it does |
|-----|-----------|--------------|
| `sortable` | `"true"` | Enable sorting by this column in the clients table. |
| `width` | string | Column width in pixels, e.g. `"120"`. |
| `align` | `""` / `"start"` / `"center"` / `"end"` | Header alignment. Empty means default. |
| `display_in_table` | `""` / `"image"` | Cell rendering mode; `image` shows an image where data allows. |
| `display_type` | `"link"` | For string-like fields: value is treated as a link opening in a new tab. |
| `click_action` | `"open"` | For string-like fields: click opens an edit modal. **Do not combine** with `display_type: "link"` — the form’s “action on click” control is mutually exclusive. |

### Visibility

| Key | JSON type | What it does |
|-----|-----------|--------------|
| `hidden_all` | `"true"` | Hide the field everywhere in the card and related forms (same as the UI toggle). |
| `hidden_in_table` | `"true"` | Hide the column from the table column picker. |
| `hide_in_filter` | `"true"` | Hide the field from filters. |
| `hidden_in_create_popup` | `"true"` or `true` | Hide in quick-create popup when that flow is used. |
| `portal_registration` | `"true"` or `true` | Show on **Client Portal** self-registration form (`/register`). Values stored in `OpClients.extra_data`. In Constructor UI: toggle **Show on Client Portal registration** on `/settings-page/client-fields`. Does not control operator client card visibility. |

### Client Portal (registration)

Works together with instance settings `portal_registration_enabled` and `portal_registration_role_id`. Types `SELECTAPI` and `FILE` are **excluded** from the registration form even when the flag is set. See [Configure instance settings](/en/settings/how-to/configure-instance.md) and [Configure roles](/en/settings/how-to/configure-roles.md).

### Validation: `rules`

An array of rule name strings. Values available from the picker:

| Value | Purpose |
|-------|---------|
| `required` | Required value |
| `email` | Email format |
| `digits` | Digits only |
| `latin` | Latin characters only |
| `latinDigits` | Latin letters and digits |
| `stringMaxLength` | Max length (may need extra parameters in JSON for advanced cases) |
| `json` | JSON format check |

Complex cross-field rules may use a separate `validate` object. Use the **JSON examples** on the settings page or keep a backup before editing.

Example:

```json
"email_field": {
  "type": "STRING",
  "label": "Email",
  "rules": ["required", "email"]
}
```

---

## JSON examples block

The **JSON examples** section at the bottom of the editor lists five snippets with the same JSON as in [How to configure client fields](/en/settings/how-to/configure-client-fields.md) (**JSON examples**). The documentation adds a short narrative for each scenario; the product UI only shows short selector labels.

---

## Limits and tips

- Invalid JSON will not save: check commas, quotes, and brackets.
- Back up the configuration before large edits.
- Removing a field here does not automatically remove its key from the card visibility settings; update the [field editor in the client card](/en/settings/how-to/configure-client-card-fields.md) if needed.