To represent an empty value in YAML, decide which kind of empty you mean. Leave the value blank after the colon, or write null or ~, and you get null. Write "" for an empty string, [] for an empty list and {} for an empty map. These four are different types, and a blank value is never an empty string.
The four kinds of YAML empty value
YAML has four distinct empty values: null, the empty string, the empty list and the empty map. Here they are in one file:
middle_name: # null
nickname: ~ # null
suffix: null # null
title: "" # empty string
tags: [] # empty list
labels: {} # empty map
Converted to JSON, that file is {"middle_name": null, "nickname": null, "suffix": null, "title": "", "tags": [], "labels": {}}.
Pick by what the program reading the file expects. Code that loops over tags works with [] and crashes on null; a string method on title needs "" for the same reason.
What the spec says a blank value means
A blank value after the colon is null, because the YAML core schema resolves empty content to the null type. Section 7.2 of the YAML 1.2.2 specification says nodes with empty content "are commonly resolved to a 'null' value." The core schema's resolution table then lists two rows for null: null | Null | NULL | ~, and Empty.
The spec's own example sets the two side by side. Also a null: # Empty is null, while Not a null: "" is a string of length zero. The same section adds that "a null is different from an empty string."
The older YAML 1.1 null type has the same list and names ~ as the canonical form. So this rule did not change between versions, unlike the booleans behind the YAML Norway problem.
Empty values tested in PyYAML and js-yaml
PyYAML 6.0.3 and js-yaml 4.1.0 agree on every empty form I tested. I loaded the same file with yaml.safe_load and with load, then printed the result as JSON:
| You write | PyYAML 6.0.3 | js-yaml 4.1.0 | As JSON |
|---|---|---|---|
key: |
None |
null |
null |
key: ~ |
None |
null |
null |
key: null, Null, NULL |
None |
null |
null |
key: nUll |
string | string | "nUll" |
key: nil |
string | string | "nil" |
key: None |
string | string | "None" |
key: "" or '' |
empty str |
empty string | "" |
key: "null" |
string | string | "null" |
key: [] |
empty list | empty array | [] |
key: {} |
empty dict | empty object | {} |
Two rows catch people. None is not null in YAML, even in Python: PyYAML loads it as the string 'None'. And nil is a plain string too, whatever Ruby or Go habits suggest.
Going the other way, both libraries dump null as the word null and an empty string as ''. Neither writes a blank value or a tilde by default. To see how your own data comes out, paste JSON into the JSON to YAML converter.
The trap: a parent key with nothing under it
A parent key whose children are all removed or commented out becomes null, not an empty map. This is the empty-value bug I'd watch for first, because nobody typed anything wrong:
env:
# DEBUG: "true"
# REGION: eu-west
ports:
- 8080
-
Both parsers load env as null. Code that expected a map and loops over its keys now fails, in Python with 'NoneType' object is not iterable. Write env: {} when you empty a block.
Lists have the same hole. The bare dash under ports is a null entry, so the list has two items: 8080 and null. The YAML 1.1 page shows this deliberately, with a "sparse" sequence that "has five entries, two have values."
A completely empty file is the last case. PyYAML returns None for it and js-yaml returns undefined, so check the result before you index into it. YAML comments explains why the commented lines vanish without a trace.
Null is not the same as a missing key
A key set to null is present with no value, and that is different from leaving the key out. The spec says so directly: a mapping entry with a key and a null value "is valid and different from not having that key in the mapping."
Helm relies on the difference. A chart may ship a default like livenessProbe.httpGet. According to the values-file guide, if you override that key with null, "Helm will remove the key from the overridden values merge." Leaving the key out of your override would keep the default instead.
JSON has the same split, covered in null vs undefined in JSON.
Tools that blur null and empty string
Some tools convert null to an empty string after parsing, so the YAML rule and your application's result can differ. Spring is the well-known case. A framework issue opened on Apr 10, 2017 reported that null or ~ in application.yml reached a String property as "". The loader flattened nulls to empty strings.
That issue was closed on Jan 28, 2026 as superseded. Spring Framework 7.0.4 added a method that lets subclasses control how null and empty values are handled. A maintainer also noted that Spring's Environment cannot store null at all.
This is the limit of everything above. My table shows what two parsers return, and nothing about what your framework does next. When the distinction matters, print the loaded value in the tool that consumes it.
Which form I'd use
My take: write the explicit form every time. Use null for null, "" for an empty string, [] and {} for collections. A blank value and ~ are legal, but a blank looks like a line somebody forgot to finish, and reviewers can't tell which.
Explicit forms also survive stricter schemas. Under the spec's JSON schema only lowercase null is listed as null. In js-yaml's failsafe schema, ~ and null stayed strings in my test while a blank value was still null.
Two related checks: validate the YAML syntax before you debug types, and if the value you need is long text rather than empty, see YAML multiline strings.
FAQ
Is an empty value in YAML null or an empty string?
Null. A key with nothing after the colon resolves to null under the YAML core schema. To get an empty string you have to write a pair of quotes, either "" or ''.
What does the tilde mean in YAML?
The tilde is a short way to write null. In the core schema, ~, null, Null and NULL all resolve to the null type, and so does a blank value.
How do I write an empty list or empty dictionary in YAML?
Use flow style: [] for an empty list and {} for an empty map. A key left blank, or a key whose children are all commented out, is null and not an empty collection.
Is a key with a null value the same as a missing key?
No. The YAML spec says a mapping entry with a key and a null value is valid and different from not having that key. Some tools use the difference: Helm removes a default key when you override it with null.