---
title: "Settings (OrgSettingsDecl)"
description: "Generated from the doc schema (CatalogDocSchema, @canonify/kernel-catalog/doc): each field’s type, default and description are the schema’s own, and each example is a bundle file that readBundle…"
order: 12
id: "model/settings"
---

# Settings (OrgSettingsDecl)

Generated from the doc schema (`CatalogDocSchema`, @canonify/kernel-catalog/doc): each field’s type, default and description are the schema’s own, and each example is a bundle file that readBundle decodes. A field’s Example is its value in one of those examples.

## OrgSettingsDecl {#orgsettingsdecl}

The org settings.

| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| `locale` | `"en"` \| `"da"` | yes | — | `"en"` | The org default locale for words and formats; readers may choose another. |
| `locales` | (`"en"` \| `"da"`)[] | no | — | `["da","en"]` | The locales the org serves, the default locale among them; absent = only the default locale. |
| `zone` | string (matching `^(UTC\|[A-Z][A-Za-z_-]+(\/[A-Za-z0-9_+-]+){1,2})$`) | yes | — | `"Europe/Copenhagen"` | The IANA time zone of the org clock, e.g. Europe/Copenhagen. |
| `currency` | string (matching `^[A-Z]{3}$`) | no | — | `"DKK"` | An ISO 4217 code used only by the converter and authoring defaults, never by a codec. |
| `units` | Record<string (matching `^[a-z][a-z0-9_]{0,31}$`), [OrgSettingsDecl.units](settings.md#orgsettingsdecl.units)> | no | — | `{"visit":{"label":{"da":"Besøg"}}}` | Tenant count-like units by code, with no conversion (C46). |
| `retention` | [RetentionDecl](settings.md#retentiondecl) | no | — | (see the example) | How long retired data is kept (authz). |
| `authoring` | [AuthoringPolicyDecl](settings.md#authoringpolicydecl) | no | — | (see the example) | Who may propose and approve catalog changes (authz). |
| `search` | [OrgSettingsDecl.search](settings.md#orgsettingsdecl.search) | no | `{"language":"simple"}` | `{"language":"simple"}` | How the org’s search index reads words; absent = simple. |

`settings.json`

```json
{
  "locale": "da",
  "locales": ["da", "en"],
  "zone": "Europe/Copenhagen",
  "currency": "DKK",
  "units": { "visit": { "label": "Besøg" } },
  "search": { "language": "da" }
}
```

## OrgSettingsDecl.units {#orgsettingsdecl.units}

A tenant unit.

| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| `label` | [Text](shapes.md#text) | yes (a draft may leave it out: propose writes a default made from the name, `catalog.label_defaulted`) | — | `{"da":"Besøg"}` | The words shown for the unit. |

## OrgSettingsDecl.search {#orgsettingsdecl.search}

How the org’s search index reads words; absent = simple.

| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| `language` | `"simple"` \| `"en"` \| `"da"` | yes | — | `"simple"` | The stemming language of the search index; simple folds without stemming. |

## RetentionDecl {#retentiondecl}

How long retired data, audit rows and other retained rows are kept, in days; absent = the plan floors (authz §2.9).

| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| `auditDays` | integer (greater than 0) | no | — | `730` | Days the org’s audit rows are kept; absent = the plan floor (365). |
| `historyAfterDeleteDays` | integer (greater than 0) | no | — | `365` | Days a deleted record’s history is kept; absent = the plan floor (365). A live record’s history is never pruned. |
| `retiredDays` | integer (greater than 0) | no | — | `60` | Days retired data (a removed property or type) is kept before it is collected; absent = the plan floor (30). |
| `receiptDays` | integer (greater than 0) | no | — | `7` | Days idempotency receipts are kept; absent = the plan floor (7). |
| `outboxDeliveredDays` | integer (greater than 0) | no | — | `30` | Days a delivered outbox row is kept; absent = the plan floor (14). |
| `carrierSessionDays` | integer (greater than 0) | no | — | `14` | Days an ended visitor session is kept; absent = the plan floor (14). |
| `evidenceDays` | integer (greater than 0) | no | — | `3650` | Days e-sign evidence is kept; absent = the plan floor (1,826). |

The `retention` of `settings.json`.

```json
{
  "auditDays": 730,
  "historyAfterDeleteDays": 365,
  "retiredDays": 60,
  "receiptDays": 7,
  "outboxDeliveredDays": 30,
  "carrierSessionDays": 14,
  "evidenceDays": 3650
}
```

## AuthoringPolicyDecl {#authoringpolicydecl}

Who may propose and approve catalog changes; absent = the platform default (authz).

| Field | Type | Required | Default | Example | Description |
|---|---|---|---|---|---|
| `agentMayPromote` | (`"metadata"` \| `"additive"` \| `"data_converting"` \| `"retiring"` \| `"policy"`)[] | no | `["metadata","additive"]` | `["metadata","additive","data_converting"]` | The classes an agent’s proposal may promote after a green dry run; default metadata and additive. |
| `ownerApproves` | (`"metadata"` \| `"additive"` \| `"data_converting"` \| `"retiring"` \| `"policy"`)[] | no | `["data_converting","retiring","policy"]` | `["retiring","policy"]` | The classes an agent’s proposal waits for an owner’s approval on; default data_converting, retiring and policy. |

The `authoring` of `settings.json`.

```json
{
  "agentMayPromote": ["metadata", "additive", "data_converting"],
  "ownerApproves": ["retiring", "policy"]
}
```