Draft a standard format for keyboard layout JSON files

[jordiorlando]

I'm writing my own keyboard design website, and it would be great if it could be compatible with KLE. A standardized keyboard layout format could potentially be very useful for the community.

[ijprest]

See also #21. I have been documenting the format on the wiki, but not rigorously. I've only recently become aware of 3rd-party sites trying to interact with KLE (e.g., Ortholinear Keyboards and Swill's Plate Builder), so maybe a more formal spec is a good idea.

[jordiorlando]

Honestly, the spec seems fairly complete, with exception of support for key groups. E.g. it might be nice to be able to group keys and perform operations on the groups. That said, my website explicitly separates layouts from keysets from firmware, so I'll have to write a converter anyway.

[HughP]

Just as an aside (because I like JSON over XML too) are you all aware of the work done in the Unicode Locale data set for keyboard layouts? http://unicode.org/reports/tr35/

[iandoug]

Interesting. The meat is here: http://unicode.org/reports/tr35/tr35-keyboards.html#Keyboards But I find it odd that they base everything off where it WOULD be in an ISO qwerty layout... particularly since the bleeding edge is moving away from that design rather quickly. There must be a saner way :-)

[ijprest]

I did look at that briefly when @HughP first mentioned it... I got the sense they were talking "keyboard layouts" in the Unix sense (i.e., a mapping of hardware scan-code to a Unicode code-point), rather than the physical layout that we're primarily interested in.

[dragon788]

@ijprest Wouldn't the keymappings/scancodes be rather interesting as well, so that users could "save" their layout and flash it to their keyboard a la the Massdrop keyboard configurator or the Input.Club keyboard configurator? It sounds like @D1SC0tech is doing something similar utilizing the layout data.

If that's beyond the scope of what you want to do, perhaps we should make the guys writing the configurators aware of how awesome your layout software is so they can focus on importing what you've got and they can just handle the scancode logic.

[iandoug]

@dragon788 FWIW, one item on my to-do list is to generate the keyboard config file for Linux, I guess the Mac should be able to use something similar (or at least just a small step further), while doing it for Windows will be a different ball game altogether (for me, at least... maybe IJP will find it a piece of cake... :-) )

[notionparallax]

I know that as a living spec this has been out in the wild for a while now but I thought I'd suggest something just in case you don't think it's a dumb idea.

If, instead of making the spec super terse (e.g. a newline delimited string) each key would be an object that has properties of its own, and up to 12 children. E.g.:

So instead of:

  {
    r:0,
    y:0,
    x:1,
    c:"#ff0000",
    p:"DCS R1",
    a:0,
    w:1,
    h:1
  },
  "l1\nl7\nl3\nl9\nl10\nl12\nl4\nl6\nl2\nl5\nl8\nl11"

Which is wonderfully terse, but a bit hard to parse. Maybe it could be more like:

{
  r:0,
  y:0,
  x:1,
  c:"#ff0000",
  p:"DCS R1",
  a:0,
  w:1,
  h:1,
  functions:[
    {
      Position:0,
      label:"L1",
      size:3,
      colour:black,
      command:VolU
      layer:0,
      macro:"MACRO( I(255), T(C), T(7), T(X), T(T), T(E), T(R), T(M), T(X), T(SPC), T(MINS), T(N), END  )"
    },
    {
      Position:1,
      label:"L2",
      size:3,
      colour:red,
      command:VolD
      layer:1,
      macro:"MACRO( I(255), T(P), T(I), T(G), T(L), T(E), T(T), END  )"
    },...
  ]
}

Which is way more of a pain to read, but it allows for people to be more specific, and take away a lot of the inferring that people who are consuming that JSON need to do.

I'm sure I've missed a bunch of subtleties, but this sort of thing fits how my brain works a bit better. I guess it'd have to be an additional output so as to not upset anyone who currently relies on the existing output style.