Skip to main content

Written on

Spec-YAML sucks – let's do JNGL.

My secret is that I like YAML – but only a little part of it. The rest is unnecessary, completely bonkers, or dangerous. Yes, I mean that self-proclaimed "human" data format is used in so many CI systems, automation tools, container management systems, and CMSs as front-matter.

Ok, but YAML is fine what's all the buzz about? Let me explain – or rather summarize: Ruud van Asseldonk has a lot of the pitfalls explained for you in his YAML document from hell. Like probably many others, I was bitten by these pitfalls a few times but thought it was bugs in the YAML engine.

Chris Coyier recently summarized the complexity as well and why JSON or TOML is better but isn't that great to be written by humans. That I don't like TOML that much boils down to a personal preference and laziness of mine (and also that weird dot notation for objects).

The simple parts of YAML are fine – I guess.

From my point of view, the unnecessary complexities and the breaking changes between versions are not ok. The simple parts of YAML are great, though. Because they are straightforward to write. For me, they cover my basic data format needs:

Of course, other people have other needs. That's probably why YAML has a ten-chapter spec with multiple versions and breaking changes in between. Instead of "cover all bases" a more simple and easier implementable "cover most bases" would be far better and more useful in my humble opinion.

Since this is my blog, let's look at what I need…

My simplified version of YAML

Everything I need is covered in the list of essential features I already described. A notable definition of the data types would be:

Ok, let's look at an example:

page:
  title: 'Jon said: "That's my cool blog post!"'
  updated: "2023-06-12"
  description: |
    This is a long form text that may span multiple lines and <b>can</b> contain
    markup and stuff. It could **as well** be interpreted as markdown.
  options: ["one", "two", 6, true]
  "personal Rank": 5.00003

# For when you need a different color...
styles:
  - name: "Base theme"
    src: "/assets/site.css"
    empty: null

  - name: "My theme"
    src: "/assets/my-theme.css"
    isAlternate: true

  - {
      name: "My 2nd theme", 
      src: "/assets/my-2nd-theme.css", 
      isAlternate: true,
    }

That would evaluate to a JSON object (or list if you start with a list) as:

{
  "page": {
    "title": "Jon said: \"That's my cool blog post!\"",
    "updated": "2023-06-12",
    "description": "This is a long form text that may span multiple lines and <b>can</b> contain markup and stuff. It could **as well** be interpreted as markdown.",
    "options": [ "one", "two", 6, true ]
    "personal Rank": 5.00003
  },
  "styles": [
    {"name": "Base theme", "src": "/assets/site.css", "empty": null},
    {"name": "My theme", "src": "/assets/my-theme.css", "isAlternate": true},
    {"name": "My 2nd theme", "src": "/assets/my-2nd-theme.css", "isAlternate": true}
  ]
}

That shouldn't be hard to implement. It's essentially a stricter YAMl with all the junk removed. Because it is stricter it shouldn't run into all the boogie traps of the normal YAML but still be parsable by a YAML engine.

Let's name this spec.

I call this format jngl and you may speak that as the English jungle. Why? If find it funny and it's somewhere in between JSON and YAML.