Validation and Audit

Bowerbird validates notes against your schema and helps fix violations.

Hard vs Soft Enforcement

Hard enforcement — bwrb new and bwrb edit refuse to create invalid notes
Soft enforcement — Manual edits can break the schema; bwrb audit catches drift

Running Audit

Check your entire vault:

bwrb audit

Check specific types:

bwrb audit --type task

Common Issues

Audit catches:

Missing required fields
Invalid field values (not in a select field’s inline options)
Type mismatches
Malformed frontmatter

Built-in fields recognized by bwrb (id, name, and forked-from) are always allowed and never reported as unknown-field. Ordinary interactive and JSON creation writes id and name; the name remains the note identity even when the physical filename is normalized or pattern-derived.

Fixing Issues

bwrb audit --fix applies fixes by default, but requires explicit targeting (use --all to target the full vault).

Preview fixes without writing:

bwrb audit --path "Ideas/**" --fix --dry-run

Apply fixes:

bwrb audit --path "Ideas/**" --fix

Apply fixes across the entire vault:

bwrb audit --all --fix

Hygiene Warnings

Audit also reports low-risk hygiene warnings to keep frontmatter deterministic and reduce noisy diffs.

Example: trailing-whitespace checks raw frontmatter key: value lines for trailing spaces/tabs.
Scope is intentionally narrow: block scalar content (|/>) is ignored, and whitespace inside quoted values is allowed.
Fix behavior is minimal-diff line trim only; it does not reserialize YAML.

Automation note:

# Preview auto-fixes
bwrb audit --fix --auto --all

# Apply execute-gated auto-fixes (including trailing-whitespace)
bwrb audit --fix --auto --execute --all

See the bwrb audit command reference for exact issue semantics and fix gating details.

CI Integration

Run audit in CI to catch schema violations:

bwrb audit --output json
# Exit code 1 if violations found

Describe vs. enforce: `discover` vs. `audit`

audit is prescriptive — it reports what is wrong relative to the schema, exits non-zero when it finds violations, and can --fix them.

bwrb schema discover is the descriptive counterpart. It reports frontmatter facts over a folder — every field, its frequency, the value-types it holds, which files diverge, and (when a schema exists) drift such as used-but-undefined fields, defined-but-unused fields, and values diverging from declared options. It never passes or fails and is safe to run anytime.

Two ways to reach for it:

Before a schema exists — point discover at a messy folder to gather raw material for designing types.
After a schema exists — use it to see drift descriptively, then use audit to enforce the schema.

# Describe what's in a folder (no judgment)
bwrb schema discover ./notes

# Enforce the schema (pass/fail, fixable)
bwrb audit

Next Steps

Migrations — Evolving your schema over time
Bulk operations — Batch fixes