Configuration on back(d)

Data model (CONFIG_DIR)

Mon, 01 Jan 0001 00:00:00 +0000

The data model is a directory tree under CONFIG_DIR, loaded once at startup. Directories define realms and databases, and a schema.json defines a collection.

$CONFIG_DIR/<realm>/
 realm.yaml # required — realm settings
 email/<kind>/ # optional — email templates (see Functions → Email)
 app-config/ # optional — app configuration: schema.json and rules.yaml
 <database>/<collection>/
 schema.json # required — JSON Schema draft 2020-12
 indexes.json # optional — index declarations
 collection.yaml # optional — access rules, file fields, soft delete, erase policy
 rules.test.yaml # optional — tests of the rules (`backd rules test`)
 <database>/_functions/ # optional — server-side functions

Each directory under CONFIG_DIR is a realm. It must contain a realm.yaml.
Each directory inside a realm is a database, stored in the MongoDB database <realm>__<database>.
Each directory inside a database is a collection, stored in a MongoDB collection of the same name. It must contain a schema.json.
A realm’s email folder holds its email templates, pages is reserved for the pages backd will serve, push holds push templates and consents holds the consent texts: none is a database, so they are never read as one and can’t be database names.
A realm’s app-config folder declares its app configuration, and is not a database either.
A database’s _functions directory holds its functions, not a collection.
Other plain files at the realm and database levels are ignored, as are hidden entries (names starting with .).
Changing the config requires a restart — except with BACKD_DEV=true, which reloads it live (see Dev mode).

Starting from a template

backd template writes commented starter files, so you don’t have to start from an empty directory. It only needs CONFIG_DIR.

App configuration

Mon, 01 Jan 0001 00:00:00 +0000

App configuration is one realm-level configuration for your client apps: feature flags, maintenance switches, promotions, limits. It is declared like collections (a JSON Schema and read rules), changed at runtime by administrators and functions only, and read by apps through one endpoint with caching.

It is not a secrets store (see No secrets, no encryption), not a content store (the whole configuration is at most 64 KiB), and not a targeting system: there are no per-user or percentage rollouts. Time-based changes are your own cron functions.

Realm settings (realm.yaml)

Mon, 01 Jan 0001 00:00:00 +0000

Every realm directory must contain a realm.yaml. It holds the settings that apply to the whole realm: its users, how they sign in, and which browser origins may call it.

$CONFIG_DIR/<realm>/realm.yaml

If a realm has no realm.yaml, backd refuses to start and names the realm. Create a commented starter file with:

CONFIG_DIR=./config backd template realm --realm <realm>

Example

auth: enabled
signup: invite
sessions:
 idle_timeout: 14d
 max_lifetime: 60d
password:
 min_length: 14
cors:
 origins:
 - https://app.example.com
 - http://localhost:5173
roles:
 admin:
 description: Manages users and invitations
 admin: true
 users:
 - ops@example.com
 - email: lead@example.com
 editor:
 description: Can publish articles

An empty file, or one with only comments, is valid: every key has a default.

Custom ids

Mon, 01 Jan 0001 00:00:00 +0000

By default backd generates the id of every document. A collection can instead take it from the client, for ids that mean something: an invoice number, a reference from another system, or the user’s own id for one document per user. This page is about when to use that and how to do it safely; the declaration is in collection.yaml, and the requests and errors are in Create.

When to use them

Use	Why
One document per user (profile, settings, preferences)	`custom_id: user` makes the id the user’s own, so the document is found with `GET …/profiles/<user id>`, nothing else is needed to keep it unique, and backd refuses an id that isn’t the caller’s
A number or reference that exists outside backd	The document is addressed by the number you already print and receive; a second one with the same number is refused
Human-readable keys of reference data (`EUR`, `de-DE`)	Fixed vocabularies you create and own

Don’t use them for anything that might change (an id never changes), for anything that holds personal data (see below), or only to avoid a unique index: a unique field in indexes.json works with generated ids and can change.

Schema validation

Mon, 01 Jan 0001 00:00:00 +0000

Every collection’s schema.json is enforced at two levels.

API level (authoritative). Every write is validated against the full JSON Schema draft 2020-12 before it reaches the database. Failures return 400 with one entry per failing field.
Database level (safety net). The same schema is translated into a MongoDB $jsonSchema collection validator. This protects the data from writes that bypass the API. MongoDB’s dialect is older and smaller, so the translation covers a subset of the schema.

Translation to MongoDB

JSON Schema	MongoDB `$jsonSchema`
`type: string` / `boolean` / `object` / `array` / `null`	`bsonType: string` / `bool` / `object` / `array` / `null`
`type: integer`	`bsonType: [int, long, double]` plus `multipleOf: 1`, unless the schema sets its own `multipleOf`
`type: number`	`bsonType: [int, long, double, decimal]`
`const: v`	`enum: [v]`
`exclusiveMinimum: n` / `exclusiveMaximum: n`	`minimum` / `maximum: n` plus `exclusiveMinimum` / `exclusiveMaximum: true`
`properties`, `required`, `enum`, `minimum`, `maximum`, `multipleOf`, `minLength`, `maxLength`, `pattern`, `items`, `minItems`, `maxItems`, `uniqueItems`, `additionalProperties`, `minProperties`, `maxProperties`, `allOf`, `anyOf`, `oneOf`, `not`	copied as-is (subschemas translated recursively)

Annotations (title, description, default, examples, $comment, …) are dropped silently.
Any other keyword (for example format, $ref/$defs, prefixItems, unevaluatedProperties or if/then/else) is left out of the database validator and logged at info level with its location. The API level still enforces it.

Finding documents that no longer match

A schema is enforced when a document is written. Documents stored before you changed the schema are not touched, and MongoDB is set to leave them alone (validationLevel: moderate): a collection can hold documents that would be refused today. A schema check lists them. It reads every stored document, validates it with the same full validator the API uses on a write (so it also sees the keywords MongoDB’s translation leaves out, such as format), and reports the ones that fail. It never writes anything.

Configuration on back(d)

Data model (CONFIG_DIR)

Starting from a template#

App configuration

Realm settings (realm.yaml)

Example#

Custom ids

When to use them#

Schema validation

Translation to MongoDB#

Finding documents that no longer match#

Starting from a template

Example

When to use them

Translation to MongoDB

Finding documents that no longer match