> 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/json.md). # JSON A free-form JSON object with no declared members, optionally capped in size (maxBytes); shown as a code box. A **JSON** field stores any JSON object — settings, a payload from another system — without declaring its members. `maxBytes` caps the size. It is the one field the server does not look inside. **Builder:** Form fields panel → **JSON** · widget `json` · data type `json.schema.v1` ## Data schema ```json { "notes": { "type": "object", "additionalProperties": true, "maxBytes": 4096 } } ``` | Keyword | Required | What it does | Example | | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `type` | yes | Always `"object"`. | `"object"` | | `additionalProperties` | **yes** | Always `true` — this is what makes the field free-form. With `properties` instead, the field is a [nested form](/codemash/cloud/database/schema/field-types/nested-form.md). | `true` | | `maxBytes` | no | The largest stored object, in BSON bytes: 1 to 1048576 (1 MB). | `4096` | ### 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` | | not a JSON object (a string, an array, …) | `CM-ERRORS-DATABASE-039` | `must be a JSON object` | | bigger than `maxBytes` | `CM-ERRORS-DATABASE-040` | `must be at most 4096 bytes (is 5120)` | | a dotted update into a capped object (`{ "notes.x": 1 }`) | `CM-ERRORS-DATABASE-040` | `is a JSON object capped at 4096 bytes — set the whole object, not its member 'x'` | 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.notes.sort' (field 'properties.notes' checked as json.schema.v1).` Also refused at save time: * `properties` next to `additionalProperties: true` — the field is then neither a nested form nor a JSON field: `CM-ERRORS-SCHEMA-010` `Field 'properties.notes' does not match exactly one field type …`. * `maxBytes` outside 1 … 1048576 — `CM-ERRORS-SCHEMA-010`. ## UI schema The cell uses the `json` widget: a code box that refuses text that is not a valid JSON object before the form is sent. ```json { "colSpan": 6, "element": { "fieldId": "notes", "meta": { "widget": "json", "label": "Notes", "placeholder": "{ }" } } } ``` 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, JSON tab: four code boxes Json plain (with a help text), Json type, Json free-form and Json maxBytes, and the Cancel and Create buttons

The JSON tab: json cells are code boxes.

## Records A record the schema accepts: ```json { "notes": { "source": "import", "batch": 12 } } ``` A record it refuses: ```json { "notes": "source=import" } ``` The answer: `CM-ERRORS-DATABASE-039` — `Field 'notes' is invalid: must be a JSON object`. 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 * Without `maxBytes` a dotted update (`{ "notes.batch": 13 }`) is allowed, like any undeclared path. With `maxBytes` the whole object must be sent, because the cap is measured on the stored object. * Members of a JSON field are not indexed or validated; put data you filter on into declared fields. ## Do it from code ```ts await norbix.api.database.insertOne({ collectionName: 'orders', document: JSON.stringify({ notes: { source: 'import', batch: 12 } }), }); ``` ```sh norbix api database one insert --collectionName orders --document '{"notes":{"source":"import","batch":12}}' ``` 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 form](/codemash/cloud/database/schema/field-types/nested-form.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)