Document Frontmatter Schema

This is the metadata contract for every document on the Rx360 internal docs site. It powers the site navigation + facets, the document knowledge graph (nodes = docs, edges = relationships), the Obsidian bases control panel, and — most importantly — the sensitivity gating that keeps Tier‑1 content off the site.

It deliberately reuses the vocabulary already defined in the Curated Drug KB & Tagging Schema: that schema tags clinical facts; this one tags documents. Shared tokens (status, clinical_line, provenance fields) mean the same thing in both.

---

Field reference

Field	Required	Type / allowed values	Purpose
id	✔	stable kebab/snake slug	The KG node id and the target of every related/supersedes edge. Never changes across versions of the same doc.
title	✔	string	Human title shown in nav, search, and graph.
area	✔	fall_barometer · wearable_vesta · med_intelligence · smart_scheduling · pilot_ops · market_strategy · reference	Top‑level workstream = nav section + graph color. One per doc.
doc_type	✔	spec · brief · research · deck · tool · template · protocol · index · digest · guide	What kind of artifact it is.
status	✔	preliminary · validated · draft · locked · superseded	Lifecycle. preliminary/validated carry the drug‑schema meaning (pharmacist sign‑off gate); locked = frozen by decision (e.g. Vesta); superseded = an old version (normally excluded from the allow‑list).
owner	✔	string (name)	Who owns the doc (= drug‑schema author).
approver	–	string | null	Sign‑off authority (= drug‑schema approver); null until signed off.
version	–	semver‑ish string	Document version.
effective_date	–	YYYY-MM-DD	The doc's own date (often in its filename).
last_updated	✔	YYYY-MM-DD	Last edit to the canonical file. Drives the "what changed recently" list.
sensitivity_tier	✔	never-share · internal-only · after-scrub · share-ready	The gate. never-share is illegal in the manifest — the build rejects it. internal-only is the site default (core team). after-scrub must pass the scrub gate clean before it is published.
contains_trade_secret	✔	bool	Explicit flag for Fall Barometer scoring internals (weights/caps/calibration). Renders a badge.
clinical_line	✔	bool	Reused verbatim from the drug schema: true = the doc is itself a clinical‑advice surface; handle accordingly.
canonical	✔	bool	Is this the current version of id? The allow‑list gate — only canonical: true ships.
supersedes	–	list of id	Ids this doc replaces (dashed graph edges = version lineage).
superseded_by	–	id | null	Set when a newer doc takes over.
related	–	list of id	KG edges — other docs this one relates to (solid graph edges).
tags	–	list of string	Facet/cluster vocabulary. Borrows drug‑schema flags where apt (frid, nti, high-risk, trade-secret) + site tags (site-canonical, scoring, wearable, …). Every site doc carries site-canonical.
source_path	✔	repo‑relative path	The canonical file (single source of truth).
has_docx	–	bool	A paired .docx exists (the "paired but not synced" norm).

---

Sensitivity tiers (the gate)

Tier	On the site?	Examples
never-share	Never. Illegal in the manifest; build aborts if such a path/term is detected.	Patent disclosures, raw de‑identified data (08_Data_DeIdentified/), .env secrets, anchor‑site shorthand / partner naming.
internal-only	✔ Yes — this is the site default (audience = core team).	Fall Barometer scoring internals, internal product/strategy specs.
after-scrub	Only once it passes the scrub gate clean; otherwise held out of the build and reported.	Pilot deliverables containing anchor-site naming, decks with internal callouts.
share-ready	✔ Yes (and safe even beyond the core team).	Public market research, FDA guidance summaries, the Wellness Lexicon.

The build enforces three independent fail‑closed gates: (1) deny‑rooted directories are rejected at manifest‑validate time, (2) never-share is illegal in the manifest, (3) the scrub gate scans every staged file for anchor‑site / secret / PHI patterns. An after-scrub doc that still contains a forbidden term is excluded from the build and reported (so the source gets fixed once) — it never reaches HTML, but it also doesn't block the rest of the site. A forbidden term in a doc that is not after-scrub is treated as an unexpected leak and hard‑fails the whole build.

---

Worked example — the Balance Meter canonical model

---
id: balance_meter_canonical
title: "Balance Meter — Canonical Model"
area: fall_barometer
doc_type: spec
status: validated
owner: "Gene Lang, PharmD"
approver: "Matilda (clinical)"
version: "1.0"
effective_date: 2026-05-20
last_updated: 2026-06-17
sensitivity_tier: internal-only
contains_trade_secret: true
clinical_line: false
canonical: true
supersedes: [balance_meter_model_reference]
related: [balance_meter_explainer_deck, fall_risk_algorithm_sandbox,
          fall_prediction_intake_spec, curated_drug_kb_tagging_schema]
tags: [trade-secret, scoring, frid, wearable, site-canonical]
source_path: _VP_Priorities/Fall_Risk/Balance_Meter_Canonical_Model_2026-05-20.md
has_docx: true
---

How metadata gets applied

Source files have no frontmatter today. The build pipeline injects it from the 09_Scripts/site_manifest.yml allow‑list at stage time, onto an ephemeral copy — the canonical file is never mutated. If/when frontmatter is later written into the canonical files directly (editable in Obsidian's properties panel, not raw YAML), the manifest's frontmatter: block becomes an optional supplement. Either way there is exactly one editable copy of each doc, so nothing drifts.