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