A Crash Course on YAML

This post will tell you how we use a simple YAML file to insert the initial data (like roles, privileges, admin user, and all the other necessary data) into our database. We use Play! Framework (Java) with Hibernate. The important part is how we make Objects from the YAML description using SnakeYAML (Play framework’s integrated YAML parser) though.

I’ll give you some tricks on how to use YAML easily in order to create the initial data for your application.

A Crash Course on YAML

‘Rules’ of YAML

NEVER use tabs in your YAML file. The YAML parser will throw a RuntimeException if there is even a single tab in your file.

Care for the file’s indent; the parser is indent sensitive.

I recommend you use 2-4 spaces.


YAML’s Similarity with JSON

YAML has the same expressivity as JSON. There are lots of online JSON to YAML and vice versa converters, so if you are not familiar with the YAML file format you can write your data in JSON and then convert it to YAML. Why is YAML better than JSON? I’ll explain it later in the ‘Comment’ & ‘Aliases’ sections, but first let’s take a look at what a YAML file looks like.




You can add comments to your file by adding a # at the beginning of the line

As opposed to JSON, you can leave comments in YAML. Pretty handy 🙂

YAML elements

In a valid YAML file we can have lists (like a JSON Array), associative arrays (like a JSON Object), and scalars. I’ll call these just as they are in the JSON syntax to avoid further misunderstanding.

Connection with Java classes

If you want to tell the parser that your YAML object is an instance of your JAVA class, simply define its key as !!package.MyClass. The following example is a list of two users.


Aliases are good if you don’t want to copy-paste a lot of boilerplate code (for example, Roles, Privileges, Organization etc.). You can define an alias with the ‘&’ special character, and reference the alias later with the ‘*’ character.

IMPORTANT: This is why YAML is better than JSON – define once & use it all the time.

ALSO IMPORTANT: You can only back-refer with aliases, so you must define the alias before you use it.

Recursion with aliases

You can easily define recursion with aliases. Still note that you can only back-refer.


If you have the following enum for examle, you just refer to it in the YAML file by its name.


Store initial data into the DB

The following code snippet will do all the work for you. The only thing you have to care about is the order of the entity lists. If you want to store an entity that refers another, then you must store the referreditem first, and the referring after (but because of the aliases, this shouldn’t be a problem).



As you see, YAML is an easy way to define your initial data for an application. You don’t need a lot of boiler plate code in your application to parse the YAML and insert the data into the DB, you only have to write the YAML file, and that’s why we love it!


Another way of using YAML

We have another post on using YAML as Swagger documentation, a Swagger doc is an easy way to define the interface between backend and frontend (web or mobile clients, too). I recommend you to take a look at that post too!