Configuration on backd

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)
 <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, and pages is reserved for the pages backd will serve; neither is a database, so they are never read as one and can’t be database names.
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. There is no hot-reload.

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.

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.

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 backd

Data model (CONFIG_DIR)

Starting from a template#

Realm settings (realm.yaml)

Example#

Schema validation

Translation to MongoDB#

Finding documents that no longer match#

Starting from a template

Example

Translation to MongoDB

Finding documents that no longer match