Introduction
YAML is used for configuration files, blueprints, and also in page settings.
YAML is to configuration what markdown is to markup. It’s basically a human-readable structured data format. It is less complex and ungainly than XML or JSON, but provides similar capabilities. It essentially allows you to provide powerful configuration settings, without having to learn a more complex code type like CSS, JavaScript, and PHP.
YAML is built from the ground up to be simple to use. At its core, a YAML file is used to describe data. One of the benefits of using YAML is that the information in a single YAML file can be easily translated to multiple language types.
YAML Basic Rules
There are some rules that YAML has in place to avoid issues related to ambiguity in relation to various languages and editing programs. These rules make it possible for a single YAML file to be interpreted consistently, regardless of which application and/or library is being used to interpret it.
- YAML files should end in .yaml.
- YAML is case sensitive.
- YAML does not allow the use of tabs.
Basic Data Types
YAML excels at working with mappings (hashes / dictionaries), sequences (arrays / lists), and scalars (strings / numbers). While it can be used with most programming languages, it works best with languages that are built around these data structure types. This includes: PHP, Python, Perl, JavaScript, and Ruby.
Scalars
Scalars are a pretty basic concept. They are the strings and numbers that make up the data on the page. A scalar could be a boolean property, like true, integer (number) such as 5, or a string of text, like a sentence or the title of your website.
Scalars are often called variables in programming. If you were making a list of types of animals, they would be the names given to those animals.
Most scalars are unquoted, but if you are typing a string that uses punctuation and other elements that can be confused with YAML syntax (dashes, colons, etc.) you may want to quote this data using single ‘ or double ” quotation marks. Double quotation marks allow you to use escapings to represent ASCII and Unicode characters.
integer: 25 string: "25" float: 25.0 boolean: true
TIP: Words true, false, null, ~ and dates have special meaning in YAML. Please quote them if you do not want to use them as a boolean, null or datetime type. Same is true with version numbers, they should be quoted to separate them from float values.
Sequences
Here is a simple sequence you. It is a basic list with each item in the list placed in its own line with an opening dash.
- Cat - Dog - Goldfish
This sequence places each item in the list at the same level. If you want to create a nested sequence with items and sub-items, you can do so by placing a single space before each dash in the sub-items. YAML uses spaces, NOT tabs, for indentation. You can see an example of this below.
- - Cat - Dog - Goldfish - - Python - Lion - Tiger
If you wish to nest your sequences even deeper, you just need to add more levels.
- - - Cat - Dog - Goldfish
Sequences can be added to other data structure types, such as mappings or scalars.
Mappings
Mapping gives you the ability to list keys with values. This is useful in cases where you are assigning a name or a property to a specific element.
animal: pets
This example maps the value of pets to the animal key. When used in conjunction with a sequence, you can see that you are starting to build a list of pets. In the following example, the dash used to label each item counts as indentation, making the line items the child and the mapping line pets the parent.
pets: - Cat - Dog - Goldfish
Resources and Further Documentation
For more information about YAML, including detailed documentation about how it works, check out the resources linked below.