# Data Driven QMK

This document explores how to make QMK more data driven.

## What does that mean?

As a general statement it means using data instead of code. There are a lot of things in QMK that use code where data might work better:

* Keycodes
* Songs
* `rules.mk`/`config.h`
* Keyboard Definitions
* Possible build configurations
* Default pins for backlight, indicators
* Physical matrix layout
* Possible add-on hardware (audio, screens, rgb strips)
* LED/RGB layout and configuration
* Keymaps
* Share keymap data between qmk_firmware, configurator, and via
* We can potentially allow for multiple keymap files, so users can more easily share portions of their keymap between disparate boards
* LAYOUT
* (This is technically covered in Keyboard Definitions but it's important enough to be called out on its own)
* Instead of a C macro use a simple dictionary with the following format:
* `{'label': {'row': int, 'col': int}, [...]}`
* `row` and `col` are the row and column for the switch location
* `label` is chosen from a list of pre-defined keys that map to a standard 104/105 key layout.
* The list of pre-defined keys should include provisions for keyboards that have unusual extra keys, like M1, M2, etc
* Explore using https://github.com/hid-io/layouts/ for this
* At compile time we will simply generate the raw keymap arrays, with KC_NO/KC_TRNS as the default keycode
* The selection of KC_NO/KC_TRNS might be a config option
* Custom Code
* The use of keymap.json will still require the ability to also use custom code. We should define a new file that custom code can be placed in.
* Userspace might be better for this

## Why are we doing this?

The number of places that need to interface with QMK is increasing. Configurator and VIA are two examples of applications that need to know about the internals of QMK. Currently when QMK is updated both of those systems need to be updated as well.

Pulling data out of code and putting it into well defined config files makes updating those apps much simpler. It also enables some things we think would be pretty neat:

* Easier sharing of keymaps between keyboards
* TUI and/or GUI keymap editing tools
* TUI and/or GUI keyboard creation/maintence tools
* Giving people who don't code a friendlier way to maintain keyboards and keymaps

## How do we get there?

Piece by piece.

For the foreseeable future we'll have to continue to support the current way things are done. Some pieces we can replace while others we'll have to provide an alterantive to.

The alternatives that we build will end up providing a top-down reimplementation of QMK that builds on the current C code, while the replacements will approach the problem from the bottom up. This should allow us to do most of the work without using the breaking changes process.

### Replace

These will all need to go through the breaking change process.

* Keycodes into serialized format
* `rules.mk`
* ARM i2c driver
* Songs
* RGB/LED Matrix Definitions

### Provide Alternatives

These can be merged piecemeal as they're completed.

* `keymap.c`
* `LAYOUT`
* Keyboard definition
* Custom code

### Not sure yet

* `config.h`

## Serialization Format

For a good balance between well-known formats and human friendly formats we have decided to use [Hjson](https://hjson.org/).