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

# Rating

An integer field shown as stars: the data schema's maximum is the number of stars.

A **Rating** field is an [Integer](/codemash/cloud/database/schema/field-types/integer.md) field shown as stars. `maximum` is the number of stars; the stored value is the whole number of stars chosen.

**Builder:** Form fields panel → **Rating** · widget `rate` · data type `integer.schema.v1`

## Data schema

```json
{
  "stars": {
    "type": "integer",
    "minimum": 1,
    "maximum": 5
  }
}
```

| Keyword             | Required | What it does                                                             | Example     |
| ------------------- | -------- | ------------------------------------------------------------------------ | ----------- |
| `type`              | yes      | Always `"integer"`.                                                      | `"integer"` |
| `minimum`           | no       | The lowest score (usually `0` or `1`).                                   | `1`         |
| `maximum`           | no       | The number of stars.                                                     | `5`         |
| `default`, `unique` | no       | As on [Integer](/codemash/cloud/database/schema/field-types/integer.md). | `3`         |

### 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`                      |
| not an integer                        | `CM-ERRORS-DATABASE-039` | `must be an integer`                       |
| outside the range                     | `CM-ERRORS-DATABASE-043` | `must be at least 1` / `must be at most 5` |

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.stars.sort' (field 'properties.stars' checked as integer.schema.v1).`

## UI schema

The cell uses the `rate` widget. The same data with `widget: "number"` is a plain number input.

```json
{
  "colSpan": 6,
  "element": {
    "fieldId": "stars",
    "meta": { "widget": "rate", "label": "Rating" }
  }
}
```

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-6319b8c01b4c7c41c3221641516b145e6b57df60%2Ffield-types-numbers-1.png?alt=media" alt="The Numbers tab of the all-types record form; the integer cells at the bottom of the tab include Integer maximum, rendered by the rate widget as stars"><figcaption><p>On the Numbers tab, Integer maximum is a rate cell (stars).</p></figcaption></figure>

## Records

A record the schema accepts:

```json
{ "stars": 4 }
```

A record it refuses:

```json
{ "stars": 7 }
```

The answer: `CM-ERRORS-DATABASE-043` — `Field 'stars' is invalid: must be at most 5`. 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

* Half stars are not possible: a decimal is refused with `must be an integer`.

## Do it from code

```ts
await norbix.api.database.insertOne({
  collectionName: 'reviews',
  document: JSON.stringify({ stars: 4 }),
});
```

```sh
norbix api database one insert --collectionName reviews --document '{"stars":4}'
```

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

[Integer](/codemash/cloud/database/schema/field-types/integer.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)