Glossdown

An open, human-writable format for pronunciation / term correction glossaries, distributed as .gloss.md files.

A Glossdown file is plain Markdown — YAML frontmatter for metadata plus a Markdown table of entries.

English:

---
glossdown: "1.0"
name: Engineering terms
locale: en
license: CC-BY-4.0
---

| term | aliases |
|---|---|
| Kubernetes | k8s, kube, coobernetties |
| Anthropic | anthropic, and tropic |
| Worcestershire | woost-er-sher, worcester |

Japanese:

---
glossdown: "1.0"
name: 医療用語（循環器）
locale: ja
license: CC-BY-4.0
---

| term | aliases |
|---|---|
| 心房細動 | しんぼうさいどう, AF, Afib, エーエフ |
| アブレーション | あぶれーしょん, ablation |

• term — the canonical surface form (the output). Always present.
• aliases — a comma-separated, ordered list of keys that should resolve to term. The first entry is the primary key (treated as the preferred match and the sort key); the rest are equal.
  • Japanese: put the reading (kana) first — the surface is kanji, so the reading can't be derived reliably for proper nouns (江島 → the engine guesses えしま, missing えじま), and kana is the natural sort order.
  • English: the phonetic key is derived from the spelling via double-metaphone, so you usually don't write a reading — aliases is just misrecognitions/acronyms (e.g. ASR hears "and tropic" → corrected to "Anthropic"), and entries sort by term. Add a sounds-like first entry only for irregular words (Worcestershire, Siobhan).
  • The comma is the separator, so it never appears inside an alias; other punctuation is fine (.NET, C++, node.js).

Frontmatter: glossdown (format version, quoted) and name are required. locale is optional — a label for single-language packs; matching routes per entry by script (kana/kanji vs Latin), so one file can freely mix languages (e.g. a personal glossary with both Japanese names and English jargon).

Output-side, not input-side

Unlike classic pronunciation lexicons (W3C PLS, ASR custom vocabularies) that tell a speech engine how to pronounce or bias toward words, Glossdown is an output-side correction glossary: its phonetic keys are used to match an ASR engine's already-emitted (and possibly wrong) text back to a canonical term. The engine never consumes the glossary, so it works even with on-device engines that expose no vocabulary-biasing API.

Status

The name is reserved. The specification and a reference parser/validator are in progress at https://glossdown.org.

License

MIT (this package). Glossdown files themselves carry their own license field in frontmatter.