YAML Dates

Dates appear in schedules, logs, invoices, and release notes. YAML recognizes a date written in a standard pattern and converts it into a date object in many parsers. That behavior helps in some cases and surprises people in others, so understanding the pattern gives you control.

The Standard Date Format

YAML follows the ISO 8601 pattern: four-digit year, two-digit month, two-digit day, separated by hyphens.

birthday: 2000-05-17
launch: 2026-10-22

Year first and day last removes confusion between day-month and month-day styles. The date 03-04-2026 means March 4 in one country and April 3 in another, while 2026-04-03 has exactly one meaning.

Timestamps

A timestamp adds the time of day after a letter T or a space.

created: 2026-10-22T10:30:00Z
updated: 2026-10-22 16:00:00 +05:30
start: 2026-10-22T09:15:00

The letter Z at the end means UTC, the universal reference time. An offset such as +05:30 states the distance from UTC, which matches Indian Standard Time.

Parts of a Timestamp

  2026 - 10 - 22 T 10 : 30 : 00 Z
   |      |    |  |  |    |    |  |
 year  month  day |  hour min sec zone
                 separator

Reading the diagram from left to right follows the natural order from big units to small ones. Sorting these text values alphabetically also sorts them in time order, which makes the format convenient for filenames and logs.

Time Zones in Plain Words

Suffix	Meaning
Z	UTC, the universal reference
+05:30	Five hours thirty minutes ahead of UTC
-08:00	Eight hours behind UTC
(none)	No zone given, so the reader must assume one

Include the zone for events that involve people in different places. A meeting at 10:00 without a zone leaves everyone guessing.

What Parsers Return

PyYAML converts a recognized date into a Python datetime.date object and a timestamp into a datetime.datetime object. JavaScript libraries often return a Date object as well. Programs can then calculate differences, add days, or format the output.

import yaml

data = yaml.safe_load("launch: 2026-10-22")
print(type(data["launch"]))

The output shows a date class instead of a string.

Keeping a Date as Text

Some programs expect a string. Quote the value to stop the conversion:

launch: "2026-10-22"

YAML 1.2 removed timestamps from its core rules, so behavior depends on the library. A file that works in one tool may produce a string in another. Quoting guarantees the same result everywhere.

Lists of Dates

holidays:
  - 2026-01-26
  - 2026-08-15
  - 2026-10-02

Each entry parses as a date. Programs sort them, compare them, and check whether today appears in the list.

Common Mistakes

• Writing 22/10/2026. The slashes make the value plain text.
• Dropping the leading zero, as in 2026-5-7. Some parsers reject it or read it as text.
• Omitting the time zone for global events.
• Mixing date and text formats in one list.

Choosing a Format

Sorting and Comparing

ISO dates sort correctly even as plain text, because the biggest unit comes first. A list of release dates sorts into the right order with a simple alphabetical sort. Programs that receive real date objects compare them directly and calculate the number of days between two entries.

Dates in Configuration Files

Expiry dates for certificates, release dates for software, and start dates for campaigns all appear in configuration files. A tool reads the value, compares it with the current day, and decides what to do. Writing the value in ISO format keeps every tool in the chain in agreement.

Use ISO dates for data that programs process. Quoted text suits display labels such as "22 October 2026" that people read directly. Keep each key in one format across the whole file so every consumer of the data knows what to expect.