Syntax
4.3.1. Directives
Directives are instructions to the YAML processor. Like comments, directives are presentation details and are not reflected in the serialization tree (and hence the representation graph). This specification defines two directives, “YAML” and “TAG”, and reserves all other directives for future use. There is no way to define private directives. This is intentional.
[85] l-directive ::= l-yaml-directive | l-tag-directive | l-reserved-directive
Each directive is specified on a separate non-indented line starting with the “%” indicator, followed by the directive name and a space-separated list of parameters. The semantics of these tokens depend on the specific directive. A YAML processor should ignore unknown directives with an appropriate warning.
[86] l-reserved-directive ::= “%” ns-directive-name
( s-ignored-space+ ns-directive-parameter )* s-l-comments
[87]ns-directive-name ::= ns-char+
[88]ns-directive-parameter ::= ns-char+
Example 4.24. Reserved Directives
%FOO
bar
baz
# Should be ignored %YAML 1.1
# with a warning. |
--- !!str |
|
"foo" |
||
--- "foo" |
||
|
Legend:
l-reserved-directive
ns-directive-name
ns-directive-parameter
4.3.1.1. “YAML” Directive
The “YAML” directive specifies the version of YAML the document adheres to. This specification defines version “1.1”. A version 1.1 YAML processor should accept documents with an explicit “%YAML 1.1” directive, as well as documents lacking a “YAML” directive. Documents with a “YAML” directive specifying a higher minor version (e.g. “%YAML 1.2”) should be processed with an appropriate warning. Documents with a “YAML” directive specifying a higher major version (e.g. “%YAML 2.0”) should be rejected with an appropriate error message.
[89] l-yaml-directive ::= “%” “Y” “A” “M” “L” s-ignored-space+ ns-yaml-version s-l-comments
[90] ns-yaml-version ::= ns-dec-digit+ “.” ns-dec-digit+
Example 4.25. “YAML” directive
%YAML 1.2 # Attempt parsing |
%YAML 1.1 |
|
# with a warning |
--- |
|
!!str "foo" |
||
--- |
||
|
||
"foo" |
Legend: |
|
|
||
|
l-yaml-directive ns-yaml-version |
37
XSL• FO
RenderX
Syntax
It is an error to specify more than one “YAML” directive for the same document, even if both occurences give the same version number.
Example 4.26. Invalid Repeated YAML directive
%YAML 1.1 |
ERROR: |
% YAML 1.1 |
The YAML directive must only be |
foo |
given at most once per document. |
4.3.1.2. “TAG” Directive
The “TAG” directive establishes a shorthand notation for specifying node tags. Each “TAG” directive associates a handle with a prefix, allowing for compact and readable tag notation.
[91] l-tag-directive ::= “%” “T” “A” “G” s-ignored-space+ c-tag-handle s-ignored-space+ ns-tag-prefix s-l-comments
Example 4.27. “TAG” directive
%TAG !yaml! tag:yaml.org,2002:↓ |
%YAML 1.1 |
|
--- |
--- |
|
!!str "foo" |
||
!yaml!str "foo" |
||
|
||
|
Legend: |
|
|
l-tag-directive |
|
|
c-tag-handle ns-tag-prefix |
It is an error to specify more than one “TAG” directive for the same handle in the same document, even if both occurences give the same prefix.
Example 4.28. Invalid Repeated TAG directive
%TAG ! !foo %TAG 
! 
!foo bar
ERROR:
The TAG directive must only be given at most once per 
handle 
in the same document.
4.3.1.2.1. Tag Prefixes
There are two tag prefix variants:
[92] ns-tag-prefix ::= ns-local-tag-prefix | ns-global-tag-prefix
38
XSL• FO
RenderX
|
|
|
Syntax |
|
Local Tags |
If the prefix begins with a “!” character, shorthands using the handle are expanded to a local tag beginning |
|||
|
with “!”. Note that such a tag is intentionally not a valid URI, since its semantics are specific to the |
|||
|
application. In particular, two documents in the same stream may assign different semantics to the same |
|||
|
local tag. |
|
|
|
[93] ns-local-tag-prefix ::= “!” ns-uri-char* |
||||
Global Tags |
If the prefix begins with a character other than “!”, it must to be a valid URI prefix, and should contain |
|||
|
at least the scheme and the authority. Shorthands using the associated handle are expanded to globally |
|||
|
unique URI tags, and their semantics is consistent across applications. In particular, two documents in |
|||
|
different streams must assign the same semantics to the same global tag. |
|||
[94] ns-global-tag-prefix ::= ns-tag-char ns-uri-char* |
||||
Example 4.29. Tag Prefixes |
|
|||
%TAG ! |
!foo |
|
%YAML 1.1 |
|
%TAG !yaml! |
tag:yaml.org,2002: |
--- |
||
!!seq [ |
||||
--- |
|
|
||
|
|
!<!foobar> "bar", |
||
- !bar "baz" |
|
|||
|
!<tag:yaml.org,2002:str> "string" |
|||
- !yaml!str "string" |
|
|||
|
] |
|||
|
|
|
||
Legend: |
|
|
|
|
ns-local-tag-prefix |
ns-global-tag-prefix |
|||
4.3.1.2.2. Tag Handles
The tag handle exactly matches the prefix of the affected shorthand. There are three tag handle variants:
[95] |
c-tag-handle ::= |
c-primary-tag-handle |
|
|
|
|
| ns-secondary-tag-handle |
|
|
|
| c-named-tag-handle |
Primary Handle |
The primary tag handle is a single “!” character. This allows using the most compact possible notation |
||
|
|
for a single “primary” name space. By default, the prefix associated with this handle is “!”. Thus, |
|
|
|
by default, shorthands using this handle are interpreted as local tags. It is possible to override this |
|
|
|
behavior by providing an explicit “TAG” directive associating a different prefix for this handle. This |
|
|
|
provides smooth migration from using local tags to using global tags by a simple addition of a single |
|
|
|
“TAG” directive. |
|
[96] |
c-primary-tag-handle ::= “!” |
||
39
XSL• FO
RenderX