Database fields brainstorming

[precondition]

Here are the possible fields that we can use to describe each keymap in the database. This is still in brainstorming phase so there are potentially some not-so-good ideas that we will weed out later.

From most important to least (roughly):

field name	data type	possible values	description	notes
url	string	"https://github.com/qmk/qmk_firmware/tree/master/keyboards/minidox/keymaps/dustypomerleau" "https://github.com/alvaro-prieto/corne"	The link to the keymap files
author	string	"dustypomerleau" "alvaro-prieto"	The name of the keymap's author	Prefer GitHub username when many aliases are possible
image	string	"https://media.discordapp.net/attachments/663573863480950808/876552871309639780/unknown.png" "https://i.ibb.co/RQZx2dY/default-kyria2.jpg"	Path to a visual representation of the keymap in question	Should we host images in the repo or use URLs? If we plan to make a "cards"-view of the different keymaps in one page, "exploded" keymap pictures such as this and this won't work well so that limits us to "concatenated" views where it's very hard to visualize anything beyond 4 layers — it already gets crowded with legends in the four corners of the key.
keyCount	integer	1 (min) 36 102 255	The amount of physical keys required for the keymap	In case a keymap can be applied to multiple different keyboards with varying amount of physical keys, pick the minimum amount of keys required; no ranges.
firmware	categorical	"QMK" "ZMK" "Kaleidoscope" "KMonad"	The keyboard firmware the keymap is made for.	KMonad is not really a keyboard firmware but it gets pretty close to one.
baseLayout	array[categorical]	["Colemak", "QWERTY"] ["AZERTY"] ["BEAKL"]	An array of all the base alpha layouts that the keymap offers	IMPORTANT: Only layout families are accepted. US QWERTY, ES QWERTY, and UK QWERTY all fall under the same family of "QWERTY" for example. Same thing for Vanilla Colemak, Colemak-DH, Colemaq etc. which are all variations of the Colemak family (Workman is its own family). Notably, QWERTZ and AZERTY are separate from QWERTY. It's not rare to come across a keymap that has multiple base layouts hence the use of an array for the data type. However, if the main base layer of a keymap is Dvorak and it implements a QWERTY gaming layer, that doesn't mean QWERTY gets added to the array. Especially so, if it shifts QWERTY to the right to make WASD more comfortable on columnar stagger boards.
keyboard	categorical	"crkbd" "Kyria" "UHK" "Dactyl Manuform 5x6"	The particular keyboard for which the keymap is designed	Many people port the same keymap to a variety of different keyboards, should we use an array[categorical] instead? For example, Miryoku works on atreus, ergotravel, for_science, gergo, handwired/dactyl_manuform/4x5, handwired/dactyl_manuform/5x6, keebio/iris, keyboardio/atreus, kyria, lily58, moonlander, redox_w, sofle, torn, ...
stagger	categorical	"row" "columnar" "ortholinear" "depth"	The keyboard stagger for which the keymap is designed around. The effort grid can change from one stagger to another and so will an optimized keymap.	The unconventional "depth" stagger is my invention for 3D keyboards such as the Dactyl Manuform, it is up for debate whether separating it from columnar stagger is useful or not; suggestions welcome. Often, people group ortholinear and columnar stagger together, should we do the same?
split	bool	True False	Whether the keyboard is split or not. One-piece splits such as Atreus are considered to be split.	The criteria is whether there is a space between the two main halves. Two-piece splits like the Kyria obviously fit and so do one-piece splits like the Polilla and, since the focus is on keymaps, a keymap that puts something like a numpad between the two main halves of the alpha block also counts (example XD75). The wide mod for row stagger boards also counts as split but the angle mod doesn't.
languages	array[categorical]	["English", "French"] ["Japanese", "English"] ["ru", "en", "gr"]	The (natural) languages this keymap is designed to be used in. The first language in the array is the main language.	Don't associate a region to the language e.g. don't use "English US" and "English UK" or "French FR" and "French BE", use just "English" and just "French". It remains to be seen whether we use the full name ("Greek") or the abbreviation ("gr").
summary	string	"Keymap for Corne Keyboard specially designed for software developers using macOS and Windows and writing in Spanish and English." "OS independent shortcuts, custom modifier keys, RGB themes, key sequences, and much more." "A combo-based layout for Ergonomic Keyboards, implemented in QMK"	Short summary of the keymap to show in the card, below the picture.	Ideally, the author himself/herself writes the summary. The summary should be short.
OS	array[categorical]	["Windows"] ["MacOS", "Windows"] ["Linux"]	The operating system(s) used by the keymap author.	Different OSes have different modifier conventions and different keyboard shortcuts. I've considered adding a new category for TWM users so something like "Linux" vs "Linux TWM" since the usage of a tiling window manager brings its own set of constraints to the keymap and window management is closely related to the OS. (Should we say "GNU/Linux" instead?)
writeup	string	"https://github.com/skychil/kombol/blob/main/README.md" "http://thedarnedestthing.com/thumb%20h"	URL to the detailed write-up of the keymap which explains the rationale behind the design choices. It can be a README or a blog post.	Leave empty ("") if no writeups exist.
softwareLayout	categorical	"English (US intl., with AltGr dead keys)" "Russian (phonetic)"	The name of the software layout used in the Regional input settings of the OS.	A hardware layout is not independant of the software layout. The same keyboard firmware/keymap won't act the same if the OS layout is set to UK QWERTY, US Simplified Dvorak or Russian ЙЦУКЕН. Although an incredible majority of QMK users switch to US intl. or EURkey once they get their QMK keyboard so this might not be so important. It will also require having a giant pre-made list of possible software layouts but we can grab that off the open-source XKB project for Linux.
hasLetterOnThumb	bool	True False	Does the keymap use one or more letters on the thumb keys of the base layer	That info can probably be inferred from the baseLayout field so it's most likely redundant.
layerCount	integer	1 (min) 8 32 (max)	The amount of layers in the keymap.	Ideally, we would ignore the multiple base layers.
imageDate	string	"2021-08-26"	The (approximate) date at which the image was created.	Users' keymaps often change and thus images can be out of date if we don't pay attention. If we detect that a commit was pushed after the creation date that touched the keymap files, we can put a warning on the site saying that the image may be out of date.
isComboEnabled	bool	True False	Whether combos are enabled and used in the keymap. Look for COMBO_ENABLE in the rules.mk file in case of a QMK firmware keymap. Search for the equivalent if the firmware is different.	Some people may be interested to look at combo-heavy keymaps like the Kombol layout.
isTapDanceEnabled	bool	True False	TAP_DANCE_ENABLE
isAutoShiftEnabled	bool	True False	AUTO_SHIFT_ENABLE
isLeaderKeyEnabled	bool	True False	LEADER_ENABLE
hasOuterPinkyColumns	bool	True False	The field name speaks for itself.	Can possibly be inferred from the keyCount field so not entirely necessary.
hasExtraIndexColumns	bool	True False	Is the keymap designed for split keyboards with an extra inner index column like the Ergodox?
hasVerticalCombos	bool	True False	Does the keymap contain combos that require the simultaneous chording of two vertically adjacent keys?	Vertical combos require a special kind of keycap profile to be comfortable; if a person has such keycaps, he may be interested in how he can take advantage of it. This will be annoying to figure out automatically by parsing a keymap though.
hasHomeRowMods	bool	True False	Does the keymap contain mod-taps on the home row keys of the base layer?	I've seen people wanting to see the keymap of home row mods users to see what are their tap hold settings and overall setup. I also saw people who have had a bad experience with home row mods and wish to filter out keymaps which employ them.

