YAML Complex Keys

Most keys are short words such as name or port. YAML allows far more. A key can be a number, a phrase with spaces, a list, or even a whole mapping. Complex keys solve special problems and appear less often, yet every advanced learner benefits from knowing how they work.

Simple Keys Beyond Words

Keys can contain spaces and symbols. Numbers and booleans work as keys too.

first name: Asha
2026: Election year
true: A boolean key
home-page: index.html

A parser converts the key 2026 into an integer and true into a boolean. Programming languages that require text keys, such as JSON, will convert them back to strings. Quote a key when you need it to stay text.

"2026": Stays text

Duplicate Keys

Each key must appear once inside a mapping. Repeating a key creates ambiguity, and many parsers raise an error or silently keep the last value.

color: red
color: blue

The example above violates the rule. Strict tools report a duplicate key error. Lenient tools return blue and discard red without warning. Both outcomes cause confusion, so avoid duplicates.

The Question Mark Indicator

A question mark followed by a space starts an explicit key. Writing the key this way allows structures that would not fit on a single line.

? name
: Asha

The line with the question mark holds the key. The line with the colon holds the value. Both lines together equal the plain form name: Asha.

Lists as Keys

A list can serve as a key. Think of a chessboard where each square is identified by two numbers: a row and a column. A pair of numbers works as a single address.

? [2, 3]
: Knight
? [0, 4]
: King

      col 0   col 1   col 2   col 3   col 4
row 0   .       .       .       .      King
row 1   .       .       .       .       .
row 2   .       .       .     Knight    .

The key [2, 3] points to row 2, column 3. The value names the piece standing there.

Mappings as Keys

A key can also be a small mapping. Use block style with the question mark:

? city: Pune
  state: Maharashtra
: Population data

The pair of city and state acts as the address of the value. Programming languages must support unhashable or composite keys to load this structure. Python rejects a dictionary as a key, so PyYAML raises an error for this example.

Sets

A set is a group of unique items with no values. YAML represents it with question marks and a set tag.

fruits: !!set
  ? mango
  ? guava
  ? papaya

Each item stands alone as a key without a value. Duplicates cannot exist, which matches the meaning of a set. Python converts this structure into a set object.

Long Keys

YAML limits implicit keys to a single line of 1024 characters. A key longer than that, or one that spans several lines, needs the explicit question mark form.

Where Complex Keys Appear

Use	Example
Coordinates	Grid positions in games and maps
Composite identifiers	Country and city pairs
Sets	Unique tags or permissions
Numeric lookups	Year or code tables

Practical Advice

• Prefer plain text keys for configuration files that humans edit.
• Test complex keys with the exact library your project uses.
• Replace composite keys with a list of mappings when portability matters.

cells:
  - row: 2
    col: 3
    piece: Knight

The final layout carries the same information with plain keys. Every parser and every language can read it, which makes it the safer choice for shared data.