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 and a Stream Deck profile, with web testers, keycap maps and assistant knowledge files on the roadmap.
Draft 0.2 — a bridge to LDML Keyboard: schemas, six example layouts, a validator, five one-way exporters with loss reports, an LDML importer
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. With the keyboard, press Tab to reach a key and Enter or Space to inspect it.
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.2 core. When a CapsLock level (5-8) has no output, the key shows the output of the matching level without CapsLock.
The manifest
A key, in a few lines
Canonical ISO/IEC 9995-1 position, a mandatory USB HID anchor, cross-references for Linux and the web, outputs by ISO level and optional tags. This is the Q-position key of the six-key example azerty-global-minimal.oklm.json. 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
Five export targets, one importer, honest reports
The exporters convert a manifest to Unicode LDML Keyboard, Linux XKB, macOS keylayout, a Windows .klc source or a Stream Deck profile. 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. A sixth tool goes the other way: it imports an LDML Keyboard file into an OKLM manifest.
$ python tools/export.py --target ldml layout.oklm.json
layout.ldml.xml
layout.ldml.xml.report.json # mapped · skipped · approximated
$ python tools/import_ldml.py keyboard.xml
keyboard.oklm.json
keyboard.import.report.jsonUnicode 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.
Windows .klc
A Microsoft Keyboard Layout Creator source. Checked by a parser in the repository, never compiled with MSKLC.
Stream Deck profile
An Elgato profile of Text buttons for the characters a layout types, a reminder for rare symbols. Not opened in the Stream Deck software.
LDML Keyboard → OKLM
Reads CLDR keyboard3 files. The round trip is measured on the six examples and three third-party CLDR keyboards.
Reference exports for the 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, and it does not compete with Unicode CLDR/LDML Keyboard: it is a source model and tooling layer that exports to it. Available today: the draft 0.2 manifest schema, a conversion-report schema (draft 0.2), six example layouts, a reference validator, one-way exporters to LDML Keyboard, XKB, macOS keylayout, Windows .klc and a Stream Deck profile — each with a loss report — and an LDML Keyboard importer. Progress is measured by four gates, not dates: the gap review against LDML 48.2, ISO/IEC 9995-1:2026, W3C KeyboardEvent.code and HID Usage Tables 1.7 is done (its known gaps are public), the checks run green on a clean machine, and the LDML → OKLM round trip is measured and passed (2026-10-05); independent use, by a project we did not write, is still open. First users: AZERTY Global and QWERTY Global, whose website will read its layout from the manifest next. Full order of work: ROADMAP.