We have all been there. Your software keeps growing and you feel the need to make it customizable. It is too soon for a full-blown UI with all the bells and whistles, so your pragmatic instinct suggests a text-based configuration file. Yes, that’s exactly it!

You rejoice knowing the software’s configuration will be trivial to version control. Your pragmatic instinct is satisfied as well; the door remains open to creating a proper UI later, since it would be merely a graphical view of your configuration’s structured data. The future is bright!

Now, which language should you pick for your glorious configuration file? It needs to be user-friendly, so people can inspect it and modify it with ease. JSON springs immediately to your mind, but the abundance of brackets and the lack of comments give you pause. TOML maybe? You are afraid it might be too minimal for your needs. Rolling your own language? Too impractical.

YAML

A forbidden spark lights inside your head. Any attempts to put it out are futile. It grows and grows until it finally stands ablaze before you, tempting you with its warmth: why not YAML? Yes, YAML, which is so pleasant to the eye and widely used across the industry. How could you say no to that?

Shivers run down your spine as you remember the yaml document from hell. So often have you been warned about YAML’s deceptive simplicity! It’s a traitorous mask, your elders said, behind which a dark being lurks. Don’t ever come near, it will swallow your soul when you least expect it.

And yet… could YAML indeed be the pragmatic solution in this particular case? We are talking about a small configuration file here. What could possibly go wrong? Surely the gods of software wouldn’t punish you for this offense? How could they ask you to swim against the current, when even renowned projects such as Kubernetes use YAML pervasively?

Trembling, you stretch your hand towards the forbidden fruit, reap it and take a good bite. The flavor of instant productivity fills your mouth with delight and you feel confirmed in your choice. Why did you even doubt? After a few code changes your software is configurable through a YAML file. The dopamine surge overwhelms you, and you put the icing on the cake by adding an example configuration to the project’s readme.

But alas, superficial satisfaction cannot last. As the years go by, the sweet flavor in your mouth turns bitter. Your software has grown. The once simple configuration file now spans more than a hundred lines. Yes, the file is pleasant to look at, but modifying it is nothing short of miserable. Why did you disregard ancient wisdom? In silence, you mourn your lost innocence and the fallen state of humanity.

Ah, if you could begin again.

The crux of the problem

Do you recognize yourself in this story? I have seen it play out a few times and feel like we, as an industry, have somehow come to terms with the miserable situation we are in. Once in a while you may see some brave and noble soul proposing a new configuration language, but so far none has achieved mass adoption. What is going on?

The crux of the problem is, in my eyes, beyond the domain of configuration language choice (i.e., YAML vs. alternatives). We seem to be approaching the very problem of configuration from a flawed starting point, setting way too low expectations for our tools. We are failing to see that configuration files are actually user interfaces, and that they should be treated as such.

Once you start thinking of configuration files as user interfaces, it suddenly makes sense to demand an excellent user experience for working with them. The whole point of a user interface is to make the software accessible, with mechanisms that prevent human error and guide the user down the pit of success. We all recognize bad UX when it feels like you are fighting the computer to achieve a specific goal. In an ideal world, the computer would enhance you without getting in the way, like a bicycle for the mind.

What would configuring software look like if our tools were rooted in the “configuration is UI” paradigm? Can we realistically dream of an ecosystem in which configuration is a joy to write and maintain?

A shout out to KSON

Having come to this point, I’m resisting the urge to present an all-encompassing theory of what configuring software could look like in the perfect world. Instead, I’d like to give a shout out to an existing open source project, which in my eyes is an excellent real-world example of the “configuration is UI” vision. I’m talking about KSON, which just released its first public beta after years in the making. Feel free to check out the website, or go directly to the online playground. That will give you a much better idea of the project than anything I could write here. You know what they say: show, don’t tell.

For those who’d rather skip the links above, let me briefly quote some paragraphs from the beta release announcement:

Anywhere a human is reading or editing YAML/JSON/TOML, KSON may be used as a more effective interface on that data.

That’s a bold claim right there! But maybe it’s warranted, especially once you consider the sheer amount of work that has gone into the release:

KSON is a verified superset of JSON, has native JSON Schema support, transpiles cleanly to YAML (with comments preserved!), and is likely available wherever you want it—current supported platforms: JS/TS, Python, Rust, JVM, and Kotlin Multiplatform.

KSON is also widely available in developer tools, with support for VS Code, Jetbrains IDEs, and anywhere you can plug in an LSP.

See the appendix at the end of this article for an example KSON document. You will notice that the language feels familiar and that it has been designed from the ground up to provide an excellent editing experience. Also, advanced language support in code editors is to me a great example of the “configuration is UI” paradigm. It lets the document come to life under your fingertips, instead of being a dead text file.

Join the movement

What a breath of fresh air! I’m hoping the vision of user-friendly configuration keeps unfolding over time, be it inside the KSON project or elsewhere. We, as an industry, should really set a new standard in which it’s normal and even expected to provide a top-tier configuration editing experience. There are so many possibilities¹!

In case it’s not clear yet, I’m enthusiastic about KSON. If you visit the open source repository, you will probably see me among the contributors to the project². Besides the technical merits of KSON, I’m impressed by the driving force behind it: a small community of engineers has decided to bite the bullet and craft open software configuration tools that put humans first. It truly is “a love letter to the humans maintaining computer configurations”, as it says in the repository’s tagline.

To me, KSON is more than a new language or a collection of tools. It is an attempt to bootstrap a developer movement based in the “configuration is UI” principle. If that resonates with you, please join us in our effort! Merely trying out KSON is already a good start. And, if you end up liking it, go use it wherever it makes sense. Finally, feel free to chat with us on Zulip any time. I’m looking forward to meeting you there!

Appendix: a KSON example

While this blog post is about the principles behind the project, and not about the KSON language, here’s a tiny example of a .kson file derived from a dbt model:

version: 2
models:
  - name: my_transformation
    description: 'This model transforms raw data'
    columns:
      - name: id
        description: 'A unique identifier'
      - name: name
        description: 'The name of the item'
        .
    database: your_database
    schema: your_schema
    materialized: table
    sql: %sql
      SELECT
        id,
        name
      FROM source_data%%

As you can see, it has the readability of YAML, which is a great feature in my book! Importantly, however, KSON carefully avoids classic YAML footguns. One example of that is indentation handling: the code snippet above is indented in a way that makes the structure of the document evident. But, contrary to YAML, having “wrong” indentation does not break your configuration. If you were to remove or randomize the leading spaces for every line, the following would happen:

1. The document would parse to the same object as before.
2. KSON would warn you that the document’s formatting is confusing, because the indentation doesn’t match the structure of the document (fortunately, the autoformatter can trivially fix the warning for you on save).

An additional feature that is not immediately apparent here is that the embedded SQL is actually “alive”. A properly configured editor will see more than a multiline string there! It will know that it’s SQL, it will provide syntax highlighting for it, validation, and all other goodies you are used to when dealing with code.

See the official website for more information and a space to play with KSON right from your browser.