Table of Contents
introduction
YAML is a recursive acronym for YAML Ain’t Markup Language. YAML is a human-readable data storage format. It acts as a suitable alternative to JSON and XML for most common programming tasks, including network broadcasting and transferring data between languages. It is often used to store configuration data or other information that needs to be edited by a human and processed by a program. In this article, we will review the structure and syntax of a YAML file.
Example of a YAML file
In YAML, a document is a group of objects intended to be analyzed together and saved in a single output.
Below is an example of a GitHub Actions workflow, stored as a YAML document in a single file. This file describes a single workflow job that runs whenever content is pushed to the master branch of a repository. As you can see, the file structure uses Nested junctions (A node is simply an object defined by a line of text in a YAML file) to pass information. Node levels and nesting are managed based on the amount of leading white space before each node, meaning all nodes with the same amount of leading white space are at the same level.
name: AWS-CD
on:
push:
branches:
- master
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: Install Node packages
run: npm install
- name: Build the project
run: npm run build
- name: Deploy to S3
run: AWS_ACCESS_KEY_ID=${{ secrets.AWS_ACCESS_KEY_ID }} AWS_SECRET_ACCESS_KEY=${{ secrets.AWS_SECRET_ACCESS_KEY }} aws s3 sync dist s3://${{ secrets.S3_BUCKET_NAME }}/
This sample job contains several steps:
- Check the current branch
- Install all the Node packages
- Build the project
- Deploy it to an AWS S3 bucket
You can read more about how to use this in our article on continuous deployment to AWS S3.
In this example, the YAML representation is useful because it allows the data that defines this job to be represented clearly and with minimal markup. This makes it easier for developers and programs to figure it out.
YAML mapping
The most common YAML collection is Mapping. It associates a unique key with a particular value. This is similar to maps in Java and dictionaries in Python. Here’s a quick example of a map of capital cities using YAML, where each country is a key and each city is a value:
New York: Albany
Texas: Austin
California: Sacramento
YAML sequences
sequences They are ordered collections of values. They are similar to lists or arrays in most other programming languages. One notable difference from languages like C# and Java, however, is that YAML collections are not strongly typed. A YAML list can contain strings, numbers, and booleans all at once. It is similar to Python and Javascript.
- One
- 2
- 3.45
Sequences and mappings can be nested within each other. Nesting them in this way is done using indentation instead of parentheses, similar to Python’s indented scopes.
sequenceInsideMap:
- anItem
- mapInsideSequenceItem1: a
mapInsideSequenceItem2: b
YAML Scalars
scalars They are single values, as opposed to collections. YAML natively supports strings, integers, floating-point numbers, booleans, dates, and date timestamps:
String: Hello world!
Integer: 42
Float: 12.345
Boolean: true
Date: 2020-12-25
Datetime: 2020-12-25T08:00:00.0Z
These types are usually determined by the application analyzing the data, but you can explicitly define the scalar type using !!type operator, as can be seen below. This ensures that programs that parse arbitrary YAML interpret the content correctly, especially in cases where the parser’s guess is imprecise. For example, without the !!str operator below, a parser will incorrectly interpret this string as a boolean:
word: !!str true
You can also use the null value as a scalar value, by writing null or by omitting a value from a mapping or sequence.
YAML strings
Strings There are some properties not shared by other scalars. First, string literals marked with the vertical bar character | keep all newlines. For example, the following YAML file is equivalent to {"longString": "onentwonthree"} In JSON:
longString: |
one
two
three
You can also use folded scalars >. The difference between the two is that while string literals preserve all newline characters, folded scalars treat newline characters as spaces. For example, the following YAML file is equivalent to {"longString": "one two three"} In JSON:
longString: >
one
two
three
Remarks are marked with a pound sign #. They are not processed by YAML parsers and should be used to provide information to future file managers.
str: Test # This is a comment; its content will not be included in the string
YAML anchors
anchors are used to create a reference to a node – a single object stored in the current YAML file such as a string, mapping. This reference can later be used to iterate over the original node content, allowing YAML file managers to write a node once and reuse it everywhere.
techCompanies:
- Apple
- &AMZN Amazon # “&AMZN” is a node anchor that references the “Amazon” string
- Microsoft
retailCompanies:
- Walmart
- *AMZN # This will be replaced with “Amazon” in the parser output
- Newegg
Start/end of YAML document
As we mentioned above, a document in YAML is a set of objects that are meant to be parsed together and saved in a single output. By default, each file contains only one document, but YAML includes a mechanism for defining multiple documents in one file. A series of three dashes --- Can be used to indicate the beginning of a document, while a series of three dots ... can be used to indicate its end. This is useful for long communication channels or for files that need to contain several separate entries.
---
name: Halloween
date: 2020-10-31
...
---
name: New Year’s Day
date: 2021-01-01
...
Summary
In this article, we discussed the structure and syntax of a YAML file.
If you’re interested in learning more about coding basics, we’ve written the Essential Coding for Developers guide, which covers core coding concepts and tools. It contains chapters on computer architecture, web, command line, HTML, CSS, JavaScript, Python, Java, SQL, Git and more.
We hope you enjoyed this post! Feel free to email me at jacob@initialcommit.io with any questions or comments.
