What is YAML?

Gbadebo Bello

November 6, 2023· 5 mins

YAML, which stands for “YAML Ain’t Markup Language” or “Yet Another Markup Language,” is a human and machine-readable data serialization format. It is often used for configuration files and data exchange between programming languages with different data structures.

In this article, we’ll walk through the syntax of YAML and discuss some of its key benefits. Then, we’ll explain the difference between YAML and JSON and explore the reasons you might choose one over the other. We’ll also review some common YAML use cases, as well as some best practices for working with it.

What is the structure of YAML?

YAML uses indentation and key-value pairs to present data, making it a human-readable and straightforward data serialization format. YAML documents can represent various data structures, including scalars (strings, numbers, booleans), lists (arrays), dictionaries (maps), and nested structures. Let’s take a look at the YAML document below.

# YAML example with different data structures

person:
    name: John Doe
    age: 30

hobbies:
    - Reading
    - Hiking
    - Cooking

# This is a comment in YAML
favorite_number: 42
is_student: true

description: |
    This is a multi-line
    description in YAML.

# End of YAML example

Here is a breakdown of the basic components and structure of the above YAML document:

• Indentation: YAML uses indentation to indicate the nesting and hierarchy of data. Spaces or tabs are used for indentation, and the number of spaces/tabs is consistent within a YAML document (e.g., two or four spaces per level). Consistency is crucial because YAML relies on indentation for structure. In the above example, the data is indented using four spaces.
• Key-value pairs: In YAML, key-value pairs are used to represent data. The key and value are separated by a colon. In our example, “name” is a key, and “John Doe” is its value.
• Lists (arrays): YAML supports lists or arrays, which are represented using hyphens (“-“). Items in a list are indented with the same number of spaces or tabs to indicate they are part of the list. The hobbies list in the above example must include a minimum of one item, but beyond that, it can have as many items as necessary.
• Dictionaries (maps): YAML allows you to create dictionaries or maps, which are collections of key-value pairs. Think of them as dictionaries in Python or objects in JSON. The person dictionary in our example above has two properties: name and age.
• Scalars: Scalars in YAML are individual values like strings, numbers, booleans, and null. Scalars do not require special syntax; you can write them directly. For instance, favorite_number and is_student in our example are both scalars. You can also represent multiline strings as scalars in YAML without the need for any special syntax, as shown in the description property above.
• Comments: YAML supports comments, which are preceded by the “#” symbol. Comments provide explanatory notes within the YAML document.

What is the difference between YAML and JSON?

YAML files are stored using the .yaml or .yml extension and are designed to be highly portable and human-readable. YAML is a superset of JSON, which means that any valid JSON document is a valid YAML document.

While YAML and JSON serve similar purposes, they have distinct syntax, semantics, and use cases. Some of their differences are highlighted below.

Syntax differences:

• YAML: YAML uses indentation in its data structure, relying on spaces or tabs to indicate nesting. It also uses colons to denote key-value pairs and dashes to represent items in lists.
• JSON: JSON uses a more explicit syntax with curly braces to define objects and square brackets to define arrays. It also uses double quotes for string keys and values.

Readability:

• YAML: YAML is often considered more human-readable due to its use of indentation and minimal punctuation. It closely resembles the way humans naturally structure lists and data.
• JSON: JSON is less readable for humans due to its heavier use of punctuation and explicit syntax. While it’s still relatively straightforward, it’s not as visually intuitive as YAML.

Data types:

• YAML: YAML has native support for more complex data types, including dates and binary data. It also allows for multi-line strings.
• JSON: JSON primarily supports basic data types such as strings, numbers, booleans, arrays, and objects. It doesn’t have native support for dates or binary data.

Usage

• YAML: YAML is often preferred for configuration files, particularly in DevOps and infrastructure-as-code (IaC) scenarios. It’s also used in data serialization and exchange, where human readability is a priority.
• JSON: JSON has native support for many programming languages, which makes it a great fit for data interchange between web services. It is also the preferred format for transmitting data in APIs and web applications.

What can YAML be used for?

YAML has a wide range of use cases across various domains. Its human-readable and machine-friendly structure makes it a popular choice for:

• Configuration files: YAML is commonly used for configuration files in software applications. It allows developers to define settings, parameters, and options in a human-readable format. It is particularly very popular and widely used amongst DevOps and Cloud Native developers.
• API and web services: YAML is used to write API definitions for popular API specifications, such as OpenAPI and AsyncAPI. These specifications are used to describe and document API services.
• Metadata: YAML can be used to store and organize metadata and content structure. Documentation generators, package management tools, LaTex files, and Markdown documents use YAML to describe metadata information.
• Data serialization: YAML is used for data serialization, especially in situations where human readability is essential. JSON  and other data formats can be converted to and from YAML.

What are some best practices for working with YAML?

When working with YAML, it’s important to adhere to the following best practices to ensure data integrity, readability, and compatibility across different systems:

• Consistency: Be consistent in your semantics. For instance, use a consistent number of spaces (commonly two or four spaces) for indentation throughout your YAML file, maintain consistent naming conventions, and uniformly use single or double quotes for strings to avoid ambiguity. Consistency ensures that the document structure is clear and easily understood.
• Use spaces for indentation: While YAML allows both spaces and tabs for indentation, it’s generally recommended to use spaces to avoid potential cross-platform issues.
• Validation: Use YAML linters or validators to catch syntax errors and potential issues in your YAML files. Popular tools like yamllint and IDE extensions can help with this.
• Security: Be cautious when using YAML for configuration, especially in situations where the YAML is auto-generated and contains user input data. Ensure that confidential credentials are not stored in plain text, and implement proper input validation and security measures to prevent potential exploits.
• Modularization: Break large YAML files into smaller, modular files when possible in order to improve maintainability and reusability.