YAML Essentials

in Yaml on Yaml
YAML Essentials

This post is an essentials guide about YAML for developers. The YAML syntax is defined with examples on how to use the syntax optimally. Finally, the guide contains links to important YAML websites.

Originally YAML was an acronym for Yet Another Markup Language since its original purpose was to be a document markup language. The three authors, Clark Evans, Ingy döt Net and Oren Ben-Kiki came together in 2001 realising the projects they worked on have a lot in common. They combined their work into a single project known as YAML, a data serialization language. They renamed YAML to YAML Ain't Markup Language which is also a recursive acronym.

YAML is commonly used for configuration files and in applications where data is being stored or transmitted. YAML has very simplistic data types (scalars, lists, arrays..) and data structures (indentation, dashes, colons ..). The extension of a yaml file can either be yml or yaml.

YAML Syntax

Basic Syntax

The YAML syntax uses indentation for a structure (2 spaces, not tabs), dashes for lists and colons for key-value pairs. No duplicate keys are allowed on the same level.

Sequences are lists:

- Item 1
- Item 2

Mappings are key-value pairs:

key1: value1
key2: value2

A sequence of mappings:

- key1: value1
  key2: value2

A mapping of mappings:

overallkey:
  key1: value1
  key2: value2

Block Style employs indentation rather than indicators to denote structure. This results in a more human-readable (though less compact) notation, but is also less compact.

student: "Joe Soap"
university: 
  city: Pretoria
  country: South-Africa
  name: Tukkies
courses: 
  - "Computer Science"
  - Mathematics
  - Physics

Flow Style can be thought of as the natural extension of JSON to cover folding long content lines for readability, tagging nodes to control the construction of native data structures, and using anchors and aliases to reuse constructed object instances.

student: "Joe Soap"
university: { name: Tukkies, city: Pretoria, country: South-Africa}
courses: [Computer Science, Mathematics, Physics]

Comments

An explicit comment is marked by a “#” indicator. Comments must be separated from other tokens by white space characters. Comments are a presentation detail and must not be used to convey content information.

# This is a comment
students: # This is an inline comment
  - Mark McGwire
  - Sammy Sosa
teachers:
  # This is an inline comment
  - Sammy Sosa
  - Ken Griffey

Scalars

YAML provides three flow scalar styles: double-quoted, single-quoted and plain (unquoted). The double-quoted style is specified by surrounding " indicators. This is the only style capable of expressing arbitrary strings, by using \ escape sequences. The single-quoted style is specified by surrounding ' indicators. Therefore, within a single-quoted scalar, such characters need to be repeated. The plain (unquoted) style has no identifying indicators and provides no form of escaping.

The scalar represents strings, integers, dates, and other atomic data types.

strings:
  - double-quoted: "This is a string value"
  - single-quoted: 'This is a string value'
  - unquoted: This is a string value
nulls: 
  - null
  - ~ 
booleans:
  - true: true          # Other values are { Y, true, Yes, ON  }
  - false: false        # Other values are { n, FALSE, No, off }
integers:
  - canonical: 12345
  - decimal: +12345
  - octal: 0o14
  - hexadecimal: 0xC
floating-point:
  - canonical: 1.23015e+3
  - exponential: 12.3015e+02
  - fixed: 1230.15
  - negative_infinity: -.inf
  - not_a_number: .NaN
timestamps:
  - canonical: 2001-12-15T02:59:43.1Z
  - iso8601: 2001-12-14t21:59:43.10-05:00
  - spaced: 2001-12-14 21:59:43.10 -5
  - date: 2002-12-14
block-notation: | 
  Scalar content can be written in block notation, 
  using a literal style (indicated by `|`) where 
  all line breaks are significant.
folded-style: >
  Scalar content can be written with the 
  folded style (denoted by `>`) where each 
  line break is folded to a space unless it 
  ends an empty or a more-indented line.

Structures

YAML uses three dashes --- to separate directives from document content. This also serves to signal the start of a document if no directives are present. Three dots ... indicate the end of a document without starting a new one, for use in communication channels.

---
# Directive 1
cluster_name: 'Test Cluster'
num_tokens: 256
listen_address: localhost
---
# Directive 2
cluster_name: 'Production Cluster'
num_tokens: 1024
listen_address: 192.168.10.1
...

Tags

Tags are used for setting a custom URI, setting local tags and setting a data type.

