Free tool · works now

Frontmatter batch auditor

Inventory properties, detect mixed scalar/list types, and resolve schema drift across your Markdown notes.

Vault Frontmatter Schema Auditor

Paste multiple notes with filename headers to inspect property hygiene, flag mixed scalar/list collisions, audit casing drift, and generate normalization plans.

100% Browser-LocalNo Silent FlatteningFormula-Guarded CSV
0%Cleanliness Score
5Notes Audited
11Unique Keys
2Mixed Scalar/List Conflicts
2Casing Anomalies
Multi-Note Source BufferSeparate notes using === filename.md === headers
1345 characters
Property KeyCoverageKindsDetected TypesStatus & Diagnostic
authorVariants: author, Author60% (3/5)scalar, liststring, list_string❌ Mixed Scalar/List

CRITICAL: Mixed scalar and list values! Standardize on List (e.g. wrap single values in [brackets]) or Scalar.

tags80% (4/5)scalar, liststring, list_string❌ Mixed Scalar/List

CRITICAL: Mixed scalar and list values! Standardize on List (e.g. wrap single values in [brackets]) or Scalar.

statusVariants: status, Status60% (3/5)scalarstring, boolean⚠️ Type Drift

Standardize key casing to "status" across all notes.

priority80% (4/5)scalarstring, number⚠️ Type Drift

Multiple data types detected (string, number). Harmonize field types.

StatusVariants: status, Status20% (1/5)scalarstring⚠️ Casing Drift

Standardize key casing to "status" across all notes.

AuthorVariants: author, Author20% (1/5)scalarstring⚠️ Casing Drift

Standardize key casing to "author" across all notes.

title80% (4/5)scalarstring✅ Consistent
created_at40% (2/5)scalardate✅ Consistent
review_date40% (2/5)scalardate✅ Consistent
createdAt40% (2/5)scalardate✅ Consistent
reviewer20% (1/5)unresolvedunresolved✅ Consistent

Comprehensive Guide: Auditing Frontmatter & Curing Schema Drift in Note Vaults

Personal knowledge management (PKM) vaults and research note collections grow organically over months and years. While the freedom of plain Markdown text is liberating, frontmatter properties (YAML metadata) invariably suffer from schema drift: identical concepts recorded under varying keys, conflicting data types across files, and the insidious issue of mixed scalar and list representations. This comprehensive technical guide analyzes the anatomy of frontmatter drift, the hazards of silent type flattening, cross-platform casing collisions, and strategies for sustainable vault governance.

1. What is Schema Drift and How Does It Arise in Markdown Vaults?

In relational databases, schemas are enforced by strict constraints, migrations, and table definitions. In contrast, Markdown notes follow a "schema-on-read" philosophy: authors type arbitrary YAML key-value pairs at the top of individual files.

Over time, schema drift occurs through several natural behavioral dynamics:

  • Evolving Taxonomy: In January, a note author uses category: Systems; by June, they switch to tags: [systems]; by December, an automated template introduces topic: Systems.
  • Device & Client Divergence: Notes written on mobile devices often adopt abbreviated property names (e.g. stat: done) compared to desktop templates (status: completed).
  • Multi-Plugin Ecosystems: Different community plugins in tools like Obsidian or Logseq impose conflicting property expectations. One plugin parses aliases: [Note Alias] as a list, while another expects a single string.
  • Collaborative Authorship: When multiple team members check Markdown files into a shared Git repository, slight differences in naming habits (such as due_date versus dueDate) quickly multiply across directories.

Left unchecked, schema drift degrades search precision, causes Dataview or SQL queries to omit critical notes, and complicates migrations to static site generators or dedicated database runtimes.

2. The Critical Failure: Silent Type Flattening and Mixed Scalar/List Collisions

Among all schema inconsistencies, the most destructive is the mixed scalar and list collision. This occurs when the exact same property key holds a scalar primitive in some notes and an array list in others.

The Real-World Hazard Scenario

Consider two files in a knowledge vault:

# note-a.md
---
title: "Distributed Systems Overview"
tags: systems
---
# note-b.md
---
title: "Consensus Algorithms"
tags:
  - systems
  - consensus
---

In note-a.md, tags is a string scalar. In note-b.md, tags is an array list of strings.

Many naïve audit scripts attempt to "clean" this data by silently flattening the list (e.g. converting [systems, consensus] into the joined string "systems, consensus") or coercing scalar values into single-item arrays without alerting the author. This silent modification corrupts data integrity:

  1. Loss of Dimensionality: Flattening arrays into comma-separated strings destroys distinct token boundaries, confusing search indexers and breaking exact tag lookups.
  2. Unintended Serialization Bugs: In YAML, a string containing a comma is still a single string scalar. If downstream tools expect an array, iterating over the property results in iterating over individual characters rather than list entries.
  3. Query Breakage: Static site generators such as Astro, Hugo, or Eleventy generate taxonomy pages by flat-mapping tag arrays. If a scalar string enters the collection pipeline, runtime type exceptions occur during production builds.

Our batch auditor treats mixed scalar and list representations as an explicit critical schema collision. Rather than silently coercing values, it documents both file cohorts and generates a clear normalization plan recommending array standardization.

3. Cross-Platform Casing Anomalies: The Silent Trap of Case-Insensitive Filesystems

Property key casing inconsistencies (e.g. status versus Status, or created_at versus createdAt) represent another pervasive class of vault defect.

