Yamel and Jason

In a somewhat lengthy spiral of researching self hosted applications, I encountered the Personal Relationship Management system Monica. This application essentially provides a nice interface for keeping track of details about your friends and the conversations you have shared. Monica can be useful if you are living abroad and rarely keep in touch with friends at home, or if you have troubles remembering these things in general. Some might be adverse to this rigor in keeping track of your friends, but I agree with this quote from the author

Call it cheating - I call it caring.

I have previously considered writing down details I want to follow up on next time I speak with someone, especially if I talk to this person monthly or even less freequently. I played around with the web interface of Monica briefly, and it seems rather nice, but also a bit of overkill for my personal use. I keep track of things like phone numbers, birthdays and debts elsewhere, and I essentially just need a few notes of where we left of last time, so I figured I could write this in text files instead of running a full fledged web application.

I have had similar needs in the past when I have been considering how to take notes or write configuration files in a standardized format. I use YAML as preamble for my markdown files, and I know JSON is a popular format for tasks like these, but I haven’t really looked in to comparisons between them, so I decided to briefly survey the qualities of these two formats.

To get an idea of how the two differ, I suggest this great example, which I have copied and modified below. This sample also contains some of the pros and cons of each format:

JSON

{
  "json": [
    "rigid",
    "better for data interchange"
  ],
  "yaml": [
    "slim and flexible",
    "better for configuration"
  ],
  "object": {
    "key": "value",
    "array": [
      {
        "null_value": null
      },
      {
        "boolean": true
      },
      {
        "integer": 1
      }
    ]
  },
  "paragraph": "Blank lines denote\nparagraph breaks\n",
  "content": "Or we\ncan auto\nconvert line breaks\nto save space"
}

YAML

---
json:
    - rigid
    - better for data interchange
yaml:
    - slim and flexible
    - better for configuration
object:
    key: value
    array:
        - null_value:
        - boolean: true
        - integer: 1
paragraph: >
     Blank lines denote

     paragraph breaks
content: |-
     Or we
     can auto
     convert line breaks
     to save space

I definitely prefer YAML’s indented syntax over JSON’s brackets, braces and quotation marks. The YAML example above is close to how I write my notes in markdown already and definitely more readable in my opinion. I enjoy Python’s syntax for the same reason, I believe spatial organisation (here, indentation) makes it easier for humans to navigate text. I should note that I changed the YAML indentation from two to four spaces, but that is just a matter of preference:

The amount of indentation is a presentation detail and must not be used to convey content information.

Additional comparison

I found a few additional pros and cons from these two questions over at StackOverflow:

---
json:
    - ubiqutous among javascript developers
    - potentially allows for duplicate keys
    - annoying quotation of values
    - comments not possible

yaml:
    - easier for humans to read and edit
    - refer to other items with achors
    - allows for comments
    - does not allow duplicate keys
    - not as concise as json
    - lengthy spec that can get complicated

Currently, I am leaning towards YAML for configuration files that are likely to be read and edited by humans, while I would prefer JSON exchanging data between applications. Especially the quotations marks, brackets and braces in JSON would annoy me if I were to edit it by hand.

YAML markdown preamble and jekyll front matter delimiters

YAML uses three dashes (“—”) to separate directives from document content. This also serves to signal the start of a document if no directives are present. Three dots ( “…”) indicate the end of a document without starting a new one, for use in communication channels.

I used to prefer three dots to end YAML blocks, mostly because all the pandoc examples use this style and that it was slightly more convenient in a vim command that I defined. However, since both GitLab and GitHub only support hyphens as the end delimiter for rendering YAML blocks, I have tended towards that syntax lately. I am more and more inclined to use well supported standard and reduce the time I spend on workarounds.

PhD candidate in stem cell bioengineering

Developmental biology researcher and data science educator