> 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/array.md). # Array A list of values of one type — texts, numbers, dates, references, nested forms or other arrays — with row count and uniqueness rules. An **Array** stores a list of values of one type: a list of phone numbers, of order lines (nested forms), of coordinates (arrays of numbers). `items` is any of the 17 field types; the rules of `items` apply to every entry. **Builder:** Form fields panel → **Array** · widget `array` · data type `array.schema.v1` ## Data schema ```json { "lines": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": false, "items": { "type": "object", "properties": { "sku": { "type": "string", "minLength": 2 }, "qty": { "type": "integer", "minimum": 1 } }, "required": ["sku", "qty"] } } } ``` | Keyword | Required | What it does | Example | | ----------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | `type` | yes | Always `"array"`. | `"array"` | | `items` | **yes** | The type of every entry: any field definition — a primitive, a reference, an object (= a list of nested forms) or another array. | `{ "type": "string" }` | | `minItems` / `maxItems` | no | The fewest / most entries. | `1` / `50` | | `uniqueItems` | no | `true` = no two entries may be equal (objects are compared by value). | `true` | * Two string-array shapes are **not** this type: `items: { type: string }` with `uniqueItems: true` is [Tags](/codemash/cloud/database/schema/field-types/tags.md); `items: { type: string, format: uuid }` is [File](/codemash/cloud/database/schema/field-types/file.md). * An array counts as one nesting level; an array of nested forms with a nested form inside is three. The limit is five — see [Nested forms and arrays](/codemash/cloud/database/schema/nesting.md). ### 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` | | the value is not an array | `CM-ERRORS-DATABASE-039` | `must be an array` | | fewer than `minItems` / more than `maxItems` | `CM-ERRORS-DATABASE-040` | `must have at least 1 items` / `must have at most 50 items` | | an entry breaks the `items` rule | the entry's code, at its position | `Field 'lines[0].qty' is invalid: must be at least 1`, `Field 'scores[1]' is invalid: must be an integer` | | two equal entries with `uniqueItems` | `CM-ERRORS-DATABASE-046` | `entries must be unique — repeated at positions 0, 1` | | a dotted update with a segment that is not a position | `CM-ERRORS-DATABASE-039` | `'qty' is not an array position — use an index (lines.0), $[] for every element or $[name] with arrayFilters` | | a sort on or through the array | `CM-ERRORS-DATABASE-039` | `is an array — a list cannot be sorted or paged on; sort on another field` | 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.lines.sort' (field 'properties.lines' checked as array.schema.v1).` Also refused at save time: * an array without `items` — `CM-ERRORS-SCHEMA-010`; in the builder, **Save** on an Array with no item type shows the reason on its **Item** tab. ## UI schema The cell uses the `array` widget: rows with add, remove and move buttons. When `items` is an object, the row's fields are laid out in `children`. ```json { "colSpan": 12, "element": { "fieldId": "lines", "meta": { "widget": "array", "label": "Order lines", "array": { "allowAdd": true, "allowRemove": true, "allowReorder": true, "showMinMax": true } }, "children": [ { "colSpan": 6, "element": { "fieldId": "sku", "meta": { "widget": "text", "label": "SKU", "required": true } } }, { "colSpan": 6, "element": { "fieldId": "qty", "meta": { "widget": "number", "label": "Qty", "required": true } } } ] } } ``` | Option | What it does | | ------------------------------------------------- | ---------------------------------------------------------------------------------------- | | `array.allowAdd` / `allowRemove` / `allowReorder` | Which row actions the form offers (all default `true`). | | `array.showMinMax` | Shows the data schema's `minItems` / `maxItems` next to the row count (`2 of 1–3 rows`). | 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).
New schema sc_nesting_cloud_orders in the Visual Builder: the fields Name (Required), Address (3 fields), Phones (of Text (1–3)) and Order lines (of Nested Form (3 fields)), each 12/12; Cancel, Create draft and Save & publish

The builder shows an array by its item type and bounds: Phones is an array of Text (1–3), Order lines an array of Nested Form.

## Records A record the schema accepts: ```json { "lines": [{ "sku": "A-100", "qty": 2 }, { "sku": "B-200", "qty": 1 }] } ``` A record it refuses: ```json { "lines": [{ "sku": "A-100", "qty": 0 }] } ``` The answer: `CM-ERRORS-DATABASE-043` — `Field 'lines[0].qty' is invalid: must be at least 1`. 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 * Update one entry with a position (`{ "lines.0.qty": 3 }`), every entry (`{ "lines.$[].qty": 1 }`) or the entries a filter matches (`{ "lines.$[line].qty": 3 }` with `arrayFilters: [{ "line.sku": "A-100" }]`) — see [Nested forms and arrays](/codemash/cloud/database/schema/nesting.md). * Filter through an array with a dotted path: `{ "lines.sku": "A-100" }`. Sorting on a list is refused — sort on a top-level field. * The records list shows an array as a short summary of its entries, not as raw JSON. ## Do it from code ```ts await norbix.api.database.insertOne({ collectionName: 'orders', document: JSON.stringify({ lines: [{ sku: 'A-100', qty: 2 }] }), }); ``` ```sh norbix api database one insert --collectionName orders --document '{"lines":[{"sku":"A-100","qty":2}]}' ``` 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 [Nested forms and arrays](/codemash/cloud/database/schema/nesting.md) · [Nested form](/codemash/cloud/database/schema/field-types/nested-form.md) · [Tags](/codemash/cloud/database/schema/field-types/tags.md) · [File](/codemash/cloud/database/schema/field-types/file.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)