YAML – Syntax Characters

YAML - Syntax Characters

YAML uses a set of indicator characters to define its structure and features. Understanding these characters is key to writing and reading YAML documents. This chapter outlines the most common syntax characters and their roles.

Indicator Characters

Indicator characters have special meanings that define the structure and content of a YAML document. Here’s a table summarizing them:

Character	Functionality
-	Denotes a block sequence entry (list item).
?	Denotes a complex mapping key in a block mapping.
:	Separates a key from its value in a mapping.
,	Separates entries in a flow collection (flow sequence or flow mapping).
[	Starts a flow sequence (inline list).
]	Ends a flow sequence.
{	Starts a flow mapping (inline dictionary/object).
}	Ends a flow mapping.
#	Denotes a comment. Everything from ’#’ to the end of the line is ignored.
&	Denotes a node’s anchor property (for creating a reusable node).
*	Denotes an alias to an anchored node (for reusing a node).
!	Denotes a node’s tag (for specifying a data type). Can be single ! (application-specific) or double !! (YAML core types).
|	Denotes a literal block scalar (preserves newlines).
>	Denotes a folded block scalar (folds newlines into spaces, preserves paragraph breaks).
’	Single quote: Surrounds a flow scalar, escapes single quotes within by doubling them ('').
”	Double quote: Surrounds a flow scalar, allows C-style escape sequences (e.g., \n, \t).
%	Denotes a directive, like %YAML or %TAG.
---	Document separator, marks the beginning of a new YAML document in a stream.
…	Document end marker, indicates the end of a document in a stream.

The following example demonstrates several of these characters in use:

%YAML 1.2
---
# This is a YAML document demonstrating various syntax characters

# A mapping (dictionary/object)
user_profile:
  name: &user_name "Alice Wonderland" # Anchor for the name
  age: 30
  is_active: true
  roles: # A block sequence (list)
    - admin
    - editor
  contact_info: {email: "alice@example.com", phone: "123-456-7890"} # A flow mapping
  bio: |
    Alice is a curious individual.
    Loves exploring new worlds.
  notes: >
    Prefers tea over coffee.
    Usually available in the mornings.

# Another top-level key referencing the anchored name
primary_contact_name: *user_name # Alias to the name

# A list of tags (strings)
preferred_tags: ["fantasy", "adventure", "classic"]

---
# Start of a second document in the stream
another_item: Simple value
...

This example showcases comments (#), directives (%YAML), document separators (---), mappings (:), block sequences (-), flow collections ({}, []), anchors (&), aliases (*), and block scalars (|, >).