One open source of truth per keyboard layout.
OKLM is a human-maintainable JSON model to describe, validate and export keyboard layouts — to Unicode LDML Keyboard, operating-system formats, web testers, keycap maps, dynamic key displays and assistant knowledge files.
Draft 0.1 — schemas, six example layouts, a validator and one-way exporters
Live demo
The format, demonstrating itself
This keyboard is rendered from the actual .oklm.json manifests published in the repository — nothing is drawn by hand. Pick a layout, toggle modifiers, click any key. Orange marks dead keys: click one to see its composition table.
Keycap convention: Shift output top-left, base bottom-left, AltGr bottom-right, Shift+AltGr top-right — letters show a single capital plus their AltGr extras. Greyed keys are frame keys, out of the draft 0.1 core.
The manifest
A key, in five lines
Canonical ISO/IEC 9995-1 position, a mandatory USB HID anchor, cross-references for Linux and the web, and outputs by ISO level. Readable, diffable, hand-correctable.
{
"id": "D01", "hid": "0x14", "xkb": "AD01", "code": "KeyQ",
"levels": { "1": "a", "2": "A" },
"categories": ["letter", "french"]
}Design principles
Complement the standards, don't compete
OKLM builds on ISO/IEC 9995 and Unicode CLDR/LDML Keyboard instead of reinventing them.
Human-maintainable
An .oklm.json manifest must be readable, correctable and versionable without a proprietary generator. Stable field order, explicit names, compact notation.
Standards-aligned
ISO/IEC 9995 key numbers and (group, level) terminology. The text core compiles to Unicode LDML Keyboard 3.0 rather than reinventing transforms and markers.
Validated
JSON Schemas for manifests and conversion reports, plus a CLI validator that also checks uniqueness and dead-key reference resolution.
Loss-aware conversions
Every OKLM ⇄ LDML conversion must produce a machine-readable report. Nothing is silently discarded, in either direction.
Architecture
Describe once, export everywhere
The manifest is the source model; standards and platforms are export targets.
Exporters
Three export targets, honest reports
The v1 exporters convert a manifest to Unicode LDML Keyboard, Linux XKB or macOS keylayout. Every export writes the target file plus a machine-readable conversion report — validated against its own JSON Schema — declaring exactly what was mapped, skipped or approximated. Nothing is silently discarded.
$ python tools/export.py --target ldml layout.oklm.json
layout.ldml.xml
layout.ldml.xml.report.json # mapped · skipped · approximatedUnicode LDML Keyboard 3.0
CLDR/UTS #35 Part 7 keyboard3 XML — the standards-oriented interchange export.
Linux xkb_symbols
A standalone xkb_symbols block covering ISO/IEC 9995 levels 1–4; the report states the scope limits.
macOS .keylayout
An Apple .keylayout file with dead keys mapped to terminator states.
Reference exports for all six example layouts are committed in examples/exports/ and covered by regression, determinism and schema tests.
Proof of concept
Six layouts already described
From the 29-dead-key AZERTY Global to the bare ANSI QWERTY baseline — including both options of the French standard NF Z71-300. Converted manifests are verified field-by-field against their source.
| Manifest | Layout | Keys / levels / dead keys | Layout license |
|---|---|---|---|
| azerty-global | AZERTY Global 2026 | 49 / 8 / 29 | EUPL-1.2 |
| azerty-afnor | AZERTY option of NF Z71-300:2019 | 49 / 8 / 22 | NOASSERTION |
| bepo | BÉPO (ergonomic option of NF Z71-300) | 49 / 8 / 21 | CC-BY-SA / GFDL |
| azerty-traditionnel | Legacy Windows French AZERTY | 49 / 5 / 4 | NOASSERTION |
| qwerty-us | US QWERTY (ANSI baseline) | 48 / 3 / 0 | CC0-1.0 |
| azerty-global-minimal | Six-key teaching subset | 6 / 2 / 2 | EUPL-1.2 |
Status
A public draft, in the open
OKLM is not yet a published standard. Available today: the draft 0.1 manifest schema, a conversion-report schema (draft 0.2), six example layouts, a reference validator and one-way exporters to LDML Keyboard, XKB and macOS keylayout — each with a loss report. Next: importers (LDML → OKLM) to close the round trip. Reference layouts: AZERTY Global and QWERTY Global.