Skip to content

Instantly share code, notes, and snippets.

@bhpayne
Last active April 18, 2021 14:52
Show Gist options
  • Save bhpayne/d4b1a91313ef75db3738e14fce87113a to your computer and use it in GitHub Desktop.
Save bhpayne/d4b1a91313ef75db3738e14fce87113a to your computer and use it in GitHub Desktop.
survey of various markdown/markup formats

Criterion for inclusion: human readable. (which excludes ProtoBuf)

a key / value format where keys can (optionally) be grouped into sections.
cite

; last modified 1 April 2001 by John Doe
[owner]
name=John Doe
organization=Acme Widgets Inc.

[database]
; use IP address in case network name resolution is not working
server=192.0.2.62     
port=143
file="payroll.dat"

XML = Extensible Markup Language = https://en.wikipedia.org/wiki/XML

https://en.wikipedia.org/wiki/Billion_laughs_attack

JSON = JavaScript Object Notation = https://en.wikipedia.org/wiki/JSON

Definition: https://www.json.org/json-en.html

  • Data stored in name/value pairs
  • Records separated by commas. Trailing commas without the following property are not allowed.
  • Double quotes wrap property names & strings. Single quotes are not allowed.
  • multiline Strings are not supported by JSON.
  • Infinity and NaN are not supported in JSON cite

Because JSON does not allow comments, please do not choose JSON as your app’s config file format. For data interchange it’s okay; for config files it’s not. cite

JSON schema: https://json-schema.org/

https://preserves.gitlab.io/preserves/why-not-json.html

JSONc = JSON with comments

Supported by VSCode

https://github.com/Microsoft/node-jsonc-parser and https://komkom.github.io/

  • Single and multi-line comments are allowed.
  • Strings may be single quoted.
  • Strings may span multiple lines by escaping new line characters.
  • Strings may include character escapes.
  • Numbers may be hexadecimal.
  • Numbers may have a leading or trailing decimal point.
  • Numbers may be IEEE 754 positive infinity, negative infinity, and NaN.
  • Numbers may begin with an explicit plus sign.
{
  // comments
  unquoted: 'and you can quote me on that',
  singleQuotes: 'I can use "double quotes" here',
  lineBreaks: "Look, Mom! \
No \\n's!",
  hexadecimal: 0xdecaf,
  leadingDecimalPoint: .8675309, andTrailing: 8675309.,
  positiveSign: +1,
  trailingComma: 'in objects', andIn: ['arrays',],
  "backwardsCompatible": "with JSON",
}

YAML = YAML Ain't Markup Language = https://en.wikipedia.org/wiki/YAML

is a superset of JSON, so you can use fully qualified JSON syntax inside YAML

https://yaml.org/

  • .yml files begin with ---, marking the start of the document

  • key-value pairs are separated by a colon

  • lists start with a hyphen

  • YAML uses indentation with one or more spaces to describe nested collections cite

  • YAML's semantic feature is that it can represent a possibly cyclic graph.

  • YAML mappings can use complex nodes (sequences or mappings) as keys. cite

Downsides:

  • Implicit typing causes surprise type changes. (e.g. put 3 where you previously had a string and it will magically turn into an int).

https://en.wikipedia.org/wiki/Billion_laughs_attack#Variations

tv_shows:
  - Seinfeld
  - 24
  - !!str 90210

The second list item is all digits so may be converted to integers. cite

strictYAML

https://github.com/crdoconnor/strictyaml

StrictYAML does not have a proper specification and only a single implementation
cite

TOML = Tom’s Obvious, Minimal Language = https://en.wikipedia.org/wiki/TOML

multiline strings, auto-escaping of reserved characters, datatypes such as dates, time, integers, floats, scientific notation, and “table expansion”.

Definition: https://github.com/toml-lang/toml

Unlike YAML, TOML doesn’t rely on whitespace with difficult to read indentation. cite

tv_shows = [
  "24",
  "Seinfeld",
  "90210",
]
  • TOML is case sensitive.
  • A TOML file must contain only UTF-8 encoded Unicode characters.
  • Whitespace means tab (0x09) or space (0x20).
  • Newline means LF (0x0A) or CRLF (0x0D0A). cite

TOML's main semantic difference is that it doesn't support cycles, complex keys, or tags.
cite

TOML has a conceptual advantage over YAML: Since its structure allows less freedom, it tends to be easier to read.
cite

TOML's

[a.b.c]
d = 'Hello'
e = 'World'

expands to

  {
    "a": {
      "b": {
        "c": {
          "d": "Hello",
          "e": "World"
        }
      }
    }
  }

SDLang = Simple Declarative Language = https://sdlang.org/

https://github.com/Abscissa/SDLang-D

    // This is a node with a single string value
    title "Hello, World"

    // Multiple values are supported, too
    bookmarks 12 15 188 1234

    // Nodes can have attributes
    author "Peter Parker" email="peter@example.org" active=true

    // Nodes can be arbitrarily nested
    contents {
    	section "First section" {
    		paragraph "This is the first paragraph"
    		paragraph "This is the second paragraph"
    	}
    }

    // Anonymous nodes are supported
    "This text is the value of an anonymous node!"

    // This makes things like matrix definitions very convenient
    matrix {
	1 0 0
	0 1 0
	0 0 1
    }

CSON = CoffeeScript Object Notation

CSON is JSON without the curly braces. CSON instead relies on indentation to determine hierarchy of your data. Multiline strings are easy to write, you can enter comments by starting a line with a hash, and there’s no need for separating key-value pairs with commas.

TOML and YAML comparison

title = "TOML Example"
 
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00
 
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true
 
[servers]
 
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"
   
  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"
   
[clients]
data = [ ["gamma", "delta"], [1, 2] ]
 
hosts = [
  "alpha",
  "omega"
]
title: YAML Example
 
owner:
  name: Tom Preston-Werner
  dob: 1979-05-27T07:32:00-08:00
 
database:
  server: 192.168.1.1
  ports: [ 8001, 8001, 8002 ]
  connection_max: 5000
  enabled: true
 
servers:
 
  alpha:
    ip: 10.0.0.1
    dc: eqdc10
   
  beta:
    ip: 10.0.0.2
    dc: eqdc10
 
clients:
  data: [ [gamma, delta], [1, 2] ]
   
  hosts:
    - alpha
    - omega

From https://gist.github.com/oconnor663/9aeb4ed56394cb013a20

See a useful comparison on https://gohugohq.com/howto/toml-json-yaml-comparison/

XML vs JSON on https://www.barenakedcoder.com/blog/2020/03/config-files-ini-xml-json-yaml-toml/

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment