Collaboration diagram for Keymap formats:

Enumerations
enum	xkb_keymap_format { XKB_KEYMAP_FORMAT_TEXT_V1 = 1 , XKB_KEYMAP_FORMAT_TEXT_V2 = 2 }

Detailed Description

Keymap formats for parsing and serializing keymaps.

Enumeration Type Documentation

The possible keymap formats.

See The XKB keymap text format, V1 and V2 for the complete description of the formats and Keymap support for detailed differences between the formats.

Remarks: A keymap can be parsed in one format and serialized in another, thanks to automatic fallback mechanisms.

Keymap format to use depending on the target protocol
Protocol		libxkbcommon keymap format
Name	Keymap format	Parsing	Serialization
X11	XKB	XKB_KEYMAP_FORMAT_TEXT_V1	Always use XKB_KEYMAP_FORMAT_TEXT_V1, since the other formats are incompatible.
Wayland	`xkb_v1`	Wayland compositors The format depends on the keyboard layout database (usually xkeyboard-config). Note that since v2 is a superset of v1, compositors are encouraged to use XKB_KEYMAP_FORMAT_TEXT_V2 whenever possible. Client apps Clients should use XKB_KEYMAP_FORMAT_TEXT_V1 to parse the keymap sent by a Wayland compositor, at least until XKB_KEYMAP_FORMAT_TEXT_V2 stabilizes.	At the time of writing (July 2025), the Wayland `xkb_v1` keymap format is only defined as “libxkbcommon compatible”. In theory it enables flexibility, but the set of supported features varies depending on the libxkbcommon version and libxkbcommon keymap format used. Unfortunately there is currently no Wayland API for keymap format negotiation. Therefore the recommended serialization format is XKB_KEYMAP_FORMAT_TEXT_V1, in order to ensure maximum compatibility for interchange. Serializing using XKB_KEYMAP_FORMAT_TEXT_V2 should be considered experimental, as some clients may fail to parse the resulting string.

Enumerator

XKB_KEYMAP_FORMAT_TEXT_V1

The classic XKB text format, as generated by xkbcomp -xkb.

Important: This format should always be used when serializing a keymap for X11.; For the Wayland xkb_v1 format, it is advised to use this format as well for serializing, in order to ensure maximum compatibility for interchange.

Note: In case serializing a keymap with more than 4 layouts, use xkb_keymap::xkb_keymap_serialize() and select the layouts to serialize using xkb_keymap_serialize_config::layouts.

XKB_KEYMAP_FORMAT_TEXT_V2

Xkbcommon extensions of the classic XKB text format, incompatible with X11.

Important: Do not use when serializing a keymap for X11 (incompatible).; Considered experimental when serializing for Wayland: at the time of writing (July 2025), there is only one XKB keymap format xkb_v1 in Wayland and no Wayland API for keymap format negotiation, so the clients may not be able to parse the keymap if it uses v2-specific features. Therefore a compositor may parse keymaps using XKB_KEYMAP_FORMAT_TEXT_V2 but it should serialize them using XKB_KEYMAP_FORMAT_TEXT_V1 and rely on the automatic fallback mechanisms.