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.

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.