Proposal: Switch from JSON to YAML for Config Files

[galligan]

Update from @mikker:

This is a great suggestion. If anyone is up for it: We should look for .json, if it doesn't exist look for .yaml or .yml. If they don't exists either, create default json like now.

JSON and Yaml should have same schema and resolve to the same in-memory object(s).

---

Hey there @mikker! 👋 First off, loving Leader Key. I was hacking something like it together by way of AeroSpace binding modes, but this is way more purpose-built and slick. I wanted to suggest something that could make the config experience even better: switching from JSON to YAML for configuration files.

Why YAML? 🤔

JSON works fine, but YAML (which is a superset of JSON) really shines when it comes to human readability while maintaining all the machine-readable benefits. It's also a lot more concise, which could help if loading up configs into AI tools for help (fewer tokens used).

Plus, it's battle tested: a bunch of projects like Home Assistant, Docker, and others use YAML for their configs.

Here's a quick comparison using a snippet from a Leader Key config in JSON and the same in YAML:

JSON (Current)

• 748 characters
• 38 lines

{
  "type": "group",
  "actions": [
    {
      "type": "group",
      "label": "Open",
      "key": "o",
      "actions": [
        {
          "key": "m",
          "label": "Music",
          "type": "group",
          "actions": [
            {
              "type": "application",
              "value": "/Applications/Spotify.app",
              "label": "",
              "key": "s"
            }
          ]
        },
        {
          "key": "b",
          "label": "Browser",
          "type": "group",
          "actions": [
            {
              "type": "application",
              "value": "/Applications/Safari.app",
              "label": "",
              "key": "s"
            }
          ]
        }
      ]
    }
  ]
}

YAML (Proposed)

• 411 characters (near 2:1 reduction)
• 22 lines

type: group
actions:
  - key: o
    type: group
    label: Open
    actions:
      - key: m
        type: group
        label: Music
        actions:
          - key: s
            type: application
            value: /Applications/Spotify.app
      - key: b
        type: group
        label: Browser
        actions:
          - key: s
            type: application
            value: /Applications/Safari.app

Benefits 🌟

1. Cleaner Visual Hierarchy

   • YAML uses indentation to show structure, making it super easy to scan and understand the config at a glance
   • No more hunting for matching braces or commas!
   • Hyphens denote new list items, making it easier to see the structure of the config

2. Massive Character Reduction

   • Removes unnecessary quotes, braces, and commas
   • Early testing shows about a 2:1 reduction in file size (great for sharing configs or using with AI tools!)
   • Less typing = fewer chances for syntax errors

3. Built-in Comments

   type: group
   actions:
     # Quick access to music apps
     - type: group
       label: Music
       key: m

4. Simpler Special Character Handling

   # In JSON:
   { "key": "\\", "type": "application" }
   
   # In YAML:
   key: \\ # Backslash with simple comment
   type: application

Implementation Notes 🛠

• YAML is a superset of JSON, so migration would be straightforward
• Most programming languages have mature YAML parsers
  • Consider using Yams for a Swift YAML parser.
• Could maintain backward compatibility by supporting both formats initially

What do you think? Would love to hear your thoughts on this!

tl;dr

YAML would make configs more readable, reduce file size by ~50%, and add useful features like comments while maintaining all the functionality we have now. It's a win-win! 🎉

[mikker]

I agree. I regret using JSON.

[mikker]

In my defense, I was bullied into it 😅

https://x.com/mikker/status/1781708924732805602

[zenangst]

Is there a YAML parser that works well with the built-in JSON decoder in Swift?

I also went for JSON in my app, but I'm not sure if I'm totally regretting it.

Edit:

https://github.com/jpsim/Yams looks interesting :)

[galligan]

In my defense, I was bullied into it 😅

@mikker that's tragic! I can only suspect these people are gluttons for punishment, or simply aren't familiar with YAML.

@zenangst As I was poking around, it did seem like Yams was the parser of choice. Could be good to investigate for this!

[susl]

+1 for TOML
I find to be the easiest to parse with my eyes and the easiest one to edit quickly.

[miiraheart]

+1 for YAML !

[martinengelke]

I also like toml a lot for small config files, but:

https://hitchdev.com/strictyaml/why-not/toml/

On the other hand I also do not like indentation based languages, even if they have there benefits I may a bit old school but often find me in a situation with no good Text editor showing me tabs and stuff.

[mikker]

What would a toml config look like?

[martinengelke]

nvmd, as I tried to explain TOML isn't useful for complex nested arrays, explained here: https://news.ycombinator.com/item?id=26682876
I like it for easy config files with less hierarchy
You should go with YAML, maybe StrictYAML (link above)

[saml-dev]

I disagree. I really dislike writing YAML. I'm a heavy home assistant user and I groan every time I have to open up my config. I think it's a poor choice for anything complex because indentation matters, which just gets annoying with long configs. The app already has a UI, that's the human-friendly version.

[martinengelke]

I prefer {} as well, but maybe I'm a bit old school :x

[jsvensson]

This is a long shot since the work is a bit more involved (you'll need to write your own mapper functions), but I'm a very big fan of HCL for configuration files intended to be both readable and writable by a squishy human.

An imagined example I pulled out of my posterior:

group "Browsers" {
  key = "b"

  actions {
    application {
      name = "Google Chrome"
      key  = "c"
      path = "/Applications/Google Chrome.app"
    }

    application {
      name = "Safari"
      key  = "s"
      path = "/Applications/Google Chrome.app"
    }

    # subgroup for the heck of it
    group "Firefox-based browsers" {
      key = "f"

      actions {
        application {
          name = "Firefox"
          key  = "f"
          path = "/Applications/Firefox.app"
        }

        application {
          name = "Zen Browser"
          key  = "z"
          path = "/Applications/Zen Browser.app"
        }
      }
    }
  }
}

application "1Password" {
  key = "p"
  path = "/Applications/1Password.app"
}

It can also easily be translated straight back to JSON, though again it needs a mapper function if you want a different structure for the JSON.

[CanRau]

I think for json it should always support jsonc or json5 both of which support comments.

If not too much trouble maybe it could support .json(c) & .yaml 💁‍♂

Although I'm totally fine if it'd completely switch over to yaml only, tho then it'd be nice if the app could auto migrate the file for me 😇