All About YAML | What is YAML with Example

YAML is a recursive acronym for YAML Ain’t Markup Language earlier known as Yet Another Markup Language. It is a prevalent human-readable serialization language used to configure applications where the requirement is to either transmit or store data. You might know it from Azure DevOps Pipelines, however, it’s not the only popular application that uses it. Ansible, Kubernetes, Docker Compose, CloudFormation, SpringBoot, GitHub Actions etc. are also some of the other popular applications that use it for setting up various configurations.

It has a colon-centered syntax revolving around a key-value structure. Many source code editors provide reading and writing support for YAML, earlier Vim, EMACS now even popular IDEs like Visual Studio Code, IntelliJ, and Eclipse. Its ability to ease into native data structures makes YAML a great choice.

YAML represents scalars such as strings, numbers and booleans, sequences (lists), and mappings (dictionaries or objects). We will see examples of all three. Think of it as giving your configuration a readable address book.

Extensions for YAML

Use either .yaml or .yml as the file extension. In 2024, however, the MIME type, application/yaml was finalized.

So if you are working on any IDE and you want to create a yaml file, you can simply do so if you provide the extension .yaml after the provided name of the document.

An e.g. in VSC:

The editor now recognizes the YAML file. Even if you want to go with the alternative .yml that is also fine:

Structure with Example

A YAML document can start with --- and end with .... These markers are optional for a simple single-document file. Use --- to separate documents in a stream when the consuming application supports multiple documents.

---
 raj: "boy, a male"
 kiran: female
 diwali: true
 days: 2
 distance: 6.6374

The original screenshot below shows the YAML website using YAML itself. Nice! A document marker is not a command to discard arbitrary text above it: invalid content can still cause a parser error.

Nice!

Strings can use single quotes, double quotes, or plain unquoted text when the content permits it. Quote ambiguous values, text containing a colon followed by a space, or a hash preceded by a space.

The parser reads unquoted numbers as integers or floating-point values, depending on the schema. In the above example, we can see the three dashes (—) initiating a YAML after which two string variables are used. The second string showcases that the string is used without any quotes, and the parser still reads it as text.

The third key is a boolean takes a true or false value. But what if true or false should be a string? Then enclose it in the quotes, goddamn it!

The fourth value is an integer.

The fifth value is a floating-point number.

NOTE: The colons follow the key-value pair like JSON and separate the keys from their adjacent pair.

Depicting an Array in Yaml File – Nesting

YAML uses indentation to depict nesting. Use spaces, never tabs for indentation. Two spaces per level is a convenient convention; siblings must align. If I were to continue on the example above and showcase an array, this is how I would do it:

members:
  - Callisto
  - Apocalypto
  - Bjorn

Each dash introduces one entry. The parser reads members as a sequence containing three items.

Create Your First YAML File: One Step at a Time

Step 1: Open your editor and create a file called practice.yaml. The screenshots above show both accepted extensions. Keep this practice file separate from any real deployment configuration.

Step 2: Copy this complete example. Keep the indentation exactly as shown. The spaces are doing actual work here, dude.

name: Scottshak
active: true
experience: 2
profile:
  city: Ahmedabad
  interests:
    - poetry
    - films
    - automation
message: "YAML: now with fewer mysteries"

Step 3: Read it from the outside inward. The top-level mapping has five keys. profile contains another mapping, and interests contains a sequence of three strings. Moving a key back to the left changes its parent.

Step 4: Save the file. Syntax highlighting can help you spot mistakes, but it does not prove the application accepts the configuration. Validate with the YAML support in your editor, then use the target application’s own validation before running anything.

Strings, Booleans and the Quote Trap

In YAML 1.2’s core schema, true and false are booleans. Quoting them makes them strings. Some tools use older YAML rules and can interpret words such as yes or on as booleans. Check your tool’s parser, and quote values you intend to keep as text.

enabled: true
label: "true"
answer: "yes"
version: "1.20"
postal_code: "00123"
missing: null

Here, enabled is a boolean, missing is null, and the quoted values are strings. Quoting a version or postal code preserves its intended text. Otherwise, your carefully chosen zeroes may go on an unannounced vacation.

Comments and Text Across Multiple Lines

Use # for a comment outside a quoted string. Put a space before an inline comment. Use | when line breaks matter, or > to fold ordinary adjacent lines into a paragraph.

retries: 2 # Try twice
message: |
  Hello, dude.
  Keep this on a new line.
summary: >
  This is one paragraph
  spread over two source lines.

Both block styles keep a final newline by default. Use |- or >- when you want to strip it. Blank lines and more-indented lines have additional rules, so test multiline values when formatting matters.

Common YAML Mistakes and How to Fix Them

A parser complains near a colon: Check the line above as well as the reported line. Use a space after the colon separating a key and its value. Quote text like "status: ready".

A list becomes a strange string: Each block list item needs a dash followed by a space. Keep sibling dashes aligned. Use a code block when sharing YAML so a website does not eat its indentation.

The YAML parses, but the tool rejects it: Valid YAML can still contain an unknown key or wrong value type. Docker Compose, GitHub Actions and Kubernetes each define their own configuration structure. YAML supplies the container; the application decides what belongs inside.

A setting disappears: Check for repeated mapping keys. Keys in the same mapping must be unique; parsers may reject duplicates or handle them differently. Keep one unambiguous value.

Try This Before You Leave

Add a fourth interest to the practice file. Change active to false, then to "false". Can you explain the difference? Finally, add a nested tools list under profile. If all three changes make sense, you have the basics.

For the precise language rules, consult the official YAML specification. Start small, keep your spaces in formation, and let the configuration do its job. Nice!