Frontmatter schema

zudo-text attaches a small block of YAML frontmatter to every note and archive file — title, timestamps, tags, and other fields your workspace might need. A frontmatter schema lets you define the shape of that block: what fields exist, what types they hold, which ones are required, and which are filled in automatically.

Schemas are per-workspace, stored as a single JSON file, and hot-reloaded while the app is running — you can evolve your schema without restarting the writing app.

For details on the two automatic timestamp modes, the writer-policy design decision, and back-compat rules for the legacy date field, see Auto-managed frontmatter fields.

Where the schema file lives

<workspace-root>/.zudotext/frontmatter-schema.json

The file must be valid JSON and must follow the shape described in the Field types section below.

When the file is missing or cannot be parsed, the writing app falls back to the built-in default schema automatically. A non-blocking warning surfaces through the same diagnostic channel used by other workspace-config errors — the editor keeps running with the default schema active. You can check Settings → Diagnostics (or the status bar) for the warning text.

Default schema

When no workspace schema file is present, the app uses a built-in default defined in @takazudo/frontmatter-schema. The default covers the five fields every zudo-text note is expected to have:

Example schema file

{
  "fields": [
    { "name": "title", "type": "string", "required": true },
    { "name": "status", "type": "enum", "values": ["draft", "review", "done"] },
    { "name": "created_at", "type": "datetime", "auto": "on-create" },
    { "name": "updated_at", "type": "datetime", "auto": "on-save" },
    { "name": "tags", "type": "string-array" },
    { "name": "published", "type": "boolean" }
  ]
}

Field types

Each field in "fields" has a name, a type, and optional metadata:

Enum fields

Enum fields require a "values" array listing the allowed options:

{ "name": "status", "type": "enum", "values": ["draft", "review", "done"] }

Validation reports an error if the frontmatter contains a value not in the list.

Note stickers

The optional note sticker (#7673) — the free-text label shown next to a note's number in the Note Tray, Timeline, Grid and Pile View — is stored under one frontmatter key. That key is a user setting, not part of the schema: AppSettings.general.stickerField (Settings → General → Sticker field), "sticker" by default. isValidStickerFieldName() in @takazudo/app-defaults accepts a plain YAML key and rejects the keys the app already gives a meaning to (title, type, columns, tags, created_at, updated_at, date); an invalid value falls back to the default.

The sticker key is app-owned, so the diagnostics never report it as an unknown field, and a frontmatter block that holds only the sticker is treated like no frontmatter at all — adding a sticker never makes a plain note fail a required field. A schema may still declare the key (for a description); it is then validated like any other declared field.

Sticker writes touch only that key: adding or editing sets it as a quoted-when-needed YAML string, removing deletes only that key, and the body, title, filename and number never change. A change is applied to whichever editor currently owns the note's buffer (unsaved body text included) and saved by that editor; only when no editor holds the note is the file written directly, and that path refuses a note with unsaved edits elsewhere, a deleted slot or a missing file. Schema-driven auto: "on-save" fields are stamped by the owning editor's save path; the direct file path writes the sticker change only.

Validation

The schema validator in @takazudo/frontmatter-schema runs against the parsed frontmatter of every note opened in the editor. Validation is non-blocking: errors surface through the same diagnostic channel used by other workspace-config errors, not as modals or blocking UI. You can keep editing — the warnings are advisory.

Common validation errors:

• Missing required field — a field marked "required": true is absent from the frontmatter.

• Wrong type — a field contains a value that cannot be coerced to the declared type.

• Unknown enum value — a type: "enum" field contains a value not listed in "values".

Hot reload

Edit .zudotext/frontmatter-schema.json in any editor while the writing app is running — the app picks up the change automatically. The file watcher (restart_watchers in tauri-app/src/commands/watchers.rs) monitors the .zudotext/ directory and emits a frontmatter:schemaChanged event. The renderer's useFrontmatterSchema hook subscribes to this event and re-reads the schema without a restart.

Manual reload command: open the command palette and run Reload frontmatter schema. This is the escape hatch when the watcher misses an external edit (network-mounted workspaces, editors that write via a temp-file rename, CI scripts). The default keyboard shortcut for this command is configurable in Settings → Shortcuts.