> 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/role-reference.md).

# Role reference

A reference to one or several project roles: the record stores the role id, shown by its name.

A **Role** reference points at a role of the project — a system role or a custom one. The record stores the **role id** (never the name); Cloud shows the role's name.

**Builder:** Form fields panel → **Select → Roles** · widget `select` · data type `role.selection.schema.v1`

## Data schema

```json
{
  "visibleTo": {
    "source": "role",
    "displayField": "name",
    "multiple": true
  }
}
```

| Keyword        | Required | What it does                                     | Example  |
| -------------- | -------- | ------------------------------------------------ | -------- |
| `source`       | yes      | Always `"role"`.                                 | `"role"` |
| `displayField` | no       | `name` — the default and the only option.        | `"name"` |
| `multiple`     | no       | `true` = the record stores an array of role 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 '<name>' is invalid: <reason>`. 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 role of the project — a role **name** counts as not found | `CM-ERRORS-DATABASE-051` | `'Editor' is not a role of this project`                                      |
| 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.visibleTo.sort' (field 'properties.visibleTo' checked as role.selection.schema.v1).`

## UI schema

The cell uses the `select` widget; the picker lists the project's roles by name.

```json
{
  "colSpan": 6,
  "element": {
    "fieldId": "visibleTo",
    "meta": { "widget": "select", "label": "Visible to" }
  }
}
```

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).

<figure><img src="https://712692422-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FHy372bqsaex2cqS3ikhL%2Fuploads%2Fgit-blob-46d8cbe8a9366a60ca53ed13fb664e8ce88af82c%2Freferences-form-1.png?alt=media" alt="Edit Record form of sc_refs-cloud_tasks with the Role cell showing Admin Portal Manager from a role picker and the Roles cell below it"><figcaption><p>A role picker on a record form shows the role's name; the record stores the role id.</p></figcaption></figure>

## Records

A record the schema accepts:

```json
{ "visibleTo": ["rol_7Hq2mVx9Lk3pN5sT8wZa1B"] }
```

A record it refuses:

```json
{ "visibleTo": ["Editor"] }
```

The answer: `CM-ERRORS-DATABASE-051` — `Field 'visibleTo' is invalid: 'Editor' is not a role of this project`. 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

* Get role ids from Membership → Roles or `norbix hub membership roles get`.
* A role reference records *which* role a record names; it does not give that role permissions — permissions come from [policies](/codemash/cloud/concepts/permissions.md).

## Do it from code

```ts
await norbix.api.database.insertOne({
  collectionName: 'documents',
  document: JSON.stringify({ visibleTo: ['rol_7Hq2mVx9Lk3pN5sT8wZa1B'] }),
});
```

```sh
norbix api database one insert --collectionName documents --document '{"visibleTo":["rol_7Hq2mVx9Lk3pN5sT8wZa1B"]}'
```

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) · [User reference](/codemash/cloud/database/schema/field-types/user-reference.md) · [Roles](/codemash/cloud/membership/roles.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)