A YAML Primer

Content

A YAML Primer#

What is YAML?#

YAML (short for “YAML Ain’t Markup Language”) is a human-readable data serialization format commonly used for configuration files and data exchange between languages with different data structures. Its simplicity and readability make it a popular choice for defining workflows in platforms like GitHub and GitLab.

Configuration Files: Many applications and services, such as Docker, Kubernetes, and Ansible, use YAML for configuration due to its clear syntax.
Data Serialization: YAML is often used to serialize data structures in programming languages, making it easier to read and write complex data.
API Specifications: Tools like Swagger (OpenAPI) utilize YAML to define API specifications, allowing for easy documentation and sharing of API endpoints.

YAML Syntax#

Tip

We recommend learn YAML in Y minutes for an extensive intro to YAML syntax.

YAML syntax is designed to be easy to read and write. Here are some key elements of YAML syntax:

1. Basic Structure#

Key-Value Pairs: YAML uses a simple key-value pair structure, where keys are followed by a colon and a space.
```
name: John Doe
age: 30
```

¹Using spaces for indentation ensures consistency across different editors and environments, as tabs can be displayed differently depending on the settings of the text editor or IDE. For example, one editor might display a tab as four spaces wide, while another might display it as eight spaces wide. This inconsistency can lead to misaligned code, making it harder to read and maintain.

Nested Structures: Indentation (using spaces, not tabs ¹ ¹Using spaces for indentation ensures consistency across different editors and environments, as tabs can be displayed differently depending on the settings of the text editor or IDE. For example, one editor might display a tab as four spaces wide, while another might display it as eight spaces wide. This inconsistency can lead to misaligned code, making it harder to read and maintain.) is used to represent nested data.

person:
  name: John Doe
  age: 30

3. Strings#

String Formatting: Strings can be written in plain format, or enclosed in quotes (single or double).
```
greeting: "Hello, World!"
farewell: 'Goodbye!'
```
Multiline Strings: Use the pipe (|) for multiline strings, preserving line breaks.
```
descr: |
  A multiline string.
  Retains line breaks.
```

Abbreviated forms

Lists and Dictionaries can be condensed:

start = ["a", "b"]
user = {name: John, job: Developer}

2. Lists#

Lists: Lists are created using a hyphen followed by a space.
```
fruits:
  - Apple
  - Banana
  - Cherry
```

4. Comments#

Comments: Comments start with a # and continue to the end of the line.
```
# A comment
name: John Doe  # Also a comment
```

Conclusion#

YAML’s straightforward syntax and structure make it an ideal choice for configuration files in CI/CD workflows. Its readability facilitates the definition and management of complex workflows in GitHub and GitLab.