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 and a validator
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.
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, six example layouts and a reference validator. Next: LDML Keyboard exporters and importers with loss reports. Reference layouts: AZERTY Global and QWERTY Global.