The danger of casing drift is exacerbated by operating system differences:

Environment / ToolCasing BehaviorImpact on Note Frontmatter
macOS APFS / Windows NTFSCase-Insensitive, Case-PreservingFilesystem lookups succeed regardless of casing, giving authors a false sense of consistency.
Linux ext4 / Cloud CI/CDCase-SensitiveScripts and static generators searching for tags will completely overlook Tags.
YAML 1.2 SpecificationStrictly Case-Sensitivetags and Tags are parsed as two completely distinct, non-overlapping dictionary keys.
Obsidian PropertiesCase-Insensitive UI RegistryMaps keys into a single registered display label, masking underlying disk discrepancies.

Our batch auditor audits every note key across case-insensitive canonical groupings. If a property is recorded as status in 14 files and Status in 2 files, the tool isolates the anomaly and recommends normalizing to the dominant lowercase convention.

4. Type Drift: Booleans, Numbers, Dates, and Unresolved Placeholders

Beyond scalars versus lists, property keys frequently suffer from semantic type drift across note clusters:

  • Boolean vs String: published: true (boolean flag) versus published: "true" (string) versus published: yes (YAML 1.1 boolean keyword, which converts to string in YAML 1.2).
  • Priority Representations: priority: 1 (numerical order) versus priority: high (categorical text). Mixing numeric and string priorities breaks sorting algorithms in query views.
  • Date Variations: ISO 8601 strings (2026-10-13) versus localized human strings (Oct 13, 2026) versus Unix timestamps (1791936000).
  • Unresolved Placeholders: Notes cloned from templates often retain unresolved tokens like owner: <REQUIRED_UNRESOLVED> or reviewer: <UNRESOLVED>. Our auditor inventories these unpopulated properties separately from valid values.

5. Step-by-Step Vault Normalization Architecture

Normalizing an existing knowledge repository requires a systematic, risk-mitigated approach:

Step 1: Inventory & Coverage Analysis

Audit your notes to discover the long-tail distribution of property keys. Properties appearing in over 80% of notes represent your core schema; single-occurrence keys are candidates for consolidation.

Step 2: Resolve Mixed Scalar/List Collisions

Standardize multi-value fields (such as tags, authors, aliases) on array lists. Wrap existing scalar strings into single-element arrays to guarantee uniform parser handling.

Step 3: Unify Casing Conventions

Adopt a vault-wide naming standard. Lowercase snake_case (e.g. created_at) or kebab-case (e.g. review-date) offers the highest compatibility across command-line tools and web generators.

Step 4: Formalize Property Schema

Export the normalized findings into a formal JSON Schema or Obsidian types.json configuration. Check this definition into your vault to guide new note creation.

6. Privacy Architecture: 100% Client-Side Execution

Frontmatter properties contain sensitive operational and personal metadata: project budgets, confidential stakeholder names, private tags, and internal security classifications.

This tool guarantees absolute data sovereignty:

  • No Cloud Round-Trips: All multi-file parsing, lexical analysis, conflict classification, and report generation occur inside your browser JavaScript runtime.
  • Zero Telemetry: No analytical beacons, tracking scripts, or server requests inspect your note contents.
  • Offline Capable: The auditor functions perfectly when disconnected from the internet, allowing secure audits in air-gapped enterprise environments.

Questions

Why are mixed scalar and list properties considered a severe schema problem?

In personal knowledge management and automated publishing, mixed types cause silent query breakage. For example, if some notes define `tags: pkm` (a scalar string) while others define `tags: [pkm, audio]` (an array list), search queries, Dataview filters, and static site generators (like Astro, Hugo, or Eleventy) that expect an array will fail or drop single-tagged notes. Our auditor flags this as an explicit conflict rather than silently flattening records.

How does the auditor detect property casing conflicts?

Operating systems (like macOS APFS by default and Windows NTFS) are case-insensitive, while Linux and strict YAML parsers are case-sensitive. If your notes use `status: published` in some files, `Status: published` in others, or alternate between `created_at` and `createdAt`, tools treat them as distinct properties. Our engine groups keys by case-insensitive canonical names and highlights all spelling variants.

How do I input multiple notes from my Obsidian or Logseq vault?

You can paste notes directly into the workbench separated by `=== filename.md ===` or `--- filename.md ---` headers. Alternatively, when using the browser, you can drop multiple files into the text area or use our sample vault template to test your schema conventions.

What is the Cleanliness Score and how is it calculated?

The Cleanliness Score (0–100) measures how well your note collection adheres to a coherent property schema. Severe penalties (-25 points) are assigned to properties exhibiting mixed scalar and list collisions, moderate penalties (-15 points) for general type drift, and minor penalties (-10 points) for casing discrepancies and notes completely missing frontmatter.

Can I export the audit findings for team documentation or script automation?

Yes. You can export a comprehensive Markdown Audit Report suitable for checking into a team repository, or download a formula-safe CSV data dictionary listing all property keys, coverage rates, detected types, and recommended normalization actions.

Are any of my note contents or property keys uploaded to external servers?

No. The entire batch audit engine runs 100% locally in your client web browser memory. Zero files, metadata values, or diagnostic metrics are transmitted over the network.

Keep your notes structured, sovereign, and clean

Explore Oyma for fast, private local Markdown notes with built-in frontmatter governance and zero cloud lock-in.

frontmatter batch auditor downloadDownload for Mac

No account needed. Intel Mac build