2. Vault Lint
Forge scans .md markdown notes against your schema, enabled lint settings, and optional shape validation rules.
Non-markdown files are exempt from Vault Lint and Shape Lint. They can still appear in inventory and export counts, but they are not metadata- or shape-validated.
Vault Lint is read-only for vault notes.
The only files it writes are reports, history files, and generated summaries.
Run:
Forge: Run Vault Lint
What Vault Lint Checks
Vault Lint helps detect:
- missing metadata
- malformed frontmatter
- inconsistent tags
- invalid field values
- stale notes
- undocumented inline metadata
- structural drift
- shape mismatches
The goal is not perfection.
The goal is helping the vault remain consistent and dependable over time.
Outputs
Forge writes lint output into:
A-I/Forge/Exports
Typical outputs include:
| Output | Purpose |
|---|---|
lint-report.json | Latest machine-readable lint results |
lint-history.json | Historical lint summaries |
| lint run notes | Human-readable summaries and reports |
These reports help track how vault structure changes over time.
Rule Coverage
| Rule | Meaning | Severity Source |
|---|---|---|
no_frontmatter | File has no YAML frontmatter block | Error |
required_field | Required schema field is missing | Field severity |
enum_value | Field value is not in the schema enum list | Field severity |
date_format | Date field is not yyyy-MM-dd | Field severity |
stale_date | Date field is older than stale_after_days | Field severity |
type_mismatch | Field value has the wrong YAML type | Field severity |
unique_field | Field value is duplicated across scanned notes when the schema sets unique: true | Field severity |
tag_namespace | Tag has no namespace slash | Tag rule severity |
unknown_tag_namespace | Tag namespace is not allowed by schema | Tag rule unknown_tags |
required_when | Conditional field is missing | Rule severity or field severity |
forbidden_when | Conditional field exists when it should not | Rule severity or field severity |
tag_consistency | Field value does not have a matching namespaced tag | Rule severity or field severity |
invalid_shape_ref | Shape reference points at an unknown shape | Field severity |
inline_is_schema_field | Inline key duplicates a schema frontmatter field | Warning |
inline_fuzzy_schema | Inline key resembles a schema field typo | Warning |
inline_fuzzy_inline | Inline key resembles an allowed inline field typo | Warning |
inline_undocumented | Inline key is not listed in inline.allowed | Info |
stale_note | Review cycle has elapsed | Needs Review |
stale_inbox_note | Inbox note is older than the configured retention threshold when inbox retention action lists stale inbox notes for review | Needs Review |
shape_heading_missing | Required heading is missing | Error |
shape_heading_order | Headings exist but are out of order | Warning |
shape_heading_extra | Heading exists outside the expected structure | Info or warning |
shape_section_empty | Required section exists but contains no direct content | Info or warning |
Severity Levels
Forge groups findings by severity so you can prioritize cleanup gradually.
Typical severity levels include:
| Severity | Meaning |
|---|---|
error | Structural issue likely to break consistency or workflows |
warning | Important inconsistency that should usually be reviewed |
info | Informational issue or soft consistency recommendation |
review | Valid note that needs a human review pass, shown outside lint issues |
Schemas can define severity levels for many rules directly.
This allows different vaults to enforce structure differently.
A research vault may enforce stricter metadata than a lightweight journal vault.
Why Linting Matters
Many Obsidian workflows depend on predictable structure.
That includes:
- Dataview
- Bases
- dashboards
- templates
- exports
- automation workflows
- AI-assisted systems
Without consistent metadata, those systems gradually become unreliable.
Examples:
projectvsprojectsactivevsin-progress- malformed dates
- undocumented tags
- inconsistent note types
Vault Lint helps surface those problems before they spread.
Stale Note Review
Forge can find notes whose review cycle has elapsed.
These findings are not lint errors or warnings. They appear in the dashboard's Needs Review section and do not make lint fail.
Typical configuration includes:
- a cycle field, usually
review_cycle - an updated field, usually
updated - optional note type filters
Example review cycles:
daily
weekly
monthly
quarterly
never
never acts as an opt-out.
Stale review workflows are especially useful for:
- project systems
- research vaults
- operational notes
- evergreen documentation
- team vaults
Forge can also flag stale inbox notes when:
Inbox retention action -> List under Needs Review
is enabled in maintenance settings.
Inline Metadata Checks
When:
Lint inline metadata
is enabled, Forge scans body metadata like:
source:: example
Forge can detect:
- undocumented inline keys
- typo-like keys
- collisions with frontmatter fields
Keep inline metadata keys listed in:
inline:
allowed:
to avoid accidental drift.
Shape Validation
If Shapes are enabled, Vault Lint can also validate heading structures and section organization.
This helps detect:
- missing sections
- unexpected headings
- empty required sections
- structure drift over time
Shape validation is especially useful for:
- project templates
- meeting notes
- research pipelines
- operational runbooks
- reusable workflows
Recommended Workflow
A common lint workflow looks like this:
- Validate schema
- Run Vault Lint
- Review findings
- Normalize metadata
- Repair inconsistencies
- Re-run lint
- Export dashboards and summaries
Over time, this helps the vault become:
- easier to maintain
- easier to query
- more consistent
- more reliable for Dataview and Bases
- easier to use with AI workflows
