bwrb schema

Inspect and manage your vault’s schema definition.

Synopsis

bwrb schema <subcommand>

Subcommands

Subcommand	Description
types	Alias for schema list
fields	Alias for schema list <typePath>
list	List schema contents
validate	Validate schema structure
new	Create a type or field
discover	Report frontmatter field-usage facts (descriptive)
diff	Show pending schema changes
migrate	Apply schema changes to notes
history	Show migration history

Quick Examples

# List all types
bwrb schema list
bwrb schema types

# Show specific type details
bwrb schema list type task
bwrb schema fields task

# Validate schema structure
bwrb schema validate

# Create a simple type without prompts
bwrb --non-interactive schema new type idea --directory Ideas \
  --fields marker:text,published:boolean --output json

# Report frontmatter field-usage facts over a folder (descriptive)
bwrb schema discover ./notes

# Preview migration
bwrb schema diff

# Apply migration
bwrb schema migrate --execute

---

list

List schema contents including types, fields, and detailed type information.

When a type, field, or select option has a description, schema list surfaces it — as a dim suffix in the overview tree, on its own line in type <name> detail view, and as a description key in --output json. This makes the schema self-documenting: agents and humans can run bwrb schema list --output json to learn what each type and field is for instead of relying on out-of-band notes.

Synopsis

bwrb schema list [options]
bwrb schema list [options] <typePath>
bwrb schema list [options] -t|--type <typePath>
bwrb schema list types [options]
bwrb schema list fields [options]
bwrb schema list type [options] <name>

Subcommands

Subcommand	Description
(none)	Show full schema overview
types	List type names only
fields	List all fields across all types
type <name>	Show details for a specific type
<typePath>	Alias for type <typePath> (except reserved nouns)

Options

Option	Description
--output <format>	Output format: text, json
-t, --type <typePath>	Alias for type <typePath>

Targeting Rules

• Reserved nouns are deterministic subcommands: types, fields, type
• Use shorthand (<typePath> or --type) for all other type paths
• If mixed forms are provided (for example positional + --type), the command errors with guidance

Field provenance

schema list fields lists the resolved fields for every type, so each type shows its own fields plus the fields it inherits from a parent and the fields it composes from traits — matching what schema list type <name> reports. Every field row carries an origin so you can tell where it came from:

origin	Meaning
own	Declared directly on the type
trait:<name>	Composed from the named trait
inherited:<name>	Inherited from the named ancestor type

In text output the origin is the leading token in the DETAILS column. In JSON output (--output json) each entry in data.fields gains an origin string alongside the existing type, field, and definition. A schema with no inheritance or traits lists the same fields as before, each with origin: "own".

Examples

# Show full schema overview
bwrb schema list

# List all type names
bwrb schema list types

# List all fields across types
bwrb schema list fields

# Show details for a specific type
bwrb schema list type task
bwrb schema list type objective/milestone

# Equivalent aliases for type details
bwrb schema list task
bwrb schema list --type task
bwrb schema list -t objective/milestone

# JSON output for scripting
bwrb schema list --output json
bwrb schema list types --output json
bwrb schema list fields --output json
bwrb schema list type task --output json
bwrb schema list -t task --output json

---

types alias

schema types is a discovery-friendly alias for schema list.

Synopsis

bwrb schema types [options]

Options

Option	Description
--output <format>	Output format: text, json
--verbose	Show all types with fields inline

Examples

bwrb schema types
bwrb schema types --verbose
bwrb schema types --output json

---

fields alias

schema fields <typePath> is a discovery-friendly alias for schema list <typePath>. Use schema list fields when you want the all-fields overview across every type.

Synopsis

bwrb schema fields <typePath> [options]

Options

Option	Description
--output <format>	Output format: text, json

Examples

bwrb schema fields task
bwrb schema fields objective/milestone --output json

---

validate

Validate your schema.json file for structural correctness.

Synopsis

bwrb schema validate [options]

Options

