[XAP Prereq] External IDs need to be defined in `data/*.json`

XAP Task Info

Original Issue Original spec document Current XAP Definitions Current XAP Generated Docs Placeholder PR

Description

Any work in this area needs to be discussed with QMK Collaborators first, and in this case primarily with @fauxpark due to their prior work in this area.

As a prerequisite of the XAP work, we need to shift all externally-visible QMK IDs into *.json files under data/, or some other "versionable" location.

This currently includes:

• Keycode IDs
• RGB Effects IDs

These IDs need to be versioned in lock-step with the XAP protocol version, such that they effectively are defined by the protocol, even when not running a XAP-enabled firmware.

Ideally these IDs should not change, such that newer firmwares are compatible with older host apps that do not have the newer keycode definitions; the firmware will gracefully communicate with existing known IDs. However, in more drastic scenarios, this also allows for reordering at will; if we need to reallocate ranges in order to be able to "clean up", then newer firmware builds can do so by increasing the version accordingly. It will be up to the host app to be able to determine if it can cope, and disable the dynamic keymap subsystem if not.

These IDs should also have a corresponding compile-time validation header, much like quantum/via_ensure_keycode.h so that anyone attempting to add new keycodes triggers a failure and thus needs to discuss with collaborators whether a new version is required.

NOTE: no mapping tables are to be generated and included in the firmware -- available flash space is already scarce, so the intention here is to shift the complexity out of the firmware and into host apps.