Yaml Best tutorial: Syntax and Configuration Examples

Introduction

YAML (YAML Ain’t Markup Language) is a human-readable data serialization format commonly used for configuration files, data exchange, and structured data representation. This tutorial aims to provide a comprehensive introduction to YAML, covering its syntax, data structures, and configuration examples.

Furthermore, it is possible to convert between YAML and JSON formats.

File structure

YAML files can consist of one or multiple documents, each with its own independent organizational structure. The documents are separated by “—” at the beginning of each document. Additionally, a document can be terminated with “…” as an optional ending marker.

If there is only a single document, the separator “—” can be omitted.

While it is not necessary for each document to have an ending marker “…” to indicate its conclusion, using it can be advantageous for software processing in cases such as network transmission or streaming. It serves as a clear symbol of termination, allowing software to determine the end of a document without needing to know when the stream is closed.

---
receipt:     Oz-Ware Purchase Invoice
date:        2012-08-06
customer:
    given:   Dorothy
    family:  Gale
...

Syntax and Data Structures

online demo

This online demo allows for the validation of YAML syntax and the conversion of YAML to Javascript Obejct (like JSON).

The basic grammar rules are as follows:

Case sensitivity is important.
Indentation is used to represent hierarchical relationships.
Tab key is not allowed for indentation, only spaces are allowed.
The number of spaces for indentation is not important, as long as elements at the same level are aligned to the left.
There should be a space after the colon in key: value pairs.
The “#” symbol is used for comments

YAML supports three types of data structures:

Object: a collection of key-value pairs, also known as mappings/hashes/dictionaries.
Array: a sequence of values arranged in a specific order, also known as sequences/lists.
Scalar: individual, indivisible values.

Object

A set of key-value pairs represented using a colon structure.

animal: pets

# to Javascript object

{ animal: 'pets' }

In addition, Yaml permits an alternative syntax where all key-value pairs are written as a single inline object.

hash: { name: Steve, foo: bar } 

# to Javascript object

{ hash: { name: 'Steve', foo: 'bar' } }

Array

A group of lines starting with conjunctions forms an array.

- Cat
- Dog
- Goldfish

# to Javascript object

[ 'Cat', 'Dog', 'Goldfish' ]

If a submember of a item is an array, it can be indented by one space below that item.

-
 - Cat
 - Dog
 - Goldfish
 
# to Javascript object

[ [ 'Cat', 'Dog', 'Goldfish' ] ]

Arrays can also be represented in-line.

animal: [Cat, Dog]

# to Javascript object

{ animal: [ 'Cat', 'Dog' ] }

Compound structure

it is possible to combine objects and arrays to create composite structures.

address:
 - a: foo1
   b: bar1
 - a: foo2
   b: bar2
languages:
 - Ruby
 - Perl
 - Python 
websites:
 YAML: yaml.org 
 Ruby: ruby-lang.org 
 Python: python.org 
 Perl: use.perl.org 
 
# to Javascript object

{ 
  address: [
    {'a': 'foo1', 'b': 'bar1' },
    {'a': 'foo2', 'b': 'bar2' }
  ],
	languages: [ 'Ruby', 'Perl', 'Python' ],
  websites: { 
     YAML: 'yaml.org',
     Ruby: 'ruby-lang.org',
     Python: 'python.org',
     Perl: 'use.perl.org' 
	}
}

Scalar

In JavaScript, scalar values are the fundamental and indivisible entities. The following data types are all considered scalar values in JavaScript.

string
number
boolean
null
Date

# By default, strings do not use quotation marks, but they can also be enclosed in single or double quotation marks.
string1: foo
string2: 'foo'
string3: "foo"
string4: '1'
string5: ''

number: 12.30

boolean: true

# null
customer:

# ISO 8601 format
# to Javascript Object
# Different converters will lead to different outcomes, with some converting to Date objects and others converting to strings.
# { time: new Date('2001-12-14t21:59:43.10-05:00') }
time: 2001-12-14t21:59:43.10-05:00

# ISO 8601 format
# to Javascript Object
# Different converters will lead to different outcomes, with some converting to Date objects and others converting to strings.
# { date: new Date('1976-07-31') }
date: 1976-07-31

String

By default, strings do not use quotation marks, but they can also be enclosed in single or double quotation marks.

When there is a single quotation mark within single quotation marks, it must be escaped by using two consecutive single quotation marks.

str: 'labor''s day' 

# to Javascript Object

{ str: 'labor\'s day' }

Strings can be written on multiple lines, starting from the second line, with a single space indentation. Line breaks will be converted to spaces.

str: apple
 banana
 c
 
# to Javascript Object

{ str: 'apple banana c' }

| > + –

Multiple-line strings can be preserved with line breaks using “|” and folded with line breaks using “>”.

Blocks represented by “|” and text content indentation: preserve existing line breaks.

Blocks represented by “>” and text content indentation: replace line breaks in the block with spaces, concatenate them into one line, and add a line break at the end of the line.

The “+” symbol denotes the preservation of the line break at the end of a text block, while the “-” symbol signifies the removal of the line break at the end of a string.

this: |
 Foo
 Bar
that: >
 Foo
 Bar
 
# to Javascript Object
 
{ this: 'Foo\nBar\n', that: 'Foo Bar\n' }



s1: |
 Foo

s2: |+
 Foo


s3: |-
 Foo
 
# to Javascript Object

{
  s1: 'Foo\n',
  s2: 'Foo\n\n',
  s3: 'Foo'
}

Blocks represented by delimiters such as double quotes, single quotes, or line breaks are ultimately condensed into a single line, with line breaks replaced by a single space.

a: 
  foo,
  bar
b: 
  "foo,
  bar"
 
# to Javascript Object 

{
  a: 'foo, bar',
  b: 'foo, bar'
}

Type Conversion

More details and examples: https://yaml.org/type/

!!int               # Mathematical integers
!!float             # Floating-point approximation to real numbers
!!bool              # Mathematical Booleans
!!str               # A sequence of zero or more Unicode characters.
!!binary            # A sequence of zero or more octets (8 bit values)
!!timestamp         # A point in time (ISO8601 format) 
!!null              # Devoid of value
!!value             # Specify the default value of a mapping.
!!set               # Unordered set of non-equal values.
!!omap              # Ordered sequence of key: value pairs without duplicates
!!pairs             # Ordered sequence of key: value pairs allowing duplicates     
!!seq               # Sequence of arbitrary values
!!map               # Unordered set of key: value pairs without duplicates
!!merge             # Specify one or more mappings to be merged with the current one

Examples

# The utilization of the !!binary for type conversion involves decoding a base64 encoded string into binary data
image: !!binary |
  R0lGODlhAQABAIAAAP///wAAACwAAAAAAQABAAACAkQBADs=
  

# Explicitly typed set.
baseball players: !!set
  ? Mark McGwire
  ? Sammy Sosa
  ? Ken Griffey
# Flow style
baseball teams: !!set { Boston Red Sox, Detroit Tigers, New York Yankees }

Anchor & Referrence

defaults: &defaults
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  <<: *defaults
  
# equal to

defaults:
  adapter:  postgres
  host:     localhost

development:
  database: myapp_development
  adapter:  postgres
  host:     localhost

Below is another example

- &showell Steve 
- Clark 
- Brian 
- Oren 
- *showell 

# to Javascript Object

[ 'Steve', 'Clark', 'Brian', 'Oren', 'Steve' ]

TOC

1 Introduction
2 File structure
3 Syntax and Data Structures