> 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/currency.md). # Currency A money field: an object { value, currency } with an allow-list of currency codes and a step for the amount. A **Currency** field stores money as an object with an amount and a currency code: `{ "value": 19.99, "currency": "EUR" }`. The schema lists which currencies are allowed and how many decimal places the amount may have. **Builder:** Form fields panel → **Number → amount of money** · widget `currency` · data type `currency.schema.v1` ## Data schema ```json { "price": { "type": "object", "properties": { "value": { "type": "number", "minimum": 0, "maximum": 100000, "multipleOf": 0.01 }, "currency": { "type": "string", "enum": ["EUR", "USD", "GBP"], "default": "EUR" } }, "default": { "value": 0, "currency": "EUR" } } } ``` | Keyword | Required | What it does | Example | | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `type` | yes | Always `"object"`. | `"object"` | | `properties.value` | yes | The amount: `type` `number` or `integer`, with optional `minimum`, `maximum` and `multipleOf` (the step, any positive number — `0.01` for cents). | `{ "type": "number", "multipleOf": 0.01 }` | | `properties.currency.enum` | yes | The allowed codes, at least one of: USD, EUR, GBP, JPY, AUD, CAD, CHF, CNY, SEK, NZD, MXN, SGD, HKD, NOK, KRW. | `["EUR", "USD"]` | | `properties.currency.default` | no | The code the form starts with. | `"EUR"` | | `default` | no | A whole `{ value, currency }` object for new records. | `{ "value": 0, "currency": "EUR" }` | ### 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 object with `value` and `currency` | `CM-ERRORS-DATABASE-039` | `must be a currency object {"value": number, "currency": "EUR"}` | | `value` is not a number | `CM-ERRORS-DATABASE-039` | `the amount (value) must be a number` | | `value` off the step | `CM-ERRORS-DATABASE-044` | `the amount (value) must be a multiple of 0.01` | | `value` outside the range | `CM-ERRORS-DATABASE-043` | `the amount (value) must be at least 0` / `… at most 100000` | | `currency` is not a string | `CM-ERRORS-DATABASE-039` | `the currency code must be a string` | | `currency` is not in the allow-list | `CM-ERRORS-DATABASE-045` | `currency 'JPY' is not one of: EUR, USD, GBP` | | a declared member is missing, or an extra member is sent | `CM-ERRORS-DATABASE-047` | `the 'currency' member is required` / `unknown member 'note' (allowed: value, currency)` | 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.price.sort' (field 'properties.price' checked as currency.schema.v1).` Also refused at save time: * a `multipleOf` that is not positive, or a `default` off the step or outside the amount range — `CM-ERRORS-SCHEMA-022` / `CM-ERRORS-SCHEMA-037`. * a code outside the 15 supported ones in `properties.currency.enum` — `CM-ERRORS-SCHEMA-010`. ## UI schema The cell uses the `currency` widget: a currency selector in front of the amount. The step and the code list are data rules; the UI schema carries nothing about them. ```json { "colSpan": 4, "element": { "fieldId": "price", "meta": { "widget": "currency", "label": "Price", "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).
The Numbers tab of the all-types record form: currency cells such as Currency plain and Currency properties value, each with a USD or EUR selector followed by the amount input

Currency cells on the Numbers tab: the selector shows the allowed codes.

## Records A record the schema accepts: ```json { "price": { "value": 19.99, "currency": "EUR" } } ``` A record it refuses: ```json { "price": { "value": 19.99, "currency": "JPY" } } ``` The answer: `CM-ERRORS-DATABASE-045` — `Field 'price' is invalid: currency 'JPY' is not one of: EUR, USD, GBP`. 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 [nested form](/codemash/cloud/database/schema/field-types/nested-form.md) may not declare the members `value` + `currency` together — that shape *is* the currency type and the save is refused (`CM-ERRORS-SCHEMA-010`, "does not match exactly one field type"). * Filter on the amount with a dotted path: `{ "price.value": { "$gt": 10 } }`. ## Do it from code ```ts await norbix.api.database.insertOne({ collectionName: 'products', document: JSON.stringify({ price: { value: 19.99, currency: 'EUR' } }), }); ``` ```sh norbix api database one insert --collectionName products --document '{"price":{"value":19.99,"currency":"EUR"}}' ``` 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 [Decimal](/codemash/cloud/database/schema/field-types/decimal.md) · [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)