Global tags are URIs and hence globally unique across all applications. The tag: URI scheme is recommended for all global YAML tags.

Local tags are specific to a single application. Local tags start with !, are not URIs and are not expected to be globally unique. YAML provides a TAG directive to make tag notation less verbose

%TAG ! tag:javanibble.com,2020:
--- !shape 
- !circle       # tag:javanibble.com,2020:circle
  center: {x: 73, y: 129}
  radius: 7

- !line         # tag:javanibble.com,2020:line
  start: {x: 73, y: 129}
  finish: { x: 89, y: 102 }

- !label        # tag:javanibble.com,2020:label
  start: {x: 73, y: 129}
  color: 0xFFEEBB
  text: Pretty vector drawing.

Explicit typing is denoted with a tag using the exclamation point ! symbol.

  • !!map : { Hash table, dictionary, mapping }
  • !!seq : { List, array, tuple, vector, sequence }
  • !!str : Unicode string
  • !!set : { cherries, plums, apples }
  • !!omap : [ one: 1, two: 2 ]
  • !!bool : {true, false}
  • !!null : {null}
  • !!int : Negative numbers (-12), zero (0), positive numbers (34)
  • !!float: negative numbers (-12.3), zero (0), positive numbers (34.3), infinity (.inf), not a number (.nan)
!!map {
  ? !!str "sequence"
  : !!seq [ !!str "one", !!str "two" ],
  ? !!str "mapping"
  : !!map {
    ? !!str "sky" : !!str "blue",
    ? !!str "sea" : !!str "green",
  },
}

# This is equal to:
sequence: 
  - one
  - two
mapping: 
  sea: green
  sky: blue

Anchors

An anchor is denoted by the & indicator. It marks a node for future reference. An anchored node need not be referenced by any alias nodes. An alias node is denoted by the * indicator. The alias refers to the most recent preceding node having the same anchor.

- center: &ORIGIN {x: 73, y: 129}
  radius: 7
- start: *ORIGIN
  finish: { x: 89, y: 102 }
- start: *ORIGIN
  color: 0xFFEEBB
  text: Pretty vector drawing.

Indicators

Indicators are characters that have special semantics:

  • A - hyphen denotes a block sequence entry.
  • A ? question mark denotes a mapping key.
  • A : colon denotes a mapping value.
  • A , comma ends a flow collection entry.
  • A [ left bracket starts a flow sequence.
  • A ] right bracket ends a flow sequence.
  • A { left brace starts a flow mapping.
  • A } right brace ends a flow mapping.
  • An # octothorpe, hash, sharp, pound, number sign denotes a comment.
  • An & ampersand denotes a node’s anchor property.
  • An * asterisk denotes an alias node.
  • The ! exclamation is heavily overloaded for specifying node tags.
  • A | vertical bar denotes a literal block scalar.
  • A > greater than denotes a folded block scalar.
  • An ' apostrophe, single quote surrounds a single-quoted flow scalar.
  • A " double quote surrounds a double-quoted flow scalar.
  • A % percent denotes a directive line.

YAML Example

The following is an example of an invoice defined in YAML. The structure of the invoice is shown through indentation (2 spaces), the sequence or list of items are denoted by a dash, and finally, the all key-value pairs are denoted by a colon.

# Invoice for shipping to the USA.
invoice_nr: '123456'
date: 2020-08-24
company:
  name: The LEGO Group
  address: 
    lines: |
      Højmarksvej 8
      DK-7190 Billund
    country: Denmark
    phone: +45 79 50 60 70
bill_to: &id0001
  contact_person: Amanda Stewart
  client_company: 
    name: Lego World
    address:
      street: 125  Modoc Alley
      city: TERLINGUA
      state: TX 
      zip_code: 79852
ship_to: *id0001
product_items:
  - sku: PI1324A
    description: LEGO NINJAGO Spinjitzu Burst Lloyd - 70687
    quantity: 100
    unit_price: 9,99
    total: 999,00
  - sku: PI1324B
    description: LEGO NINJAGO Spinjitzu Burst Cole - 70685 
    quantity: 100
    unit_price: 9,99
    total: 999,00
tax: 278,00
total: 1998,00
notes: >
  Please only deliver during office hours.
  Ask for Jane Soap at the front desk.
  Alternative contact number is 555-1232

References & Links

Summary

Congratulations! You have completed the post about the essentials of YAML. Follow me on any of the different social media platforms and feel free to leave comments.