Information for YAML developers

This page lists some helpful resources for people implementing YAML processors

YAML Test Suite

Since 2016, there is an official YAML Test Suite.

It is still in development, but you can use it by pinning to a certain version.

It currently has over 300 test cases that try to cover all kinds of YAML syntax.

YAML Test Matrix

The YAML Test Matrix shows test results for those test cases for various YAML Libraries.

YAML Test Schema

While the YAML Test Suite currently concentrates on Syntax, there is a yaml-test-schema repository for testing the various Schemas for YAML 1.2 and 1.1.

It might get part of YAML Test Suite at some point.

Play with other Libraries

While developing, it can help to look at what other YAML Libraries are doing.

In 2016, Ingy döt Net started the YAML Editor. It has now been split up to YAML Runtimes.

YAML Runtimes contains Dockerfiles for currently 21 different YAML Libraries. It allows you to see the parsing events and JSON output for YAML input.

YAML Editor is built on top of that. It starts Vim inside the container with a split window layout with fancy shortcuts to quickly see YAML input processed by different libraries.

  1 ---                      |+STR                         |+STR
  2 foo: bar                 |+DOC ---                     |+DOC ---
~                            |+MAP                         |+MAP
~                            |=VAL :foo                    |=VAL :foo
~                            |=VAL :bar                    |=VAL :bar
~                            |-MAP                         |-MAP
~                            |-DOC                         |-DOC
~                            |-STR                         |-STR
~                            |~                            |~
~                            |~                            |~
~                            |~                            |~
~                            |<libyaml.event 1,1        All <ibfyaml.event 1,1        All
~                            |{                            |{
~                            |  "foo": "bar"               |  "foo": "bar"
~                            |}                            |}
~                            |~                            |~
~                            |~                            |~
~                            |~                            |~
~                            |~                            |~
~                            |~                            |~
~                            |~                            |~
~                            |~                            |~
~                            |~                            |~
input.yaml     1,1        All js-yaml.json   1,1        All <y-pyyaml.json 1,1        All

Future of YAML

While the YAML 1.2 version was an improvement to 1.1, it still has syntax rules that make it hard to implement.

There is a version 1.3 in planning.

For example one syntax element will very probably be removed: Empty keys

Read more about Empty Keys and other Features in the Main Chapter.

This is just one of the things making developer life easier when it gets removed.

If you start a new YAML library, it might be a good idea to not support empty keys. libyaml/PyYAML and several other libraries ported from them or having bindings don't support them either, and they are probably rarely used.

If you are using the YAML Test Suite, you can simply skip those test cases with the empty-key tag, and in the YAML Test Matrix those cases will show up as "not implemented" instead of a failure.