Option	Description
--output <format>	Output format: text, json

Description

Validates the schema.json file against the expected structure:

• Required fields are present
• Field types are valid
• Select options are properly defined inline on their fields
• Type hierarchies are consistent
• Types missing output_dir emit a warning (computed directory included)

Warnings are printed to stderr in text mode. In JSON mode, warnings are included in data.warnings.

Examples

# Validate schema
bwrb schema validate

# JSON output for CI
bwrb schema validate --output json

Exit Codes

Code	Meaning
0	Schema is valid
1	Validation errors found

---

new

Create schema types and fields interactively or through the bounded non-interactive type surface.

bwrb schema new type [name] [options]
bwrb schema new field [type] [name]

schema new type accepts --directory, --inherits, --description, --output, and comma-separated --fields name:type definitions. In global --non-interactive mode, the type name and every required value must be explicit. The shorthand intentionally supports only field shapes that are complete from a type name alone. A select or other prompt-rich definition is rejected promptly without creating a partial type and tells you to rerun schema new field <type> <field> in a TTY.

# Safe headless creation
bwrb --non-interactive schema new type idea --directory Ideas \
  --fields marker:text,published:boolean --output json

# Prompt-rich fields belong in the interactive field editor
bwrb schema new field idea status

---

discover

Report descriptive facts about the frontmatter across a folder of Markdown notes. discover reports what is there — every field, how often it appears, the value-types it holds, and which files diverge. It never passes or fails, never prescribes, and is safe to run anytime, including on a messy folder that has no schema yet.

It works on an arbitrary folder path, not only a managed vault, so you can point it at unmanaged Markdown during onboarding.

Descriptive vs. audit

discover is descriptive: it states facts and exits non-zero only for a real error (such as an unreadable path), never for “non-conforming” data. bwrb audit is prescriptive: it reports what is wrong relative to the schema, with exit codes and --fix. Use discover to understand a folder; use audit to enforce the schema.

Two roles

Role	When	What it surfaces
Onboarding	Before a schema exists	Every field, its frequency, value-type consistency, and which files diverge — raw material for designing types.
Drift detection	After a schema exists	Additionally: fields used but not defined, fields defined but unused, and values diverging from declared select options.

A schema is used automatically when a .bwrb/schema.json is found at or above the scanned folder (or via --vault). When none is found, discover runs in the onboarding role. Use --no-schema to force the onboarding view even when a schema is present.

Synopsis

bwrb schema discover [path] [options]

path defaults to the current directory.

Options

Option	Description
--output <format>	Output format: text (default), json
--no-schema	Skip drift detection; report raw field facts only

Examples

# Scan the current directory
bwrb schema discover

# Scan an arbitrary folder (onboarding)
bwrb schema discover ./notes

# Structured facts for scripting or agents
bwrb schema discover ./notes --output json

# Skip drift even if a schema is present
bwrb schema discover ./notes --no-schema

JSON output

--output json emits the standard { "success": true, "data": ... } envelope. The data object has this shape:

{
  "root": "/abs/path/scanned",
  "totalFiles": 4,
  "filesWithFrontmatter": 3,
  "unreadable": [],                 // { file, error } for skipped files AND nested unreadable subdirs (never fatal)
  "schemaPresent": true,            // whether a schema was loaded for drift
  "fields": [
    {
      "field": "status",
      "count": 3,                   // notes in which the field appears
      "frequency": 1,               // count / filesWithFrontmatter (0..1)
      "types": [                    // observed value-types, by descending count
        { "type": "string", "count": 3 }
      ],
      "mixedTypes": false,          // true when >1 non-empty value-type
      "divergingFiles": [],         // files whose type differs from the most common
      "defined": true,              // schema role: declared by any type?
      "divergingOptions": [         // schema role: values outside declared options
        { "value": "wibble", "files": ["c.md"] }
      ]
    }
  ],
  "drift": {                        // present only when a schema was loaded
    "usedButUndefined": ["deadline"],
    "definedButUnused": ["rating"],
    "optionDivergences": [
      { "field": "status", "values": [ { "value": "wibble", "files": ["c.md"] } ] }
    ]
  }
}

Value-types are coarse, frontmatter-shaped buckets: string, number, boolean, date (an ISO-ish date string), list, object, and empty (null / empty string / empty list).

Exit Codes

Code	Meaning
0	Report produced (including for non-conforming data)
2	Real error (for example, the path is missing or unreadable)

A scanned root that exists but whose contents cannot be listed (for example a directory with chmod 000) is a real error and exits 2 — it is never reported as “0 files”. By contrast, an unreadable nested subdirectory found mid-walk is recoverable: the rest of the tree is still scanned (exit 0) and the locked subdirectory is surfaced in the unreadable list rather than silently dropped.

---

diff

Show changes to the schema since the last migration.

Synopsis

bwrb schema diff [options]

Options

Option	Description
-o, --output <format>	Output format: text, json

Description

Compares the current schema.json against the last migration snapshot to show:

• New types added
• Types removed
• Fields added to types
• Fields removed from types
• Field definitions changed
• Select options changed

Examples

# Show what changed
bwrb schema diff

# JSON output for scripting
bwrb schema diff -o json

Workflow

1. Make changes to .bwrb/schema.json
2. Run bwrb schema diff to preview changes
3. Run bwrb schema migrate to apply changes to existing notes

---

migrate

Apply schema changes to existing notes in your vault.

Synopsis

bwrb schema migrate [options]

Options

Option	Description
-x, --execute	Actually apply the migration (default is dry-run)
-y, --yes	Accept execute confirmations
--set-version <version>	Set the new schema version for execute mode (semver, e.g. 1.2.3)
--no-backup	Skip backup creation (not recommended)
--show-changes	Show per-note before/after changes in the dry-run preview
--output <format>	Output format: text, json

Description

Migrations update existing notes when the schema changes:

• Add new required fields with default values
• Remove deleted fields
• Rename fields
• Update select options
• Move files to new output directories

Safety

• Dry-run by default: Shows what would change without modifying files
• Automatic backup: Creates a backup before applying changes
• Explicit headless execution: Non-interactive runs with note changes require --set-version; non-deterministic changes also require --yes
• Atomic operations: All changes succeed or none are applied
• Vault-wide typed-note discovery: A note remains a migration target when its frontmatter type is valid even if it has been moved outside the type’s configured output directory
• Required-field blockers: If a planned cleanup would clear a required field and no schema default provides a safe replacement, preview JSON reports blocked / blockers; execute exits non-zero before writing notes, backups, snapshots, version, or history. Set an explicit valid value and retry rather than accepting an arbitrary replacement option.

Examples

# Preview migration (dry-run)
bwrb schema migrate

# Apply migration with backup
bwrb schema migrate --execute

# Apply non-interactively with JSON output
bwrb schema migrate --execute --set-version 1.1.0 --output json

# Apply a non-deterministic migration non-interactively
bwrb schema migrate --execute --set-version 2.0.0 --yes --output json

# Apply without backup (not recommended)
bwrb schema migrate --execute --no-backup

Workflow

1. Make changes to .bwrb/schema.json
2. Run bwrb schema diff to preview changes
3. Run bwrb schema migrate to preview note updates
4. Run bwrb schema migrate --execute to apply

---

history

View the history of schema migrations applied to your vault.

Synopsis

bwrb schema history [options]

Options

Option	Description
--limit <n>	Number of entries to show (default: 10)
-o, --output <format>	Output format: text, json

Description

Shows a log of all migrations that have been applied:

• Migration timestamp
• Changes included
• Files affected

Examples

# Show migration history
bwrb schema history

# Show last 5 migrations
bwrb schema history --limit 5

# JSON output
bwrb schema history -o json

---

See Also

• Schema — Understanding schema structure
• Migrations — Migration workflow
• bwrb audit — Validate notes against schema