
JSON as configuration files: please don’t (2016) - pcr910303
https://arp242.net/weblog/json_as_configuration_files-_please_dont
======
hombre_fatal
"Lack of programmability" is a feature. Declarative config lets tools
statically analyze and transform the config. You can't even figure out what
the dependencies are going to be for some Gradle projects without executing
them. [https://stackoverflow.com/questions/51153878/conditional-
dep...](https://stackoverflow.com/questions/51153878/conditional-dependencies-
in-gradle) \-- The author's programmable example is a classic Bad Idea in my
experience.

Also, check out JSON schema and its integration into tools like VSCode. VSCode
gives you generalized autocomplete on its own config and known config formats
like package.json by pulling in json schema definitions. It works well. Easily
a better experience than the executable-program-as-config I learned to hate in
the JVM world, and easily better than ad-hoc config like Caddy's.

I have a more practical pitch: make your tool consume json5 as well as json.

Also, it's telling that the author wasn't even willing to stick their neck out
enough to pitch a single solution. I guess in the end they realized there are
always trade-offs and any alternative would have its own downsides. :) But I'm
getting a bit fatigued of these you're-doing-it-wrong posts. They are
effortless to write and they're like crack to HN. I can complain about
literally everything.

~~~
nine_k
This totally misses the point of the article :(

JSON is a fine format for storing configuration data, and any reasonably
structured data. So is XML, protocol buffets, what have you.

JSON is a poor format _for humans_. For a configuration file that an actual
human would edit _by hand_ , and read and try to understand later, JSON is a
pain.

Comments are mostly useless in a machine-generated and machine-consumed file.
They are indispensable for humans, because they are a link to what machines
are _not_ doing.

Nice formatting is useless for a machine-consumed file, because they process a
stream of bytes. They are indispensable for humans who recognize text very
differently.

This boils down to one thing: config files are _source code_ , and need all
the amenities that make source code comfortable for humans.

~~~
joezydeco
_JSON is a poor format for humans_

But do you know what sucks even harder? XML. If I can replace an XML
configuration file with JSON then screw it.

~~~
manigandham
Millions of developers use XML all the time, it's called HTML.

People can easily read and edit it with deeply nested structures, attributes,
and even malformed data. Frontend frameworks using components and variations
like JSX also maintain the same style because it's very natural to use.

Now try taking a typical HTML document and expressing it in JSON. Even an
empty page would be completely unmanageable without tooling. People have a
strange reaction when they hear "XML" but it's much more structured, usable,
and widespread than you think.

~~~
gridlockd
> Millions of developers use XML all the time, it's called HTML.

HTML is _not_ XML and even then few developers today use HTML without some
sort of processing involved. HTML is also not a language used for
configuration files, so it is really off-topic.

The question is, do people prefer XML configuration over JSON configuration.
The answer is that people generally prefer JSON. JSON just maps far better to
data types we use in everyday programming. Have you seen some of the common
ways of expressing key-value pairs in XML? It's _horrible_.

> Now try taking a typical HTML document and expressing it in JSON.

That's not the problem anybody is trying to solve here. We're talking about
configuration files, not complex documents. But let's say I wanted to solve
_that_ problem, the representation would look like this:

[http://www.jsonml.org/](http://www.jsonml.org/)

Not that bad at all.

~~~
manigandham
It's a technical distinction without a practical difference. They are both
declarative languages to describe data.

 _Why_ is it so horrible? Have you ever typed a <ul><li> list? Or <input
name="key" value="value">? What exactly is so difficult about this syntax in
XML but completely fine in HTML?

The point isn't whether you can represent a document in JSON, it's about how
easy it is for a _human_ to manage it. The XML/HTML structure is far easier as
things get more complex. The page you linked to shows this quite clearly even
with the small "Bulleted List Example" at the bottom.

~~~
SllX
HTML is distinctly _not_ XML. There _is_ XHTML if you want to use a form of
HTML that is processed like XML, but XML processing is a lot stricter than
HTML processing in which you can take a lot more liberties in the markup and
still end up with a readable result, maybe even what you intended, whereas an
XML processor will usually refuse to render incorrect XML markup at all.

~~~
manigandham
I'm comparing the data structure and editing ergonomics (which are identical)
between XML and HTML, not how they are processed. It's good for config files
to have precise parsing instead of tolerating errors.

------
fabiospampinato
So what's the author's proposed alternative?

IMHO JSON5 (JSON with comments basically) is fine for config files, VS Code is
using this and they seem to be doing alright.

Addressing the article's points:

\- Lack of comments: not an issue with JSON5.

\- Readability: I think it's pretty readable. Are the quotes, semicolons and
commas really an issue? Not for me.

\- Strictness: just edit it with an editor that points at the errors quickly.
Escaping quotes might be annoying, but I can't think of a possible alternative
format where escaping isn't required at all.

\- Lack of programmability: I've never had any problem with this, and again
pretty complex and customizable applications like VS Code seem to be doing
fine without this. This may even be considered a feature, as it forces you to
keep the configuration well separated from the actual logic.

~~~
TazeTSchnitzel
Personally I'm partial to the classic Windows-style INI file.

Because it was designed to be a human-editable configuration file format, it
has a simple and intuitive format that is easy for both humans and machines:

    
    
      [Section]
      ; comment
      Key1=Value
      ; comment
      Key2=Value
      [Section2]
      Key1=Value
    

It is also easy for machines to non-destructively edit, maintaining existing
comments and formatting by humans, and applications take advantage of that.
That is a big plus in my opinion.

~~~
Pxtl
The problem with ini is that it has no good story for arrays or associative
arrays. TOML attempts to fix this, but it provides _ugly_ format for arrays
and associative arrays.

~~~
afiori
I personally find the TOML solution quite nice. In part because you can always
drop to JSON syntax to avoid excessive nesting of array tables.

------
nebulous1
It's like every other article I read these days takes a strong opinionated
stance and then gives decent but not overwhelming support for it.

    
    
        Please don’t. Ever. Not even once. It’s a really bad idea.
    

Followed by a list of reasons of which lack of comments is the only one with
any universal weight.

~~~
mmcnl
What's even worse is the lack of a proposed alternative. These days I'm
getting sick and tired of "X is bad and you should not use it" articles with X
being something popular that everybody uses/does, without proposing a decent
alternative. Tell me what I should do, not what I shouldn't do. The first one
is very valuable, the second is just giving yourself a tap on the shoulder.

~~~
overgard
That’s a pretty silly stance. If I tell you not to touch a hot stove do you
expect me to give you instructions on what to touch instead? And if I don’t
are you going to burn your hand to spite me? “Well if you don’t have a better
idea I’m just going to keep burning my hand”

~~~
adjkant
Well if you need to do X, then yes, you need an alternative. The alternative
of not doing anything is worse in the case (or at least that premise seems to
be accepted by the author). So if you say do X but don't use tool Y, then you
need the alternative.

Your stove metaphor breaks because the alternative of doing nothing have no
consequences.

~~~
overgard
If you’re a professional you get paid to make these decisions. You don’t need
a blog to do it for you.

~~~
adjkant
Yes, because doing any research on anything is not what professionals do, they
just do everything themselves...

Blogs are meant to offer insight and arguments, and all the top level comment
is saying is that this blog did a bad job in that respect.

~~~
overgard
Advice on what _not_ to do IS an insight. And there's an argument for why not.
The idea that you have to give an alternative in order to not be "negative" or
whatever when there's not a one-size-fits-all piece of prescriptive advice is
just dumb.

~~~
adjkant
You don't _have_ to offer alternatives but it does improve the piece. No one
said it had to be one-size-fits-all, there's plenty of room for nuance.

------
johnwheeler
Website is really wigging out on iOS.

Back on topic, first we’re not supposed to use text files. Then, no XML files.
Then, don’t use YAML. Now, we’re supposed to stop using JSON.

At some point you realize the problem isn’t with the tech but with the
programmer. We have this need to constantly reinvent the wheel all the time.
It’s silly.

~~~
ordinaryperson
Exactly. Also, OP does not explain the need for comments in a config file. I
mean, do people consider Apache config files -- which extensively use comments
-- to be a shining example of clarity? Hundreds of lines long, impossible to
parse manually. Good luck finding those 3 lines you need.

OP's argument is silly. JSON files are fine for config.

~~~
kbenson
> I mean, do people consider Apache config files -- which extensively use
> comments -- to be a shining example of clarity? Hundreds of lines long,
> impossible to parse manually.

You're conflating two things, the readability of very large config files, and
the readability of config files that allow comments.

> Good luck finding those 3 lines you need.

Personally, since I live in a world where searching text in a file is
commonplace and trivial, additional text to match, possibly even comments that
note where the config differs from the stock one that ships, are useful.

~~~
ordinaryperson
The comments of these config files are part of what make them unreadable,
these are not two unrelated issues.

Yes, searching Apache config is pretty much the only reasonable way of finding
what you need. But have we really gotten to the point where we passively
accept gargantuan, unreadable config files because it's possible to search for
the exact pattern you need?

What if there's a problem in your config and you need to find the issue?
Prepare to set aside a few hours of your time to read every block.

~~~
spc476
I just looked at some random configuration file on my system. Right at the
top, in the _comments_ was the following:

    
    
        # Please don't edit this file directly (it is updated with every Red Hat
        # Linux update, overwriting your changes). Instead, edit /etc/...
    

Nice. I now know to make changes in a file that won't be overwritten by an
update, and if there are issues, it's either with the site local file, or the
one provided by Red Hat, and it's probably (although not exclusively) the site
local file that is in error.

------
KirinDave
If you're looking for a configuration language that is powerful and useful AND
can interface with existing YAML based systems, may I recommend Dhall?

[https://github.com/dhall-lang/dhall-lang](https://github.com/dhall-
lang/dhall-lang)

Dhall gives you the power of a limited programming language, the power to
version configs and perform generation and logic in your configs, gives you
the ability to spread your configs and custom functions for config generation
across multiple machines safely, and does so with good guarantees about the
type system and does a good job of stopping potentially infinite loops.

Dhall is really, really good and very overlooked by the industry just because
its syntax is functional.

~~~
MaxGabriel
What kind of things have you used Dhall for before? I think it's pretty
interesting but we don't have enough problems with YAML to really switch.

~~~
KirinDave
You might enjoy the examples at [https://github.com/dhall-lang/dhall-
kubernetes](https://github.com/dhall-lang/dhall-kubernetes)

------
edoceo
Here I am still using INI and/or XML configs like it's 2000. Programs can
read/write if needed, comments, parsers galore. I still can't see how these
are "broken". My biggest driver is the comments issue - nearly all non-json
config files (ini, XML, rc, conf) for projects I use have loads of valuable
instructions in them, right next to the thing that needs that documentation.
Currently, all JSON ones I observe are missing that

~~~
ChrisSD
TOML is the popular modern alternative to INI. It's a more rigorous spec and
has a few useful extensions.

~~~
edoceo
Yea, yeah...I see TOML and YAML a lot too - I also prefer those to JSON for
config files.

I've been rocking the ini file config for 25+ years, it just works, zaro bugs,
and I can get on with building cool stuff.

~~~
ChrisSD
YAML I think is too full featured. It does way too much for a config file
format. INI and TOML have the advantage of being simple and focused. My only
issue with INI is that different parsers aren't always entirely compatible
with one another. But that's mostly only a problem for edge cases.

------
krapp
Almost 200 comments as of now, but no one mentions Lua tables as an
alternative to JSON?

Yes, you have to include the runtime, but the size of it is all but guaranteed
to be smaller than whatever library you need to parse YAML or TOML or XML (or
JSON in many languages.) Smaller than some fonts.

The syntax is almost the same as JSON, but you can use comments and multiline
strings. There are also APIs for just about every language imaginable.

You do sacrifice an enforced lack of programmability unless you're self
disciplined, though, and Lua does index at 1 instead of 0, which is annoying
and objectively wrong, but still less of a gotcha than some of the crazy stuff
YAML does.

... that said, I do also feel like anything touching the web stack at all
should probably be using JSON just because javascript engines already parse
it.

~~~
fit2rule
I came here looking for other lovers of Lua.

Configuration is in Lua's roots. It is specifically designed for use as a
self-documenting configuration language.

I think the issue is that people just don't know how to use Lua to load config
files. ;) But the fact is, there are few other better options than to include
the Lua VM and then put all configuration management in .lua files on the
target system.

------
aphextron
After spending the last week fiddling with YAML files, please do. White-space
dependent config is a complete nightmare, and XML is generally overkill. JSON
caught on for a very good reason; it is the most succint possible human and
machine readable text based data format short of just writing S-expressions.

~~~
adrianhel
Toml is so much better. Editing json with the default vim configuration is
really error prone. But I'd rather have json than yaml.

~~~
h1d
Really tired of cutting the last element in an array and causes an error on
that last little comma in json. TOML to the rescue.

------
tgsovlerkhgsel
The problem with _not_ using JSON is that the alternative almost always is
"some proprietary format" or "an undefined dialect of something that looks
like a well-known format".

I consider that significantly worse. With JSON, you at least can assume that
the person reading it will understand what the file means. With a proprietary
format, especially the popular "key=value" format, it gets super murky - what
are the rules for quotes in this dialect (are quotes required, optional, or
interpreted as part of the value, which escape characters), will white space
be included, etc.

Lack of comments does seem like a very valid point.

I don't see the issue with readability. It is not great but still OK without
syntax highlighting, and superb with highlighting (which works because it's a
wide-spread standard format, not some weird custom dialect).

The strictness is mildly annoying, but violating it will make the config
obviously invalid, which means it can be rejected instead of silently breaking
production because you used a single quote and this dialect's parser only
considers double-quotes, so your single quote was considered part of the
string.

I don't know of many projects that use programmable configs, and many attempts
to achieve this resulted in horrendous nightmares.

Seems like a superset of JSON that remains a subset of JS (like JSON5) can
address most concerns, and can still be syntax-highligted with a JS
highlighter.

~~~
trollied
> The problem with not using JSON is that the alternative almost always is
> "some proprietary format" or "an undefined dialect of something that looks
> like a well-known format".

Sorry, that’s nonsense. JSON is young.

We lived happily with many easy to read & parse file types before JSON
arrived. Everything has changed because CPUs are fast now (so parsing overhead
isn’t noticed) and storage isn’t worried about (JSON is bloated).

------
jayd16
Json is the worst except for all the other options. It seems too late now but
json with comment blocks and a schema notation would be ideal.

I say too late because there's no migrating the world's json parsers at this
point. We could decide to all agree on a schema and comment format that uses
the existing syntax with "#comment" and "#schema" fields but there doesn't
seem to be a defacto standard.

------
mojuba
What we tend to forget in this debate is, human readability doesn't only mean
"read and understand", but "read, understand and mentally validate". Now I'm
not so sure that for example YAML is as easily validatable as JSON.

To me the simplest and the easiest to validate used to be the old good INI but
unfortunately it never got its chance to be strictly standardized to support
nested structures. JSON is the next readable/validatable but it is slightly
worse in all respects.

~~~
enriquto
> To me the simplest and the easiest to validate used to be the old good INI
> but unfortunately it never got its chance to be strictly standardized to
> support nested structures.

That is a feature! If you need to "nest" structures, you are not really
writing a configuration file.

------
didibus
Since I started using Clojure, all my configs have become EDN
([https://github.com/edn-format/edn](https://github.com/edn-format/edn)),
which is what JSON is to JavaScript. And it is awesome.

So I can't see why JSON would be a bad choice either.

There are some things in EDN missing in JSON, richer types, can be extended by
the user and support for comments mostly. I'm not sure if not having those
would be a deal breaker though.

I've used YAML for some things, and I haven't found it better. In fact, it's
annoying to have a different syntax for your config then you do for your code.
And the whitespace matters definitly has been a source of frustration.

~~~
donpdonp
EDN is fantastic, though I havent used it in a project in a long time. If
there's one thing JSON (and numerous programming languages in general) can
learn from EDN is that whitespace is the ideal seperator in lists. Commas are
an anti-pattern that adds its own level of management (hence the trailing
comma issue) that can be sidesteped entirely.

------
adjkant
Besides comments I see none of these as negatives.

JSON is plenty readable for most in my experience and there are plenty of
great readers/prettifiers for it.

Having flexible configuration files sounds like a terrible idea. I don't want
my mistakes to fail silently. Not to mention that the only problem the author
mentions is trailing commas...

as mentioned better by others, lack of programmability is a feature, not a
bug. Configuration files are presets and markers, not functionality.

------
drej
Some valid points, but the only one that pains me are comments, the rest is
fine.

I don’t want to program my config files, it goes against the whole idea of
configuring stuff.

JSON being JSON makes it language agnostic and easily shared (via APIs and
whatnot).

And as for the changes argument - try inline commit log in a file editor (eg
GitLens in VS Code). Not perfect, but it does give you some history at a
glance.

(The point above is weakened by JSON’s lack of dangling comma support, so one-
line changes often affect two lines).

~~~
strags
Switch your parsers to HJSON, and never look back :)

~~~
drej
Can’t. It’s either a fully standard file or something that will fail at some
point.

------
wiradikusuma
For those looking for JSON-like alternative, I recommend HOCON:
[https://github.com/lightbend/config/blob/master/HOCON.md](https://github.com/lightbend/config/blob/master/HOCON.md)

------
BurningFrog
I just made some JSON config files. They're always/normally written by
software but should be readable by humans. I have no regrets.

PS They do have "comment" fields that record when the file was created. I
don't find it "just damn ugly" at all.

------
buserror
I made an 'extended' JSON format, and parsing library many, many moons ago. I
actually _want_ JSON as config file, it's nice, is strict, it's easy to edit,
it's hierarchical, it's nowhere near as arcane as XML, it's not as stupid as
flat [config].

I added comments, a way to have node names that don't require quotes, hex
constants, base64 blobs etc etc and even have annotated nodes (for translation
and that sort of things).

I know it's not purist, but I never tried to shove it down people throats, it
just fits my use case(s)

[https://github.com/buserror/libejson](https://github.com/buserror/libejson)

~~~
amelius
This looks nice!

Is there a way to have comments, such that when the file is read and then
later written (by the program), the comments are preserved (even if some of
the fields changed)?

~~~
buserror
'saving' comments is difficult; and no the API doesn't handle that, but it's a
pretty cool idea I'll look into it! I mean, all i can do is call the 'slaved'
API with the comment content and let them re-generate them....

------
keymone
i will never stop shilling for EDN: [https://github.com/edn-
format/edn](https://github.com/edn-format/edn)

it has no comma issues (commas are whitespace), it has comments, it's very
structured, it got better set of primitive types and literals for them, it has
native support for tagged values for encoding more complex types, it's got
first class support of encoding computation by virtue of being subset of
clojure - lists can represent function calls, the usual lisp shenanigans, it
has readability of yaml and none of it's drawbacks.

it's a shame EDN is not more widely used.

~~~
int_19h
It does have some questionable Clojure-isms (e.g. why have both vectors and
lists), but it's certainly much better than most contenders out there. Unlike
JSON, it didn't throw the baby out with the bathwater when it comes to XML
features beyond syntax and data model idiosyncrasies - it still has
namespaces, for example, making it trivial to design extensible data models.

~~~
keymone
Vectors and lists are very different data structures with different
performance characteristics.

~~~
int_19h
In-memory, yes, but not when it comes to serialization. As data, both are
semantically just sequences of values for which order matters. Indeed, you
generally don't see this distinction in most serialization formats.

~~~
keymone
> both are semantically just sequences of values for which order matters

you've just described strings, shall we get rid of them too? :)

i find it weird that you would complain about presence of some feature which
in no way interferes with any other features and can be completely ignored
without any consequences. was there something else you wanted to use parens
for in EDN serialization format?

~~~
int_19h
Complexity matters for serialization formats - the more complex the spec is,
the harder it is to implement a parser for it, and the larger that parser is.
Serialization frameworks can't just ignore features without consequences.
Thus, redundant features always draw attention - this is no different than
e.g. XML having both attributes and elements, which is also often brought up
as one of its deficiencies.

But I don't consider it a major deficiency, just a nit. I mean, in the comment
that you've responded to, I literally said that it's one of the best
contenders for a human-readable serialization format today - it's certainly
much better than JSON, or XML for that matter. It's just not perfect.

------
KoenDG
> Lack of comments

json5 to the rescue: [https://json5.org/](https://json5.org/)

> It’s just not that readable. Sure, it’s readable for a data-interchange
> format, but not readable for a configuration file.

I'm of the opposite opinion. I find json to be the easiest to read, as opposed
to yml and xml.

------
overgard
It’s a bit lesser known but I’m a fan of HOCON (human optimised config object
notation).
[https://github.com/lightbend/config/blob/master/HOCON.md](https://github.com/lightbend/config/blob/master/HOCON.md)

If that’s not an option I’d prefer xml (with some sadness). JSON is a bad idea
for the reasons described in the article, and YAML is too clever for its own
good and is definitely a loaded foot-gun.

~~~
75dvtwin
HOCON is great. It can be incorporated into many programming languages. And it
supports inheritance, includes, overriding of environment variables and so on.

I think that this library found a very good compromise between configuration
and programmability.

In configuration files you want overrides, includes, comments and inheritance.
May be very very simple pattern matching.

Yet, you do _not_ want flow control structures such as if-statements/loops &
gotos.

------
strags
HSON ( [https://hjson.org/](https://hjson.org/) ) addresses a lot of this.
Just allowing trailing commas and adding comments reduces 90% of the friction
involved.

~~~
user5994461
And most importantly it can consume JSON just fine. No need to learn yet
another language.

Also fully convertible to json (without comments) if there is ever a need to
change format or to interface with another system that can only understand
json.

------
hp
People have tried every point on the JSON-to-full-programming-language
spectrum, I put some examples in this post:
[https://blog.ometer.com/2015/09/07/json-like-config-a-
spectr...](https://blog.ometer.com/2015/09/07/json-like-config-a-spectrum-of-
underoverengineering/)

JSON5 is new since that was written I think... there are a bunch more of them
too.

As part of the team at lightbend that came up with HOCON I still like it
because it lets you use env variables (handy for Docker, Heroku, etc) and has
some don’t-repeat-yourself capability without going to a full programming
language.

(If you’re going full language, to me why not use a real one, maybe the one
your app is written in... but there are definite tradeoffs to using a
language, like difficulty writing automation that understands the config, and
it assumes anyone changing config is a full-blown developer)

------
_bohm
Slightly off topic but did anyone else notice this ligature?
[https://imgur.com/vtOdiCE](https://imgur.com/vtOdiCE)

What in god's name is that??

~~~
ncmncm
I love that "ct" ligature so much! Also "st". Sometimes you find "sc".

I persuaded the author of Linux Libertine to add the first two as "historical"
alternatives.

[https://english.stackexchange.com/questions/25118/is-
there-a...](https://english.stackexchange.com/questions/25118/is-there-any-
significance-in-little-curls-joining-the-st-and-ct-in-old-books)

------
vonseel
_XML, which I consider to be unreadable by both machines and humans._

Really?

Depends on how it’s structured, but I’d say XML is much more READABLE than
JSON, although it requires much more typing to write by hand.

And it was a much more rigorous data format than JSON for many years before
any of the more modern things like JSON schemas came about.

~~~
zelly
XML has comments.

XML can be programmable. You can make <If> and <Loop> constructs if you so
desired while being trivially parse-able.

XML can be arbitrarily strongly typed.

JSON really was a step backwards in many ways. I think the main reason JSON
took over was that it looks nicer and is easier to type by hand (as if
everyone doesn't have editor macros for XML).

------
zeptomu
> Lack of comments

Actually I consider that a feature. If some piece of software requires some
complex configuration I have to refer to some external documentation anyway.
Many projects include the documentation (or parts) as comments in their
configuration files (e.g. Postgres' pg_hba.conf), but I think it makes it
harder to find the interesting parts.

> Readability

I think JSON is pretty readable, even for non-programmers, but this is highly
subjective.

> Strictness

Good! Parsers are too lax anyway.

> Lack of programmability

Again, that's a feature: just keep it simple. Now JSON is not perfect (I would
like to have a distinction between integers and floats), but it gets a lot
right and it supports the most important data types and structures

    
    
      - strings
      - numbers
      - dictionaries
      - lists
    

that easily map to data structures found in higher level programming
languages.

~~~
isbvhodnvemrwvn
> If some piece of software requires some complex configuration I have to
> refer to some external documentation anyway.

Except something seemingly simple which doesn't attract your attention might
have a weird reason for existing - for instance you might have dependency
which has to be pinned to a certain version due to compatibility issue or an
existing bug. Would you rather spend 2 hours troubleshooting that or maybe put
a comment there so that the next person can easily understand the core issue
and evaluate it in 5 minutes?

------
janpot
Would be nice if you could add a few suggestions of languages that you
consider more suitable for this task.

------
schwarze_pest
What about UCL?
[https://github.com/vstakhov/libucl](https://github.com/vstakhov/libucl)

~~~
stock_toaster
This is one of my favorites too.

HCL and HCL2 from hashicorp have a similar feel -- which makes sense, since
they were inspired by ucl and nginx configs apparently (so says the readme).

------
Pxtl
But XML is horrendously overdesigned and verbose.

YAML has dangerous type coercions and tedious indenting.

TOML has bizarre formatting for arrays and associative arrays.

And other formats have too-small adoption.

We know that every config format is _bad_ , but we appear unable to correct
this bone-headed simple problem.

------
dstroot
My largest hang up is I __LOVE __to comment my configuration. So JSON is out
by definition. YAML seems to work just fine for all my use cases and is less
verbose and more human readable FTW.

~~~
detaro
IMHO, YAML tries to be too clever. E.g. the fact that it happily guesses types
and doesn't require strings to be quoted creates tons of traps.

    
    
        languages:
            - en
            - de
            - no
        portmappings:
            - 8080:80
            - 2222:22
    

parsing the above, "no" is suddenly a boolean, and YAML 1.1 parsers will turn
"2222:22" into the number 133342 (because there was a helpful rule that thinks
the latter means "2222 minutes 22 seconds" and turns it into the number of
seconds... [https://docs.docker.com/compose/compose-file/compose-
file-v2...](https://docs.docker.com/compose/compose-file/compose-
file-v2/#ports) )

I really liked it initially, but after using it a bunch I'd prefer a more
restricted subset of it. (also hit a bunch of parser bugs/incompatibilities,
where the complexity of supported cases probably also plays a role)

~~~
the_imp
To be clear, both of those issues are just with YAML 1.1. The core schema of
YAML 1.2 dropped parsing "no" as true, or (as you mentioned) colon-separated
numbers as sexagesimal integers. But yeah, unfortunately a number of libraries
that only support 1.1 are still being used.

------
adrusi
I want completely different things from the configuration format, depending on
the software I'm configuring.

JSON is great if I'm going to want to generate configs programmatically much
of the time but still want to be able to view or edit them manually now and
then. JSON (+comments) is a fine config format for vscode since it's (among
other things) a specialized JSON editor, and it gets to leverage functionality
it already has (JSON schema support) towards making it's configuration
management pleasant.

If the config is going to go in a users home directory, like ssh or
fontconfig, or for services like nginx and polkit where other software is
going to want to add some configuration, then support for config glob
directories (e.g. conf.d) is very handy, so that different system packages or
gnu stow directories can provide their config via file tree merging.

Some software gets a ton of value from using a scripting language as it's
config format, although in general it's something to avoid. Vim and emacs
wouldn't be what they are with a less powerful config format.

Some programs need just a tiny sprinkle of config, just to specify the socket
to bind on and maybe some database credentials. INI files or even just
environment variables are ideal for this sort of thing.

JSON has its place, the problem is that it's too easy to use. Programmers
automatically turn to it without thinking about what their software needs from
its config format. It's the _not thinking_ that's the problem.

------
tqwhite
.ini files are the only good option.

I did a thing that used JSON for config years ago when I was young and stupid
(60). Terrible choice. Someone in this thread said that config files need the
amenities of source code. I agree. However it also needs to be readily machine
generated in case your system is successful enough to support a UI for
configuration.

.ini hits the sweet spot for me. I can edit it reliably. It's extensible in
every way I've ever wanted.

I looked at TOML, mentioned below. I would like the array syntax but when I
saw the Wikipedia article's example including something with quotation marks I
realized that complicating it with array syntax means that you hop down the
slippery slope to having semantic cruft to distinguish the types.

For .ini, everything is a string, period. You always know what you have. No
debugging.

In fact, I wrote myself a .ini interpreter that does some obvious stuff to
make it useful in Javascript. Case-insensitive interpretation of true/false.
Things that can be a number become one.

But then, slippery slopes galore. I added hinting to let me convert objects
with number property names to arrays. Now I spend my entire life realizing
that I didn't add the hint for this recently, quickly added case.

I'd be better off just always converting it where I need to use it.

It's my opinion that changing anything about the .ini is always premature
optimization.

------
zzo38computer
Depending what you are making, there is different formats that you can use,
such as: YAML (which is a superset of JSON; however, it does not use the same
comment format as JavaScript), X resource manager format (I wrote two
implementations, both of which are smaller than the one in Xlib, and can be
used independently of Xlib), a C include file (but then you have to recompile
the program to configure it, although it makes the program more efficient),
INI (some programs use a simplified version without section headings), RDF,
TOML, executable code (especially if the program is written in an interpreted
programming language, such as JavaScript, or embeds one, such as perhaps SQL
if it is a database program, although SQL seems isn't generally a very good
configuration format), etc. What is best depends on what the configuration
file is for, I think.

I haven't heard about JSON5 before now, and I don't know what is JSON5 (I read
in here apparently JSON5 is JSON with comments; what format of comments (is it
same as JavaScript), and does it accept trailing commas?). Also, XML is OK for
markup, but it is often used for other stuff where other formats are often
better (although maybe you have some case where the other options would be
worse than XML for the configuration format).

------
longcommonname
I've been attempting to use a new project for json as a dsl.

[https://jsonnet.org](https://jsonnet.org)

It's pretty amazing and I'd recommend it.

------
dorfsmay
Why isn't json5 used more? It should be pushed until it becomes the defacto
standard.

[https://json5.org/](https://json5.org/)

~~~
Carpetsmoker
JSON5 is okay, but it has different goals than JSON. I'm not sure if it should
replace it.

~~~
dorfsmay
Serialization vs configuration?

Isn't json a subset of json5? If so, but write out to json when serializing,
but always read json5 so you never run into any surprise? Any drawback with
this approach?

~~~
Carpetsmoker
I think the issue is that JSON is already harder to parse than you'd think;
see: seriot.ch/parsing_json.php

While JSON5 doesn't introduce huge changes as such, it does make it more
complex. There is also the matter of semantics/API; should json.parse() accept
JSON, JSON5, or both? What if we expect JSON and someone sends JSON5; should
we accept that? Postel's law says yes, but personally I think that would be a
mistake.

It seems to me that it's easier to maintain a clear distinction between the
two (json.parse(), json5.parse(), etc.) One of the values of JSON as a data
interchange format is that it's fairly simple, and adding JSON5 features –
none of which are needed for this usage – probably isn't a good idea.

Also note that there are many JSON supersets. YAML is a JSON superset: any
valid JSON is also valid YAML, there's alos HOCON, and probably a few other
things as well.

------
fmajid
Let's also exclude YAML, which has all sorts of security issues. TOML seems to
be the best config file syntax. Easy to read, does not try to be Turing-
complete :-)

------
ChrisSD
I agree with this except for the last point. "Lack of programmability" is a
good thing. Mixing configuration and code is a recipe for a tangled mess.

------
RandyRanderson
I believe every programmer, once they have implemented a config file format,
then added control of flow, assignment, and/or statements should get a patch
like in the boy scouts. It should have "never again" in latin on the bottom.

Randy's law 637: Every configuration file format (read by some language 'L1')
eventually gets control of flow, assignment and statements. This format then
forms language 'L2'.

Proof: See Unix.

------
holoduke
Why? I really don't get this article. I am using it for years without any
issues for multiple businesses. Easy to read and easy to parse (any language)

~~~
Zamicol
This article is silly. I honestly think a minor tweaked version of JSON will
be the future for config files. Probably JSON5 which adds trailing commas and
comments.

~~~
Carpetsmoker
A "tweaked version of JSON" is not JSON, it's a "tweaked version of JSON".
JSON5 is also not JSON; it's JSON5.

This is like replying with "but a changed version of this beer tastes great"
to "I don't like this beer". Okay, but that's not what I'm drinking.

------
skissane
The problem with comments: suppose I build a config UI to edit the
configuration file using fill-in-forms. How do I display the comments in this
UI? I can't display classic line or block comments easily, because it isn't
always clear which setting the comment is attached to.

The author says something like "__comment" is ugly for humans editing the
file. Sure, it is. But it works much better if the file is also going to be
edited by a UI. (Although "__comment" can comment the object but not an
individual key; something like "name#comment" being comment on "name" key and
"version#comment" being comment on the "version" key could permit separate
comments on each key.)

I actually am encountering a similar problem at work right now. We have a
complex XML config file. Some people edit it via an XML editor, others edit it
using a fill-in-form UI. With the fill-in-form UI, we'd like to display (and
permit editing of) the XML comments, but it isn't always possible to work out
programatically which XML element(s) the comment is talking about.

Compare:

    
    
        <!-- The following setting is blah blah blah -->
        <foo-setting>32</foo-setting>
        <bar-setting>64</bar-setting>
    

with:

    
    
        <!-- Email Configuration Section -->
        <mail-host>mail.example.com</mail-host>
        <mail-port>25</mail-port>
    

In the first example, the comment belongs the immediate subsequent XML element
only. In the second example, it belongs to both of the following elements.
There is no reliable way to distinguish these cases, unless you try to
interpret the natural language text of the comment itself (which can't be done
with perfect reliability).

------
duxup
>comment support was explicitly removed from JSON for good reasons.

>[https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaG...](https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr)

The link there goes to G+ and thus a dead end. Anyone have that link?

I would have liked to see some alternatives / options that the writer likes.

~~~
ChrisSD
[https://web.archive.org/web/20120506232618/https://plus.goog...](https://web.archive.org/web/20120506232618/https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr)

> I removed comments from JSON because I saw people were using them to hold
> parsing directives, a practice which would have destroyed interoperability.
> I know that the lack of comments makes some people sad, but it shouldn't.

> Suppose you are using JSON to keep configuration files, which you would like
> to annotate. Go ahead and insert all the comments you like. Then pipe it
> through JSMin before handing it to your JSON parser.

HN discussion is here:
[https://news.ycombinator.com/item?id=3912149](https://news.ycombinator.com/item?id=3912149)

~~~
Noumenon72
I am doing my config by reading JSON into Java classes with Jackson. Doing a
minify step would mean that I would get the wrong line number in the error
message when I forget a comma.

------
Zamicol
I 100% disagree.

I rave about JSON. I don't understand the rants with config files, but I could
bet $20 that they _always_ begin with "but my comments!".

In the past I've promptly replied with (copied from my Reddit post):

Douglas Crockford said to use comments in json config files:

"Suppose you are using JSON to keep configuration files, which you would like
to annotate. Go ahead and insert all the comments you like. Then pipe it
through JSMin before handing it to your JSON parser."

Which was at the following link before Google killed Google+

[https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaG...](https://plus.google.com/+DouglasCrockfordEsq/posts/RK8qyGVaGSr)

Here's my flag solution with JSON config files:
[https://github.com/zamicol/jsonflag](https://github.com/zamicol/jsonflag)
I've never read this "arp242.net" article, but my solution anticipates some of
its complaints, such as environmental variables, and addresses them. What I
mean to get at is that this isn't rocket science and the "deficiencies" of
JSON are flexibilities left to be easily addressed by the programmer. JSON is
a great level of complex without being too much.

Every time this comes up, I don't understand how
[https://json5.org](https://json5.org) isn't superior to YAML in every way. If
there was some deficiency with JSON5, just simply use JSON with comments. It's
that simple.

JSON is one of the best things to ever come out of the CS disciplines.
Moreover, JSON is a javascript subset. If json isn't sufficient, why not first
try a different javascript subset/json superset before trying something more
alien?

------
broahmed
Sublime Text uses JSON for settings. As a user, I've never been unhappy with
that. Their JSON parser handles comments fine because each setting is
accompanied by one.

    
    
        // When enabled, hovering over a word will show a popup listing all
        // possible locations for the definition symbol. Requires index_files.
        "show_definitions": true,
    

The author does highlight an important point though: if you're using JSON for
your program's config and your program's parser doesn't support comments, you
may want to find a parser that does.

The author also mentions readability, which I think is subjective. I find JSON
plenty readable provided key names are descriptive and the JSON is well-
formatted. Readability does suffer when you have multiple nested objects. I'll
also agree to the annoyances of forgetting a trailing comma somewhere.

------
jakobegger
One thing the article misses is that configuration files are often not only
supposed to be machine readable, but also machine writable.

Often, software offers commands to adjust config parameters (eg. PostgreSQL's
ALTER SYSTEM command) or even a GUI interface for changing the configuration.

In these cases, if your config file format supports comments, or like the
author suggests, even arbitrary code, then it's unlikely the software can
automatically alter the config file. And even if it could, comments would
quickly become outdated.

PostgreSQL addresses this issue by using multiple config files that can
override each other, which can make debugging very hard, if you're not aware
of the fact.

Issues like this can be avoided if you have a declarative config format like
JSON, and the lack of comments actually becomes an advantage.

So in my opinion, if your config files can be changed by software, JSON is
actually a very good option.

~~~
Carpetsmoker
> configuration files are often not only supposed to be machine readable, but
> also machine writable.

Config files which are expected to be written by _both_ humans and machines
are a fairly rare use case. Most config files are either editable by hand
(e.g. /etc/), or editable though an UI (e.g. Firefox), but not both.

------
jondubois
The main point that makes sense for me is about lack of support for comments;
but JSON5 should solve this problem.

I find JSON to be much more readable than alternatives like YAML and much more
flexible than plain key value pairs. I've been using YAML for a while with
Kubernetes but I find it difficult to follow the indentation (especially if my
IDE does not support guide lines)...

Strictness is a good thing for config files and makes it easier to find
things.

Programmability in config files is generally not a good idea. Config files
should be simple enough so that users with minimal technical ability can
change the behavior of the system without having to know how to code.

If/when JSON5 becomes mainstream and IDEs stop showing warnings about comments
in JSON, I will stop using .js files for my Node.js applications and just use
.json. I do think that the commenting ability is important.

------
tomrod
I get the desire since JSON isn't seen as a configuration tool by its
designers. However, it's proven itself to be a suitable tool for driving
screws as well as hammers (to paraphrase).

For the software folks -- why not adapt the tool or spin off a similar tool to
handle these very common use patterns?

------
pushpop
I don’t think it’s as clear cut as the article describes. If all you want is
to define a few static values, like DB connection details, then it makes sense
to use something that is easier to parse.

However if you’re building another nginx then obviously you’d want something
more composable.

The problem that the article doesn’t address is that there isn’t a single good
common standard. YAML has its own problems, TOML is fine for simple configs
but can quickly get less readable when you start having deep nested elements.
None of those allow conditional elements. So then you have HCL, which is an
abomination and a bunch of other vendor specific formats - most of which don’t
have reusable APIs. So do you then create your own format? And in which case
your users have to learn yet another config language.

------
lgregg
You might want to fix your site:
[https://www.dropbox.com/s/yg58z7hztlez3ff/ScreenRecording_04...](https://www.dropbox.com/s/yg58z7hztlez3ff/ScreenRecording_04-13-2019%2017-07-17.MP4)

It’s unreadable in Brave on my phone.

~~~
Carpetsmoker
wtf?! That's super weird. It doesn't even have a lot of CSS, and no JS at all,
so no idea what's going on here?!

I'll take a look later. Thanks for taking the effort of reporting it!

~~~
lgregg
Yeah! No problem, this is the app version:

Version 1.6.6 (18.11.15.17)

I’m using an iPhone SE

~~~
Carpetsmoker
I can reproduce in Safari on iPhone too (using BrowserStack), and I've reduced
all CSS to this to reproduce:

    
    
      @media (max-width: 26rem) {
        html { font-size: 12px; line-height: 150%; }
      }
    
      a { transition: all .2s; }
    

I added that transition for a slightly prettier colour change on hover. What
was going on is that this would also animate the size of the font, triggering
some back-and-forth between the regular font size, and the smaller one in the
media query.

I fixed it by changing to:

    
    
      a { transition: color .2s; }
    

I _think_ this is how it's supposed to work. It's just the iPhone SE just to
happens to be at the exact size to trigger this? I'm not sure, I wasn't really
able to trigger it in desktop Chrome or Firefox.

At any rate, thanks again :-)

------
billfruit
I haven't seen mention of it in comments: There is a config file format used
by some unix programs: the fortune cookie format. I think Eric Raymond
compared it favourably with the windows ini file format, in his Art of Unix
Programming.

------
herbst
As alternative (even thought I do like and use json) pure code files can,
depending on language, work well too.

Just a file with variable declaration that gets read into the runtime. It's
definitly more readable for non tech users than json.

------
Annatar
The author is correct: JSON shouldn't be used for configuration files (or for
anything else for that matter!), but not because it lacks comments, but
because it's very difficult to construct a parser for it. (Just yesterday I
had to compile and package jq because writing a parser of my own for it would
be insanity).

Configuration should be done with operating system packages and shell
scripting; then there is no need for comments, since the files for making the
package are kept in a revision control system like Bitkeeper or Mercurial and
configuration on systems never modified by a human.

------
mjevans
The ONLY thing I agree with is the comments. However comments in _anything_
would have to be thought of by the developers.

See a tag or section you don't use / parse? Copy that through to the output;
or only over-write the parts of the structure that the parser understands...
Something to help comments and other unsupported items in the config to the
output file.

"XML" expressed configs have this problem too. Way too many projects that
claim to process XML stuff will also just eat the config, remember what they
understand as options, and throw away everything else, comments included.

------
craftoman
And what's the least painless? Yaml? I worked with many configuration files,
the only way to deal with the big beasts is using GUIs. There are tons of free
and paid and most of them cost ~$50.

------
nixpulvis
Honestly, even as a transport datatype it's always bothered me that JSON lacks
a well defined number. I mean, if your going to allow infinitely large numbers
shouldn't you explicitly support them with Big types?

EDIT: and if you want fixed size numbers (for many good reasons) then what
size?

JSON as a config is another story, and I completely agree with this link. I'm
a personal fan of TOML[1] for many purposes.

[1]: [https://github.com/toml-lang/toml](https://github.com/toml-lang/toml)

~~~
mcculley
JSON is fine as a transport datatype between two bits of code you completely
control (e.g., webapp front end and back end). It is a terrible choice as soon
as you want to publish and document a public protocol.

------
wincent
JSON isn't my favorite format, but it's not surprising that it is so widely
used in the JS world because you can trivially read and write it using only JS
and Node built-ins.

------
jimmaswell
JSON is the most straightforward way to add a config to a static webapp. Make
it a JS file that sets window.config or something if you want comments maybe,
or parse it as JS since it's trusted (if you don't trust your own site files
then everything is out the window anyway).

ini, yml, etc are nice but you'd need to import a parsing library and that may
be slow/overkill for a small app. xml works with xmlhttprequest though.

------
reissbaker
We replaced most of our JSON config files at my last job with either YAML or
JSON5 [1]; personally I'm a pretty big fan of JSON5 from a readability and
writability standpoint, although the caveat is that it still uses 64-bit
floating point for all numbers. YAML is a bit too... enormous for my taste
personally, but at least it's better than JSON.

1: [https://json5.org](https://json5.org)

------
deanclatworthy
It's so exhausting being a developer nowadays. Do this, do that. Do this,
don't do this. This is right, this is wrong. Everyone has an opinion. Who is
right? Who is wrong?

I don't even like the term "best practice" nowadays. 9 times out of 10 it's an
opinion on a best practice.

I prefer to just get shit done, do my best what's right, learn from great
colleagues and peers on the job, and filter out the majority of this noise.

~~~
h1d
I bet it was far more exhausting to be a developer before 2000.

They only had "don't do this but since it's all we got, do it anyway".

Feel the luxury of choice not complain about it.

------
kumarvvr
YAML seems a reasonably expressive language and a good practical alternative.
Using it with python is a breeze and allows a lot of flexibility.

------
zcw100
It’s config. I’m willing to bet no matter how awesome a developer you might be
I will find a dozen things to complain about before I complain about the
config format. If it is number one, congratulations your code is amazing.
You’ll have so much time from not having to fix the millions of other thing us
mortal programmers have to do to make the worlds best config system.

~~~
hp
I think the people who really care most are doing ops not dev

(though of course many people do both)

------
flamey
Lack of comments and illegal trailing commas is an artificial problem.
Implement/use non-strict mode to allow those and both of the issues for
readability are gone. Perl JSON modules have this mode, making json files for
simple config just fine. If you already using JSON in your program, theres no
need to add more dependencies for other config file format.

------
kejaed
So what is your favourite format for config files?

~~~
cobookman
YAML.

All the benefits of JSON with none of the negatives.

~~~
iampims
YAML is whitespace sensitive, that alone is a nightmare.

~~~
nixpulvis
Yes, as someone who helps with some software with a YAML config, the
whitespace issue has caused much time in IRC spent trading pastebins fixing
these.

I agree overall YAML looks pretty nice, and consistent whitespace is a strong
preference (I have pre-commit hooks), breaking user (if you have them) config
if they don't know about this is an issue tho.

------
andreineculau
Since many are asking/complaining that the author didn't provide alternatives,
I'd like to point out the obvious starting with what JSON is - "a lightweight
data-interchange format".

Who is interchanging information? In 99% of the cases, which is the target of
the blog post, it's a human/developer and some software writing and reading a
JSON file ON THE SAME MACHINE, IN THE SAME ENVIRONMENT. _That_ is coding! You
can do a far better job controlling a piece of software by actually writing
code, telling it how to run.

Reversely, if you need to configure two pieces of software via the same config
file, you need something that both can read, so you might go with JSON, XML,
YAML, your flavour of the day.

But think for a second: does that happen more than 1% of the times? It
doesn't!

Software like eslint (js), babel (js), emacs, etc are using configuration
written in their appropriate languages, not in a serialized format. This
allows for huge benefits.

If you had the chance to work with AWS for instance, you would have noticed
how their Cloudformation templates are insane. They have pseudo functions,
control statements IN JSON (and YAML FWIW)! On the other side of the globe,
GCP teaches its customers to use python or jinja (a python template engine) to
GENERATE YAML, though you can obviously use whatever language you want, which
is then consumed by GCP.

------
seotut2
You can have comments if you add a preprocessor (such as cpp) to your build
pipeline.

Also, I don't think json is that bad for quick software utities, if you're
already using it for data interchange, there are parsers for every language, I
think it's a superior option to designing a custom config language (up to a
point of course).

------
kminehart
I think the only real issue I have with json/yaml/toml/etc is the fact that
the options available to me aren't obvious. I have to go digging through
documentation to find out what keys are available and what values they accept.
It can be really cumbersome if the authors don't keep their docs up-to-date.

------
BinaryIdiot
This again? It's the same argument against using JSON for configuration that
everyone else posts. Even worse it says "Please don’t. Ever. Not even once.
It’s a really bad idea." but gives you zero solutions that fits the criteria.

It's an effortless post just to rage against JSON. Why is this even on the
front page of HN?

------
z0mbie42
Hi,

I've created the SANE configuration format [0] because I also found JSON (and
YAML, and TOMl...) Faaaar from optimal.

It's kind of a JSON but designed for Human to Machine usecase (instead of
machine to machine)

[0] [https://opensource.bloom.sh/sane](https://opensource.bloom.sh/sane)

~~~
mruts
HOCON is pretty much the same thing. Why not use that instead?

------
cf95
JSON as config files with node programs works pretty well though - especially
when you want to have easy access to those values in the program. I really
don't find the lack of comments to be that bad... if comments are needed
relating to the config you can just stick it in a readme lol

------
graphenus
I agree that JSON is a shouldn't be used as a configuration language.

However, one could use Python as a configuration language! It could fill in
the configuration object, which will then be transferred to the main app using
JSON, YAML, XML, or something better than that.

------
ChicagoDave
This is so far down my list of coding concerns I’m already done interacting
with this thread.

------
qwerty456127
Why the heck does JSON still not support comments? Why is it so hard to add
support for them?

------
intellix
If it's within your own repository then you have comments via git. You can see
when and why things were added if you link them to an issue tracker.

You even have inline comments if you use an editor plugin like gitlens (VSC).

I guess the problem here though is portability

------
Nalta
I use protos as configs pretty frequently. They have comments, easier syntax,
there's a schema file the describes exactly whats expected. You can parse them
from text, csv, or even awful binary, and use them in practically any
language.

------
tqwhite
Speaking of slippery slopes. This JSON enhancement requires documentation. It
turns JSON into a specification language, I guess, and it required
documentation. Ick.

[https://jsonnet.org](https://jsonnet.org)

------
pygatea
Avoiding lightweight markup languages and sticking to real programming
languages for configuration has a lot of benefits.

On that: [https://youtu.be/0pX7-AG52BU](https://youtu.be/0pX7-AG52BU)

------
agl
[https://json5.org](https://json5.org)

~~~
nixpulvis
This is a welcome improved spec! I'll be curious how long till wide adoption.

------
acd
JSON as config is the same reason XML as Config files were a bad idea.
Configuration files will often be read and changed by humans and thus should
be easily human readable.

Plain text equals configuration setting is still a good idea.

~~~
xrisk
I would argue that JSON is pretty human readable, and easy to write by hand
too.

~~~
enriquto
This is not true, except for irrelevant trivial cases where the format does
not really matter.

Try to open a jupyter notebook with a text editor. What you expected to be a
cleanly laid out python program with a few nicely formatted comments is in
fact a nightmarish JSON "text" file, that looks like an obfuscated perl
program.

------
AndyKelley
Related: this C library for parsing JSON that allows comments and trailing
commas.

[https://github.com/andrewrk/liblaxjson](https://github.com/andrewrk/liblaxjson)

~~~
h1d
When they call it a json parser, they should stick to json or call it json5
parser. There is no "relaxed" json.

------
skywhopper
I agree JSON is problematic; mostly because of the lack of comments and the
unnecessarily unforgiving syntax. But this author doesn’t really provide an
alternative. Just setting PHP vars directly?

------
stephenr
I quite like the concept of SDLang for config like this, but I've not yet had
a chance to actually trial it in any real projects (due to less than broad
language support).

------
disillusion
No, it does't allow comments. Fortunately, a project README has more then
enough room for any remarks. Yes, you're better off putting numbers in
strings. No big deal.

But also:

JSON files are easily readable by default, in a lot of languages. Knowledge
about (the limitations of) JSON can easily be assumed. Alternatives like YAML,
TOML or any of the others all have their own idiosincracies.

And non-programmability is a good thing. It might be more verbose, but you
don't have to fire up a javascript environment or bash interpreter or some
such just to read a configuration file. And separate code paths are very
explicit since that will mean separate objects or even files.

------
ravedave5
I think yml is the future of config, but if you want to use JSON it should
only take 5 minutes to write a pre-parser regex to remove lines starting with
#.

------
baron816
What's the alternative? How about...JavaScript! JS has a little function
`JSON.stringify` that accepts objects and returns JSON. Pretty nifty.

------
Layvier
If the alternative is YAML, I'll keep JSON...

------
cozzyd
I'm partial to libconfig myself, although I'm not sure if it's well supported
outside c/c++/python.

------
scarface74
I always mess up when trying to edit JSON to the point where I will convert
JSON to YML make changes and convert it back.

------
beders
Can I also say: Please don't use YAML as config files. Any non-trivial YAML
file can be messed up way too easy.

------
drivingmenuts
This is going to be another holy war, like clean, pure vi vs the bloated,
satanic emacs, isn’t it?

------
ohaideredevs
I read this to be convinced, and I remain unconvinced.

• Lack of comments \- Config files are usually pretty self explanatory

• Readability \- Never been an issue

• Strictness (complaints about trailing commas) \- Who cares

• Lack of programmability \- Does YAML offer this? I don't know YAML.

What are the alternatives?

Edit: After 35 minutes of comments here - looks like we have zero consensus
and the article is trying to prescribe a preference.

~~~
vnorilo
I've used edn [0] as a "better json", but in the end, json is good enough and
ubiquitous. Oh, edn is not programmable either, and that's by design.

[0] [https://github.com/edn-format/edn](https://github.com/edn-format/edn)

~~~
ohaideredevs
Thanks for the link, reading.

------
jaimex2
Yeah nah, I'll keep doing it as its worked extremely well so far with no
issues.

------
derefr
There's a linked article discussing the shortcomings of YAML, as well:
[https://arp242.net/weblog/yaml_probably_not_so_great_after_a...](https://arp242.net/weblog/yaml_probably_not_so_great_after_all.html)

Reading the two screeds together, though, I think the author has ignored one
key idea of both JSON and YAML as formats: their use-cases are complementary,
and the "problems" with each of these two formats only arises when you're
using one for the use-case best suited to the other.

YAML's use-case is for human-written configuration. That's why it has so many
weird ways to write things: to allow humans to write some data down in a way
that works best to communicate said data _to other humans_ , in a way that
machines can coincidentally read. (See also: AppleScript.)

And that's also why YAML is "so powerful that it's basically inherently
insecure." You shouldn't be executing untrusted YAML any more than you should
be executing an untrusted bash script. YAML is a language for the _deploying
sysadmins_ of a piece of software to configure said software with; it's not a
language for the _tenants_ of a system to communicate their needs to the
system with.

JSON's use-case is for building machine data generators and parsers in a
distributed system (like the web) where it is very important that the data be
easily _introspected_ by humans, and that humans will also be able to modify
or otherwise "poke at" said data, in flight, using simple text-based tools.
But the intention isn't that humans will ever author JSON "at scale." JSON is
like HTTP/1.0: it's something that a human _can_ write, in a netcat session to
ensure things are working or to probe at a system's capabilities or responses;
but where a human writing in said format is never going to be the "proper" way
of doing things in production.

Now consider the subheadings of each screed:

"JSON as configuration files: please don’t"

\- Lack of comments

\- Readability

\- [Too Much] Strictness

Obviously, if these are your problems, then you're a human (probably a
sysadmin) hand-rolling configuration. Use YAML.

"YAML: probably not so great after all"

\- Insecure by default

\- Can be hard to edit, especially for large files

\- It’s pretty complex

\- Surprising behaviour

\- It’s not portable

None of these matter if you're a human sysadmin who is _interactively_ hand-
rolling a configuration file for a piece of software. YAML "doesn't scale",
but configuration files aren't a domain that requires thousands of lines or
huge, deep hierarchies. And the complexity, surprises, and portability don't
matter if you're not trying to "shout YAML into the void" without knowledge of
what the target system is.

If those _are_ your use-cases—if you need scalable, portable, secure,
predictable data—then you're definitely not writing a configuration file, but
rather are just interchanging data of some kind. Use JSON.

\---

Now, the funny thing to me is, JSON is a subset of YAML.

(And that's why [https://leebriggs.co.uk/blog/2019/02/07/why-are-we-
templatin...](https://leebriggs.co.uk/blog/2019/02/07/why-are-we-templating-
yaml.html) was written: nobody should be _templating_ YAML when machines are
perfectly capable of _emitting_ JSON that YAML parsers will happily accept.)

Really, rather than talking about _which_ format to use, what this discussion
_should_ be about—in a better world than the one we're in—is the use of
"trusted mode" flags in YAML parser configuration.

Ideally, you should be able to take a YAML parser, and tell it, per input
stream, that "this is the hand-rolled sysadmin kind of input, so parse it
using the full feature-set of YAML"; or "this is the J. Rando user kind of
input, so parse it like a JSON parser with maybe one or two more features"
(ala StrictYAML.)

That would solve most of the complaints the author has, on both sides: if
config systems used _YAML parsers_ but only configured them to _accept_ a
strict subset of said YAML (either StrictYAML or plain JSON) for any input
they expected to come from anywhere other than a sysadmin, then there wouldn't
even be a discussion here. You'd use a plain JSON parser for (efficiently,
securely) receiving plain data; but for configuration, a YAML _parser_ would
be the obvious choice, because it could always be locked down.

But in the world we live in, YAML parsers don't have security features like
this.

I'd make a suggestion of an alternative, which in pseudocode looks like this:

    
    
        opt.parse('-c', '--config [path]', Path) do |path|
          this.config = JSON.parse(path)
        end
    
        opt.parse('-C', '--config-trusted [path]', Path) do |path|
          this.config = YAML.parse(path)
        end

~~~
the_imp
> But in the world we live in, YAML parsers don't have security features like
> this.

I'm the author of the "yaml" npm package, and would be interested to hear more
precisely what security features you'd wish for a YAML parser to have. In
other words, if there's one I've missed, I'd like to fix that.

[https://eemeli.org/yaml/](https://eemeli.org/yaml/)

------
selimthegrim
You know what's even worse? IIS config files.

------
synthc
i prefer using EDN for configurations, it has comments and you don't need to
worry about commas and whitespace

------
PaulHoule
That's why you should use YAML.

------
tomc1985
The correct answer here is YAML, folks

------
desc
Thoughts on this:

* Config should never, ever be written by the application which depends on it. Ever. I don't care what you think your rationale is: no application should modify its own configuration.

\- Git is a weird case which springs to mind, but technically `git config` is
separate from eg. `git fetch`. So no real problem there.

\- .NET's bidirectional config bindings are daft. If you stick to reading only
then the framework's fine, but otherwise it rapidly heads into crazytown.

\- If you think you need to violate this rule, probably your 'config' is
actually user data. If so it should be treated as such, ie. it's subject to
data migrations, the admin doesn't need to touch it during upgrades, etc.

* Config needs to be strict. It must be possible to statically verify the basics, and there should not be any confusion over meaning in eg. some random diff.

\- Everything's a string in a text file. The way in which the string is
interpreted must be absolutely unambiguous _and sane_.

\- YAML need never apply.

* Config must not be Turing-complete. Ever. If your configuration can be every conceivable output of a program then you have built a system which is effectively impossible to properly test.

\- I take this one step further and consider it idiotic to include code in a
config file _at all_. It's fine to generate one from other files as part of a
deployment, but the config read by the application _fucking better be a single
static text document_ which maps to a simple data structure, with as little
processing as possible performed after the fact.

* Config needs to be possible to process in a totally reliable way by a deployment process, eg. templating.

\- See above.

* Config should succinctly describe concepts which make sense for configuring the application, not the dozen or so libraries upon which it depends.

\- In .NET terms, this means "don't give us ten megs of 'default' WCF crap to
fiddle with". Give us an endpoint address, and sufficient
documentation/logs/etc to figure out why
'[http://something'](http://something') doesn't work for an app written only
for 'net.tcp://something'.

\- Logging is a weird one. I'd generally handle this by providing app-level
levers for expected logging requirements, then explicitly calling out the
framework and version used and where to find the docs for the advanced stuff.

Given the above, I fail to see anything at all wrong with XML. It has strong
support for schema validation and templating, and can handle any complex data
structure it needs to in both contexts.

Saving keypresses is _not_ a valid excuse. Terse crap is still crap.#

While longwinded pointless junk has given XML a bad name, particularly in the
Java and .NET world, being explicit about things retains stability in the face
of supposedly-unrelated changes: if your configuration's meaning can change
globally if a single rule or heuristic is modified then your software's
reliability is in question.

All it costs is keypresses, and text diffs are very easy to audit in source
control.

Write compact config in anything you must, generate the big stuff, commit it,
record it, audit it. And have CI check that the compact matches the big.

 _Disclaimer: ten years ago I hated XML for wasting so much space. I was an
idiot. These days I 'll take abundant permanent precision over everything._

