> For the complete documentation index, see [llms.txt](https://codemash.gitbook.io/codemash/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codemash.gitbook.io/codemash/cloud/database/schema/field-types/enum.md). # Enum A selection from a fixed list of values you type into the schema; single or multiple. An **Enum** field stores one value — or, with `multiple`, several — from a list fixed in the schema: a status, a size, a category that never changes. For lists that live in the database use a [term reference](/codemash/cloud/database/schema/field-types/term-reference.md) or a [collection reference](/codemash/cloud/database/schema/field-types/collection-reference.md). **Builder:** Form fields panel → **Select → Enumeration** · widget `select` · data type `enum.selection.schema.v1` ## Data schema ```json { "status": { "source": "enum", "values": ["draft", "active", "archived"], "multiple": false, "default": "draft" } } ``` | Keyword | Required | What it does | Example | | ---------- | -------- | ------------------------------------------------------------------- | --------------------- | | `source` | yes | Always `"enum"`. | `"enum"` | | `values` | yes | The allowed values: at least one string, no repeats. | `["draft", "active"]` | | `multiple` | no | `true` = the record stores an array of values. | `true` | | `default` | no | One value for a single enum; an array of values for a multiple one. | `"draft"` / `["new"]` | ### What the server refuses Every write — insert, update, replace; from Cloud, the API, an SDK, the CLI or an AI agent — is checked against the published schema. A broken value is answered with one error per field: the code, and `Field '' is invalid: `. Nothing is written. | Case | Code | The reason it gives | | ------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------- | | a required field is missing or `null` | `CM-ERRORS-DATABASE-030` | `a value is required` | | a value outside `values` | `CM-ERRORS-DATABASE-045` | `'deleted' is not one of: draft, active, archived` | | an array sent to a single enum | `CM-ERRORS-DATABASE-039` | `must be a single option (string), not an array — the field is not multiple` | | a string sent to a multiple enum | `CM-ERRORS-DATABASE-039` | `must be an array of selected options, not a single string — the field is multiple` | | a repeated entry in a multiple enum | `CM-ERRORS-DATABASE-046` | `entries must be unique — repeated: 'paid'` | A keyword that is not in the table above is refused when the schema is **saved**, not when a record is written: `CM-ERRORS-SCHEMA-010` — `Data schema violates meta-schema: Property 'sort' has not been defined and the schema does not allow additional properties. Path 'properties.status.sort' (field 'properties.status' checked as enum.selection.schema.v1).` Also refused at save time: * an empty `values` list or a repeated value — `CM-ERRORS-SCHEMA-010` / `CM-ERRORS-SCHEMA-024` `Schema field 'status' has an invalid value set: …`. * a `default` that is not in `values` — `CM-ERRORS-SCHEMA-037`. ## UI schema The cell uses the `select` widget. `select.sort` is the only option: the order the values are shown in. ```json { "colSpan": 3, "element": { "fieldId": "status", "meta": { "widget": "select", "label": "Status", "select": { "sort": "asc" } } } } ``` | Option | What it does | | ------------- | -------------------------------------------------------- | | `select.sort` | `none` (the schema order, the default), `asc` or `desc`. | Every cell also takes the common layout options: `label`, `placeholder`, `help` (the text under the input), `required`, `readonly` and `hidden`. Keys outside this list — `watermark`, `hint`, `permissions` — are refused when the schema is saved (`CM-ERRORS-SCHEMA-012`), see [Schema authoring guide](/codemash/cloud/database/schema.md#one-contract-no-second-dialect).
Add New Record form of sc_e2e_all_types, References tab: taxonomy, collection and user pickers with a search icon and the placeholder e.g.: John Smith; the enum cells follow further down the tab

The References tab of the all-types form; enum cells share the select widget with the reference pickers.

## Records A record the schema accepts: ```json { "status": "active" } ``` A record it refuses: ```json { "status": "deleted" } ``` The answer: `CM-ERRORS-DATABASE-045` — `Field 'status' is invalid: 'deleted' is not one of: draft, active, archived`. In Cloud the same sentence is shown under the field before the form is sent; the server repeats the check on every API write. ## Good to know * Renaming a value in `values` does not change stored records; records with the old value no longer match the schema. Publish such a change with care. * A multiple enum stores `["new", "paid"]`; filter it with `{ "status": "paid" }` (MongoDB matches array members). ## Do it from code ```ts await norbix.api.database.insertOne({ collectionName: 'orders', document: JSON.stringify({ status: 'active' }), }); ``` ```sh norbix api database one insert --collectionName orders --document '{"status":"active"}' ``` The client setup is on the [Database page](/codemash/cloud/database.md#use-it-from-code). API: [Insert One](/codemash/api-reference/database/collections/insert-one.md) · [Save Database Schema](/codemash/api-reference/database/schemas/save-database-schema.md) ## Related [Term reference](/codemash/cloud/database/schema/field-types/term-reference.md) · [Collection reference](/codemash/cloud/database/schema/field-types/collection-reference.md) · [Tags](/codemash/cloud/database/schema/field-types/tags.md) · [Field type reference](/codemash/cloud/database/schema/field-types.md) · [Schema authoring guide](/codemash/cloud/database/schema.md) · [Create a schema](/codemash/cloud/database/collections/create-schema.md)