[mathias]

This is excellent, thank you! It also solidifies some of the stuff that I was just making up like key_range: [36, “+”] — technically true but I think folks will understand that it could run on more physical keys but doesn’t map them. I wasn’t sure if we’d encounter a key map with an actual range like 36-42, and wanted to be able to search on that range matching. As just one example.

Going to start moving this to the code, which tbh needs a little work to better define the columns. Then I’m planning to make a data validator script so that changes don’t break the site.

[mathias]

I am realizing that a Google Docs Spreadsheet might contain all the searching and sorting logic we might want (instead of building a site) but could we start collecting key maps in a GDocs spreadsheet and invite others to it? It’ll be easier than me trying to fill it in manually myself on my free time — then I can focus on the site JS

[ghost]

I'd add a way to define combos and also leaders.

Something like that

{
  "combos": [
     {
       "keys": ["a", "b"],
       "action": "close private browser windows"
     }
  ]
}

[precondition]

@graseggergh We're just collecting links to people's keymaps, we don't really care what specific action do their combos make, that is all explained in detail in their keymap files to which we plan to link.

[mathias]

@precondition I'll release what I've got now for the published site, and then begin implementing your suggested columns today + this weekend.

[mathias]

@precondition How do you feel about changing "keyboard" to be an array[categorical] (to use your wording) with a special value of "Many" for things like Miryoku?

[precondition]

How do you feel about changing "keyboard" to be an array[categorical] (to use your wording) with a special value of "Many" for things like Miryoku?

@mathias In the majority of cases, the keymap link will be something along the lines of https://github.com/user/qmk_firmware/blablabla/keyboards/name_of_keyboard/keymaps/user/keymap.c which means that the keymap is tightly tied to name_of_keyboard. Miryoku is really quite exceptional in the way it is setup and shouldn't be regarded as the archetypal keymap folder. Consequently, the keyboard field/column should just be a categorical and probably include a "Many" category for keymaps which are programmed to be easily applied to many different boards.

[mathias]

That works for me. Seniply also supports many keyboards so I listed out a few that we’d care about (kept the staggered row keyboards out of the list) but that is also a candidate for “Many”

[precondition]

The good thing is that we also have "keyCount", "split" and "stagger" fields so we don't really need more precision than "Many" for the "keyboard" field. keyboard="Many" + stagger="row" + split="no" + keyCount=61 already gives a good idea of what those many keyboards can be :)

[precondition]

Closing in favour of https://github.com/precondition/keymapdb/blob/main/db_fields_reference.md