A tag says what kind of value a node is. Most nodes have none written, and a schema
decides their type from their kind and form. A plain 123 is an integer under
the core schema, and a plain hello is a string.
Writing a tag
| Form | Example | Meaning |
|---|---|---|
| Secondary handle | !!str | Tag tag:yaml.org,2002:str |
| Primary handle | !local | A local tag, !local, for one application |
| Named handle | !e!foo | The handle !e!’s prefix, from %TAG, followed by foo |
| Verbatim | !<tag:x,1:a> | The tag exactly as written, with no handle |
| Non-specific | ! | Resolves by kind only, so a scalar is a string |
Without a %TAG directive, ! stands for itself and
!! stands for tag:yaml.org,2002:. A named handle must be
declared in the same document. The tag name can contain URI characters and
%XX escapes. A tag written with a handle cannot contain a flow indicator
or a !.
A tag comes before the node, with white space in between. It can be next to an
anchor, in either order: !!map &a or &a !!map. An
alias cannot have a tag.
Schemas
A schema is a set of tags and the rules for resolving nodes that have no tag written. YAML 1.2 defines three.
Failsafe schema
| Tag | Kind |
|---|---|
tag:yaml.org,2002:map | Mapping |
tag:yaml.org,2002:seq | Sequence |
tag:yaml.org,2002:str | String |
Every value is a mapping, a sequence or a string.
JSON schema
Adds the types JSON has. A plain scalar must match one of these patterns, or it is an error:
| Regular expression | Tag |
|---|---|
null | tag:yaml.org,2002:null |
true | false | tag:yaml.org,2002:bool |
-? ( 0 | [1-9] [0-9]* ) | tag:yaml.org,2002:int |
-? ( 0 | [1-9] [0-9]* ) ( \. [0-9]* )? ( [eE] [-+]? [0-9]+ )? | tag:yaml.org,2002:float |
Core schema
The schema that YAML 1.2 readers use by default. Plain scalars are matched against these patterns in order, and anything else is a string:
| Regular expression | Type |
|---|---|
null | Null | NULL | ~ | Null |
| (empty) | Null |
true | True | TRUE | false | False | FALSE | Boolean |
[-+]? [0-9]+ | Integer, base 10 |
0o [0-7]+ | Integer, base 8 |
0x [0-9a-fA-F]+ | Integer, base 16 |
[-+]? ( \. [0-9]+ | [0-9]+ ( \. [0-9]* )? ) ( [eE] [-+]? [0-9]+ )? | Float |
[-+]? ( \.inf | \.Inf | \.INF ) | Float, infinity |
\.nan | \.NaN | \.NAN | Float, not a number |
| anything else | String |
How a node’s tag is resolved
- A tag written on the node is its tag.
- A non-specific tag
!means the kind alone decides: mapping, sequence or string. - Mappings and sequences with no tag are maps and sequences.
- A plain scalar with no tag is matched against the schema’s patterns.
- A quoted or block scalar with no tag is a string.
So "123" is a string and 123 is an integer, and
!!str 123 is a string.
The YAML 1.1 type repository
YAML 1.1 described more types at yaml.org/type. They are not part of the 1.2 schemas, but readers still support many of them.
| Tag | Value |
|---|---|
!!binary | Base 64 binary data |
!!bool | Booleans, including yes, no, on and off |
!!float | Floating-point numbers |
!!int | Integers, in several bases |
!!merge | The merge key, << |
!!null | Null |
!!omap | An ordered mapping |
!!pairs | Key and value pairs that may repeat |
!!set | An unordered set |
!!str | Unicode text |
!!timestamp | A date or date and time |
!!value | The default value of a mapping |
!!yaml | The keys !, & and *, which encode YAML’s own structure inside YAML |
Specification
Tags are in sections 3.2.1.3 and 6.9.1 of YAML 1.2.2, and schemas in chapter 10.