Metadata & Naming Conventions
Relevant source files
The following files were used as context for generating this wiki page:
The Metadata and Naming Conventions in IDAHO-VAULT establish a strict contract for how information is structured, identified, and categorized within the journalism research vault. The primary goals are to improve machine readability for AI agents, ensure durable human-readable records, and eliminate ambiguity in document routing and maintenance. This system outranks implementation tooling and template guidance in cases of conflict to maintain a canonical authority over governed markdown notes.
Sources: VAULT-METADATA-STANDARD.md:14-25, VAULT-TEMPLATES.md:11-13, VAULT-CONVENTIONS.from-pushable-2026-05-08.md:65-71
1. Metadata Standards
Every governed note in the vault must begin with YAML frontmatter fenced by --- lines. This metadata is structural and stable, designed to be queried and sorted by automated scripts and AI agents.
1.1 Required Header Fields
All documents must include a baseline set of required fields to ensure lifecycle tracking and authority.
| Field | Type | Description |
|---|---|---|
title | string | The exact document title in plain text. |
updated | date | Last substantive edit date in YYYY-MM-DD format. |
status | enum | Lifecycle state: draft, active, superseded, or archived. |
authority | string | The final decision authority for the document (defaults to LOGAN). |
Sources: VAULT-METADATA-STANDARD.md:28-50, VAULT-CONVENTIONS.from-pushable-2026-05-08.md:147-156
1.2 Footer Section
Governance documents must include a ## DOCUMENT METADATA section at the end of the file. This mirrors key lifecycle fields for human readers scanning in rendered view and provides redundancy for legacy files lacking YAML.
- Required Footer Fields: Created, Last Updated, Status, Authority.
- Optional Footer Fields: Authors, Change Note, Supersedes/Superseded By.
Sources: VAULT-METADATA-STANDARD.md:73-86
1.3 Metadata Lifecycle Flow
The following diagram illustrates how a document's status evolves through its lifecycle according to the metadata standard.
The standard mandates that when a file is superseded, the superseded_by field must be populated, and the new doc must include supersedes to preserve the historical chain.
Sources: VAULT-METADATA-STANDARD.md:100-111
2. Document Class & Template System
Documents are categorized into specific classes, each with deterministic naming patterns and required metadata keys.
2.1 Document Class Registry
| Class | Purpose | Filename Pattern | Required Keys |
|---|---|---|---|
news_media | Media stories/excerpts | YYYY-MM-DD - Outlet - Title.md | author, outlet, url, published |
hearing_note | Meeting/committee notes | YYYY-MM-DD - Committee.md | cmte, meeting_date, location |
bill | Legislative bill tracking | (YYYY) Bill Type Number.md | bill_number, session_year, bill_type |
person | Public figure profile | Full Name.md | role, affiliation, residence |
organization | Entity profile | Organization Name.md | org_type, jurisdiction, url |
Sources: VAULT-TEMPLATES.md:15-32, VAULT-TEMPLATES.md:59-71
2.2 Template Structure Hierarchy
Standardized templates follow a specific logical order to ensure consistency across the journalism corpus.
Sources: VAULT-TEMPLATES.md:50-57
3. Naming Conventions
Naming rules are deterministic and class-bound. General rules include:
- Case: Use title case for entity names.
- Punctuation: Preserve legal punctuation (hyphens, apostrophes).
- Dates: Use ISO
YYYY-MM-DDfor date-leading files. - Uniqueness: Do not append ad-hoc suffixes like
(2). Duplication is resolved by merging or redirecting.
Sources: VAULT-TEMPLATES.md:73-82, VAULT-CONVENTIONS.from-pushable-2026-05-08.md:129-141
4. Tagging Schema
The vault utilizes a hierarchical, path-based tagging system (kebab-case) to facilitate machine readability.
4.1 Proposed Namespace Structure
| Namespace | Example Tag | Use Case |
|---|---|---|
/agent/... | agent/gemini/report | Artifacts generated by specific AI agents. |
/doctrine/... | doctrine/constitution | Governance and protocol documentation. |
/source/... | source/article/outlet | Notes derived from external media/sources. |
/status/... | status/awaiting-architect | Granular initiative tracking. |
Sources: PROPOSAL-NEW-ORDER-TAG-SCHEMA-2026-04-13.md:21-45, VAULT-CONVENTIONS.from-pushable-2026-05-08.md:162-166
5. Workflow and Evolution
Information evolves in place through metadata transformations rather than physical folder movement. The system operates on a unit-based transformation model.
Sources: IDAHO-VAULT — WORKFLOW.md:20-80
6. Audit and Compliance Findings
A metadata survey conducted in April 2026 revealed significant schema fragmentation. While daily_notes show high compliance (35/36 valid), the broader corpus exhibits "partial adoption" and "mixed eras."
Current Drift Metrics:
- Total Files: 32,084
- Valid Frontmatter: 11,542
- Malformed Frontmatter: 905
- Missing
updatedfield (in valid docs): 11,412
Recommendations for technical hygiene include normalizing status and authority dialects and retrofitting doc_class fields only on active, high-signal document families.
Sources: !/REPORT-METADATA-FRONTMATTER-FINDINGS-2026-04-18.md:26-53, !/REPORT-METADATA-FRONTMATTER-FINDINGS-2026-04-18.md:126-145
These conventions ensure that IDAHO-VAULT remains a scalable and queryable knowledge base where the distinction between human narrative (prose) and machine-readable state (metadata) is clearly maintained.