What is a complex mapping key in YAML?

The spec isn't very clear, but after a bit of head-scratching I figured it out. YAML has two kinds of block mapping keys: implicit and explicit. The implicit style is the kind you're familiar with:

mapping:
  foo: 1
  bar baz: 2
  "qux:quux": 3

If we load this YAML in Ruby (for example) we get the following result:

{ "mapping" =>
  { "foo"      => 1,
    "bar baz"  => 2,
    "qux:quux" => 3
  }
}

But we can also use explicit style to express the same thing:

mapping:
  ? foo
  : 1
  ? bar baz
  : 2
  ? "qux:quux"
  : 3

In other words, a line starting with ? indicates a key and a line starting with : indicates a value.

What use is that? Well, it lets us use any YAML structure as a mapping key. Want to use a sequence as a mapping key? You can! Want to use a mapping as a mapping key? Behold:

mapping:
  # Use a sequence as a key
  ? - foo
    - bar
  : 1

  # Use a mapping as a key
  ? baz: qux
  : 2

  # You can skip the value, which implies `null`
  ? quux

  # You can leave the key blank, which implies a `null` key
  ?
  : 3

  # You can even skip both the key and value, so both will be `null`
  ?

  # Or you can use a preposterously long scalar as a key
  ? |
    We the People of the United States, in Order to form a more
    perfect Union, establish Justice, insure domestic Tranquility,
    provide for the common defence, promote the general Welfare,
    and secure the Blessings of Liberty to ourselves and our
    Posterity, do ordain and establish this Constitution for the
    United States of America.
  : 3

  # Or just be ridiculous
  ? - foo: bar
      baz:
      - { qux: quux }
    - stahp
  : 4

In Ruby this would yield the following delightful hash:

{ "mapping" =>
  { [ "foo", "bar" ]   => 1,
    { "baz" => "qux" } => 2,
    "quux"             => nil,
    nil                => nil,
    "We the People of the United States, in Order to form a more\nperfect Union, establish Justice, insure domestic Tranquility,\nprovide for the common defence, promote the general Welfare,\nand secure the Blessings of Liberty to ourselves and our\nPosterity, do ordain and establish this Constitution for the\nUnited States of America.\n" => 3
    [ { "foo" => "bar", "baz" => [ { "qux" => "quux" } ] }, "stahp" ] => 4
  }
}

Oh, and the "Detroit Tigers" example looks like this when Ruby parses it:

YAML.load <<YML
? - Detroit Tigers
  - Chicago cubs
:
  - 2001-07-23

? [ New York Yankees,
    Atlanta Braves ]
: [ 2001-07-02, 2001-08-12,
    2001-08-14 ]
YML
# => { [ "Detroit Tigers", "Chicago cubs" ] =>
#          [ #<Date: 2001-07-23 ((2452114j,0s,0n),+0s,2299161j)> ],
#      [ "New York Yankees", "Atlanta Braves" ] =>
#          [ #<Date: 2001-07-02 ((2452093j,0s,0n),+0s,2299161j)>,
#            #<Date: 2001-08-12 ((2452134j,0s,0n),+0s,2299161j)>,
#            #<Date: 2001-08-14 ((2452136j,0s,0n),+0s,2299161j)> ]
#     }

Just wanted to add that complex mapping also helps if your key is a special char. For example, if your k:v are:

!: "abc"

Such special char key is not allowed So, you do this instead:

? "!"
: "abc"