> 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/term-reference.md). # Term reference A reference to one or several terms of a taxonomy: the record stores the term id, shown by the term's title or slug. A **Taxonomy** reference points at terms of one taxonomy — a category, a department, a country. The record stores the **term id**; the schema names the taxonomy and whether the term's `title` or `slug` is shown. **Builder:** Form fields panel → **Select → Taxonomy** · widget `select` · data type `taxonomy.selection.schema.v1` ## Data schema ```json { "department": { "source": "taxonomy", "taxonomyId": "departments", "displayField": "title", "multiple": false } } ``` | Keyword | Required | What it does | Example | | -------------- | -------- | ------------------------------------------------------------------------ | --------------- | | `source` | yes | Always `"taxonomy"`. | `"taxonomy"` | | `taxonomyId` | **yes** | The taxonomy: its slug, its title or its `txn_` id — stored as the slug. | `"departments"` | | `displayField` | no | `title` (default) or `slug`. | `"slug"` | | `multiple` | no | `true` = the record stores an array of term ids. | `true` | ### 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` | | an id that is not a term of that taxonomy in this environment (a term of another taxonomy, a deleted term) | `CM-ERRORS-DATABASE-052` | `'…' is not a term of taxonomy 'departments' in this environment` | | the taxonomy no longer exists | `CM-ERRORS-DATABASE-055` | `its target 'departments' cannot be read in this environment: …` | | a string sent to a multiple reference / an array to a single one | `CM-ERRORS-DATABASE-039` | `must be a single reference (string), not an array — the field is not multiple` | | the same id twice | `CM-ERRORS-DATABASE-046` | `entries must be unique — repeated: '…'` | 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.department.sort' (field 'properties.department' checked as taxonomy.selection.schema.v1).` Also refused at save time: * a `taxonomyId` the project does not have — `CM-ERRORS-SCHEMA-027` `1 taxonomy-selection field(s) point at a taxonomy this project does not have: … Create each taxonomy first …`. * no `taxonomyId` at all — `CM-ERRORS-SCHEMA-025` `Schema field 'department' is missing the required reference 'taxonomyId'.` ## UI schema The cell uses the `select` widget; the picker searches the taxonomy's terms (a tree when the taxonomy has parents). ```json { "colSpan": 4, "element": { "fieldId": "department", "meta": { "widget": "select", "label": "Department" } } } ``` 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).
Edit Record form of sc_refs-cloud_tasks with the Topic cell showing Urgent from a taxonomy picker and the Topics cell showing 2 items selected with the chips Urgent and Later

Taxonomy pickers on a record form: Topic (one term) and Topics (several terms as chips).

## Records A record the schema accepts: ```json { "department": "6650a1b2c3d4e5f6a1b2c301" } ``` A record it refuses: ```json { "department": "6650a1b2c3d4e5f6a1b2c999" } ``` The answer: `CM-ERRORS-DATABASE-052` — `Field 'department' is invalid: '6650a1b2c3d4e5f6a1b2c999' is not a term of taxonomy 'departments' in this environment`. 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 * Terms are per environment: a term created in TEST is not a valid id in PROD until the taxonomy is [promoted](/codemash/cloud/project/settings/environments.md#promote-content-up-the-ladder). * With `displayField: "title"` the expanded `display` is the term's title as stored (a language → text object when the taxonomy is translatable); with `slug` it is the slug string. * Every term has a `slug`, derived from its name and unique within the taxonomy. ## Do it from code ```ts await norbix.api.database.insertOne({ collectionName: 'people', document: JSON.stringify({ department: '6650a1b2c3d4e5f6a1b2c301' }), }); ``` ```sh norbix api database one insert --collectionName people --document '{"department":"6650a1b2c3d4e5f6a1b2c301"}' ``` 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 [References](/codemash/cloud/database/schema/references.md) · [Taxonomies](/codemash/cloud/database/taxonomies.md) · [Terms](/codemash/cloud/database/taxonomies/terms.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)