I. Introduction

The design goal of the YAML language (pronounced /ˈjæməl/) is to facilitate human readability and writability. It is essentially a general-purpose data serialization format.

The basic syntax rules are as follows.

  • Case sensitive
  • Use indentation to represent hierarchical relationships
  • Tabs are not allowed for indentation, only spaces are permitted.
  • The number of spaces for indentation is not important, as long as elements at the same level are aligned to the left

# indicates a comment, from this character to the end of the line will be ignored by the parser.

YAML supports three data structures.

  • Object: A collection of key-value pairs, also known as mapping/hashes/dictionary
  • Array: An ordered sequence of values, also known as sequence/list
  • Scalars: Single, indivisible values

These three structures are described below.

II. Object

A set of key-value pairs in an object is represented using a colon structure.

  1. animal: pets

Converted to JavaScript as follows.

  1. { animal: 'pets' }

YAML also allows another notation, writing all key-value pairs as an inline object.

  1. hash: { name: Steve, foo: bar }

Converted to JavaScript as follows.

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

III. Array

A set of lines starting with a hyphen constitutes an array.

  1. - Cat
  2. - Dog
  3. - Goldfish

Converted to JavaScript as follows.

  1. [ 'Cat', 'Dog', 'Goldfish' ]

If the sub-member of the data structure is an array, you can indent a space under that item.

  1. -
  2.  - Cat
  3.  - Dog
  4.  - Goldfish

Converted to JavaScript as follows.

  1. [ [ 'Cat', 'Dog', 'Goldfish' ] ]

Arrays can also be represented using inline notation.

  1. animal: [Cat, Dog]

Converted to JavaScript as follows.

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

IV. Composite Structures

Objects and arrays can be combined to form composite structures.

  1. languages:
  2.  - Ruby
  3.  - Perl
  4.  - Python
  5. websites:
  6.  YAML: yaml.org
  7.  Ruby: ruby-lang.org
  8.  Python: python.org
  9.  Perl: use.perl.org

Converted to JavaScript as follows.

  1. { languages: [ 'Ruby', 'Perl', 'Python' ],
  2.   websites:
  3.    { YAML: 'yaml.org',
  4.      Ruby: 'ruby-lang.org',
  5.      Python: 'python.org',
  6.      Perl: 'use.perl.org' } }

V. Scalars

Scalars are the most basic, indivisible values. The following data types belong to JavaScript scalars.

  • String
  • Boolean
  • Integer
  • Float
  • Null
  • Time
  • Date

Values are represented in literal form.

  1. number: 12.30

Converted to JavaScript as follows.

  1. { number: 12.30 }

Boolean values are represented by true and false.

  1. isSet: true

Converted to JavaScript as follows.

  1. { isSet: true }

null is represented by ~.

  1. parent: ~

Converted to JavaScript as follows.

  1. { parent: null }

Time is represented in ISO8601 format.

  1. iso8601: 2001-12-14t21:59:43.10-05:00

Converted to JavaScript as follows.

  1. { iso8601: new Date('2001-12-14t21:59:43.10-05:00') }

Date is represented using the composite ISO8601 format of year, month, and day.

  1. date: 1976-07-31

Converted to JavaScript as follows.

  1. { date: new Date('1976-07-31') }

YAML allows the use of two exclamation points to forcefully convert data types.

  1. e: !!str 123
  2. f: !!str true

Converted to JavaScript as follows.

  1. { e: '123', f: 'true' }

VI. Strings

Strings are the most common and also the most complex data type.

Strings are not quoted by default.

  1. str: 这是一行字符串

Converted to JavaScript as follows.

  1. { str: '这是一行字符串' }

If a string contains spaces or special characters, it needs to be enclosed in quotes.

  1. str: '内容： 字符串'

Converted to JavaScript as follows.

  1. { str: '内容: 字符串' }

Both single and double quotes can be used, and double quotes will not escape special characters.

  1. s1: '内容\n字符串'
  2. s2: "内容\n字符串"

Converted to JavaScript as follows.

  1. { s1: '内容\\n字符串', s2: '内容\n字符串' }

If there are single quotes within single quotes, two consecutive single quotes must be used to escape.

  1. str: 'labor''s day'

Converted to JavaScript as follows.

  1. { str: 'labor\'s day' }

Strings can be written in multiple lines, and starting from the second line, there must be a single space indentation. Line breaks will be converted into spaces.

  1. str: 这是一段
  2.   多行
  3.   字符串

Converted to JavaScript as follows.

  1. { str: '这是一段 多行 字符串' }

Multiline strings can use | to preserve line breaks or > to fold line breaks.

  1. this: |
  2.   Foo
  3.   Bar
  4. that: >   Foo
  5.   Bar

Converted to JavaScript as follows.

  1. { this: 'Foo\nBar\n', that: 'Foo Bar\n' }

+ indicates preserving the ending line breaks of text blocks, and - indicates removing the ending line breaks of strings.

  1. s1: |
  2.   Foo
  3. s2: |+
  4.   Foo
  5. s3: |-
  6.   Foo

Converted to JavaScript as follows.

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

HTML tags can be inserted within strings.

  1. message: |
  2.   <p style="color: red">     段落
  3.   </p>

Converted to JavaScript as follows.

  1. { message: '\n<p style="color: red">\n  段落\n</p>\n' }

VII. References

Anchors & and aliases * can be used for references.

  1. defaults: &defaults
  2.   adapter:  postgres
  3.   host:     localhost
  4. development:
  5.   database: myapp_development
  6.   <<: *defaults
  7. test:
  8.   database: myapp_test
  9.   <<: *defaults

Equivalent to the following code.

  1. defaults:
  2.   adapter:  postgres
  3.   host:     localhost
  4. development:
  5.   database: myapp_development
  6.   adapter:  postgres
  7.   host:     localhost
  8. test:
  9.   database: myapp_test
  10.   adapter:  postgres
  11.   host:     localhost

& is used to create an anchor (defaults), << indicates merging into current data, and * is used to reference the anchor.

Here is another example.

  1. - &showell Steve
  2. - Clark
  3. - Brian
  4. - Oren
  5. - *showell

Converted to JavaScript as follows.

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