> 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/collection-reference.md). # Collection reference A reference to one or several records of another collection: the record stores the record id, shown by a field of the target schema. A **Collection** reference links a record to records of another collection (or of the same one) — an order to its customer, a post to its author. The record stores the **record id**; the schema names the target collection and which of its fields to show. **Builder:** Form fields panel → **Select → Collection** · widget `select` · data type `collection.selection.schema.v1` ## Data schema ```json { "customer": { "source": "collection", "collectionId": "people", "displayField": "firstName", "multiple": false } } ``` | Keyword | Required | What it does | Example | | -------------- | -------- | -------------------------------------------------------------------------------------------------------- | -------------- | | `source` | yes | Always `"collection"`. | `"collection"` | | `collectionId` | **yes** | The target: the collection's unique name or its `sch_` id — stored as the name. Never its display title. | `"people"` | | `displayField` | **yes** | A field name of the target schema (a text-like field), shown instead of the id. | `"firstName"` | | `multiple` | no | `true` = the record stores an array of record 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 record of the target collection in this environment (a deleted record counts as missing) | `CM-ERRORS-DATABASE-053` | `'…' is not a record of collection 'people' in this environment` | | the target collection cannot be read in this environment | `CM-ERRORS-DATABASE-055` | `its target 'people' 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 an array of references, not a single string — the field is 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.customer.sort' (field 'properties.customer' checked as collection.selection.schema.v1).` Also refused at save time: * a `collectionId` the project does not have — `CM-ERRORS-SCHEMA-028` `1 collection-selection field(s) point at a collection this project does not have: … A collectionId must be an existing schema id (sch_…) or that collection's name — never its display title.` * a `displayField` the target schema has no field for — `CM-ERRORS-SCHEMA-039` `Field 'customer' shows 'nickname' of collection 'people', but that collection has no such field …`. * later, on the **target**: dropping or renaming the shown field is refused — `CM-ERRORS-SCHEMA-040` `Collection 'people' cannot drop or rename a field that 1 reference field(s) of other schemas show: …`; deleting the target schema is refused while references point at it — `CM-ERRORS-SCHEMA-041`. ## UI schema The cell uses the `select` widget; the picker searches the target collection by the display field. In the builder, picking a target collection loads its schema and offers its text-like fields as **Display field**. ```json { "colSpan": 6, "element": { "fieldId": "customer", "meta": { "widget": "select", "label": "Customer", "required": true } } } ``` 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).
Selection - Collection dialog of the schema builder: Required and Multiple checkboxes, Label Person, Unique field name person, the source tabs Enumeration, Users, Roles, Collection (selected) and Taxonomy, Collection sc_refs-cloud_people, Display field firstName (text) with the note The record stores the record id; the form and the list show this field of the referenced record instead; Cancel and Save

The builder's Selection dialog for a collection reference: target collection and display field.

## Records A record the schema accepts: ```json { "customer": "6650a1b2c3d4e5f6a1b2c401" } ``` A record it refuses: ```json { "customer": "6650a1b2c3d4e5f6a1b2c499" } ``` The answer: `CM-ERRORS-DATABASE-053` — `Field 'customer' is invalid: '6650a1b2c3d4e5f6a1b2c499' is not a record of collection 'people' 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 * A reference can point at its own collection (a parent record, a "related" list). * Reading with `expandReferences: true` needs read permission on the target collection too — otherwise `CM-ERRORS-DATABASE-056`; see [References](/codemash/cloud/database/schema/references.md). * A reference inside a [nested form](/codemash/cloud/database/schema/field-types/nested-form.md) or an [array](/codemash/cloud/database/schema/field-types/array.md) is checked and expanded the same way, at any depth. ## Do it from code ```ts await norbix.api.database.insertOne({ collectionName: 'orders', document: JSON.stringify({ customer: '6650a1b2c3d4e5f6a1b2c401' }), }); ``` ```sh norbix api database one insert --collectionName orders --document '{"customer":"6650a1b2c3d4e5f6a1b2c401"}' ``` 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) · [Term reference](/codemash/cloud/database/schema/field-types/term-reference.md) · [User reference](/codemash/cloud/database/schema/field-types/user-reference.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)