Skip to main content

YAML Basic Syntax

In YAML, the documents are a collection of key-value pairs where the value can be complex as a tree or simple as a string.

note

Indentation is fundamental because it represents the structure and it is used to group things that go together.

In indentation, the character will not consider as a part of content information.

Let's describe the basics of YAML syntax.

Rules for Creating YAML file​

When you are creating a file in YAML, you should remember the following basic rules:

  • YAML is case sensitive.
  • The files should have .yaml as the extension.
  • YAML does not allow tabs when creating YAML files; spaces are allowed instead.

Conventional Block Format​

This block format uses hyphen+space (- ) to begin a new item in a specified list.

For example:

--- # Shopping list
- Bread
- Tomatoes
- Aperol

Inline Format​

Inline format is delimited with comma and space (, ) and the items are enclosed in JSON.

--- # Shopping list
- [Bread, Tomatoes, Aperol]

Folded Text​

Folded text converts newlines to spaces and removes the leading whitespace.

- {name: John Smith, age: 33}
- name: Mary Smith
age: 27

The structure which follows all the basic conventions of YAML is shown below:

men: [John Smith, Bill Jones]
women:
- Mary Smith
- Susan Williams

Summary of YAML Basic Elements​

  • Comments in YAML begins with the (#) character.
  • Comments must be separated from other tokens by whitespaces.
  • Indentation of whitespace is used to denote structure.
  • Tabs are not included as indentation for YAML files.
  • List members are denoted by a leading hyphen (-).
  • List members are enclosed in square brackets and separated by commas.
  • Associative arrays are represented using colon ( : ) in the format of key value pair. They are enclosed in curly braces {}. A question mark can be used in front of a key, in the form ?key: value to allow the key to contain leading dashes, square brackets, etc., without quotes.
  • Strings (one type of scalar in YAML) are ordinarily unquoted, but may be enclosed in double-quotes ("), or single-quotes (').
  • Multiple documents with single streams are separated with 3 hyphens (---). Three periods (...) optionally end a document within a stream.
  • Repeated nodes in each file are initially denoted by an ampersand (&) and by an asterisk (*) mark later.
  • YAML always requires colons and commas used as list separators followed by space with scalar values.
  • Nodes should be labelled with an exclamation mark (!) or double exclamation mark (!!), followed by string which can be expanded into an URI or URL.
  • YAML documents in a stream may be preceded by 'directives' composed of a percent sign (%) followed by a name and space-delimited parameters. Two directives are defined in YAML 1.1:
    • The %YAMLv directive is used for identifying the version of YAML in a given document.
    • The %TAG directive is used as a shortcut for URI prefixes. These shortcuts may then be used in node type tags.

Syntax in brief with examples​

Whitespace​

Whitespace indentation is used to indicate nesting and overall structure.

name: Tom Nolan
contact:
    home:   0123456789
    office:  9876543210
address:
  street: |
            123 Main Valley
            Room 16            
    city:   New York
    state:  NY

Comments​

Comments are written beginning with the # symbol.

# This is a YAML Comment

Sequences (called also Lists)​

Hyphen (-) is used to indicate list members with each member on a separate line. List members can also be enclosed in square brackets ([…]) with members separated by commas (,).

- A
- B
- C    
[A, B, C]

Associative Array​

An associative array is surrounded by curly brackets ({…}). The keys and values are separated by colon (:) and each pair is separated by comma (,).

{name: Tom Nolan, age: 23}

Strings​

String can be written with or without double-quotes (") or single-quotes (').

Sample String
"Sample String"
'Sample String'

Scalar Block content​

Scalar content can be written in block notation by using the following:

  • |: All live breaks are significant.
  • >: Each line break is folded to space. It removes the leading whitespace for each line.
data: |
  YAML 
    (YAML Ain't Markup Language)
  is a data-serialization language  
data: ?
  YAML (YAML Ain't Markup Language)
  is a data-serialization language

Multiple Documents​

Multiple documents are separated by three hyphens (---) in a single stream. Hyphens indicate the start of the document. Hyphens are also used to separate directives from document content. The end of the document is indicated by three dots (...).

---
Document 1
---
Document 2
...

Type​

To specify the type of value, double exclamation marks (!!) are used.

a: !!float 123
b: !!str 123

Tag​

To assign a tag to a note, an ampersand (&) is used and to reference that node, an asterisk (*) is used.

name: Tom Nolan
bill-to:  &id01
  street: |
          123 Main Valley
          Room 16          
  city:   New York
  state:  NY

ship-to:  *id01

Directives​

YAML documents can be preceded by directives in a stream. Directives begin with a percent sign (%) followed by the name and then the parameters separated by spaces.

%YAML 1.2
---
Document content

Table of Contents