Click here to Skip to main content
15,918,178 members
Articles / YAML

Learn YAML in five minutes!

Rate me:
Please Sign up or sign in to vote.
5.00/5 (8 votes)
28 Dec 2017CPOL4 min read 148.6K   28   6
This quick read will teach you the basics of YAML markup language in the time it takes to make a cup of tea :)


If you haven't come across YAML yet, hang around a bit and you will, I am seeing it being adopted by a lot of organizations and projects recently and its worth knowing about. YAML is a data-orientated human readable serialization language, and I have come across it in many projects including OpenAPI, Docker, Kubernetes and Ansible playbooks among others.

YAML was originally an acronym for 'Yet Another Markup Language', but is now more commonly referred to as 'YAML Ain't Markup Language' (a bit like GNU is not unix!, or Bing! is not google!). 

The following snapshot illustrates some of the basics we will go through.

Image 1
This article is designed to give you a very brief overview of YAML - enough to get you started there is a lot more and some intricacies which you can find out about on the YAML website.

YAML elements

As you can see from the image above, a YAML file is constructed of a number of different elements. Together, they can be used to describe a wide variety of structures. I have seen YAML used to describe everything from cross language classes, api data structures and deployment instructions for virtual machines and containers. 

YAML elements are mostly based on Key-Value pairs. We may see them as strict KV:

Name: Value

or a a key with a complex/compound value:

Name: < the key<br />
     AnotherName: someValue < the value

YAML is a superset of JSON, so we can utilize JSON style sequences and maps in our constructs:

a_json_style_map: {"K": "V"}<br />
a_json_style_sequence: ["pink", "red", "red", "cat", 123, 234, 345]


Here is a BIG BIG gotcha - this will bite you so know it! ..... in YAML, you indent with spaces, not tabs, in addition, there MUST be spaces between element parts.

For example, this is correct:

Key: Value

but this will fail:

     ^^ no space after the colon!

Begin/End document

Defining the start and end of a document is optional. To  start a document insert '---' at the top of the document, to end it, insert '...'


Comments are defined by placing a hash in front of an item '#'. Comments can be made at the start of a line of anywhere in the line:

# this is a comment<br />
Key: Value   #this another comment


Simple KV pairs come in this category, here are some examples, which are quite varied and flexible.

key: value
someNumber: 299
quotedText: "some text description"
moreQuotedtext: strings do not have to be quoted, but I prefer to do it=
boolean: true
we can also have spaces in keys: and also in values
nullKeyValue: null

Collections & Lists

List and collection members are lines that begin at the same indentation level, starting with a dash followed by a space. 

# a collection of fancy cars<br />
Fancy-Cars<br />
   - Porsche<br />
   - Aston Martin<br />
   - Bentley

Multi-line collections

Complex keys can be catered for by placing a question mark followed by a pipe symbol to flag the start of a complex key:

? |<br />
      starting a complex<br />
      key with many<br />
      lines<br />
: and here comes the value!

Nested collections

You can also have deep nested collections:

# Car information<br />
- Driver<br />
      name: Francis Black<br />
      age: 21<br />
      Driving license type:<br />
          - full car license<br />
          - racing license formula V : details<br />
            license id: ABC12345<br />
            expiry date: 2017-12-28


Dictionaries comprise a key:value format with contents indented.

CarDetails:<br />
     make: Porsche<br />
     model: 911<br />
     fuel: Petrol

You can merge and mix-up collections of lists and dictionaries like this:

# Car information<br />
- Driver<br />
      name: Francis Black<br />
      age: 21<br />
      Driving license type:<br />
          - full car license<br />
          - racing license formula V



That's the very basics, here are some useful resources if you need to dig a bit deeper:

YAML specification
YAML with Ansible
YAML with Kubernetes
Docker compose files and YAML
Wikiwiki on YAML
YAML to JSON convertor online utility
Online YAML parser (you can learn a lot from playing with this!)


Version 1 -  28/Dec/2017


This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Written By
Chief Technology Officer SocialVoice.AI
Ireland Ireland
Allen is CTO of SocialVoice (, where his company analyses video data at scale and gives Global Brands Knowledge, Insights and Actions never seen before! Allen is a chartered engineer, a Fellow of the British Computing Society, a Microsoft mvp and Regional Director, and C-Sharp Corner Community Adviser and MVP. His core technology interests are BigData, IoT and Machine Learning.

When not chained to his desk he can be found fixing broken things, playing music very badly or trying to shape things out of wood. He currently completing a PhD in AI and is also a ball throwing slave for his dogs.

Comments and Discussions

Suggestionتکمیل تسویه Pin
majed khaje11-Jun-24 16:52
majed khaje11-Jun-24 16:52 
QuestionCode Project Pin
Charles Rutabanzibwa2-May-24 21:19
Charles Rutabanzibwa2-May-24 21:19 
QuestionFolks Pin
Ahmad Saferi Mat Said21-Feb-24 18:37
Ahmad Saferi Mat Said21-Feb-24 18:37 
QuestionNice Pin
Member 153087692-Aug-21 1:33
Member 153087692-Aug-21 1:33 
GeneralMy vote of 5 Pin
Clinton Asprey8-May-21 5:49
Clinton Asprey8-May-21 5:49 
QuestionMessage Closed Pin
19-Jul-20 4:51
krutik k19-Jul-20 4:51 
BugRemove </br> s Pin
momt9918-Apr-19 8:08
momt9918-Apr-19 8:08 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.