-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathdocument.yaml
240 lines (219 loc) · 5.94 KB
/
document.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
---
title: Documents
links:
- start: Document Start
- end: Document End
- directive: Directives
sections:
- name: intro
title: Documents
content:
- |
A YAML file or Stream can contain multiple [Documents](#topic:document).
- |
YAML Libraries typically have functions like `load` and `load_all` to read
only one or all documents.
- name: start
title: Document Start
content:
- |
A Document can explicitly be started with `---`. In the specification this
is called the "Directives end marker".
- |
Since directives are not used very often, and a lot of YAML users don't
know they exist, this can be confusing. I will call it "Document Start".
- |
For the first document, the Document Start is optional, but it is also
a way to mark something as YAML explicitly:
- yaml: |
--- # with optional document start marker
invoice number: 314159
name: Santa Claus
address: North Pole
- |
If a file contains multiple documents, they must be separated with the
document start marker:
- yaml: |
--- # The first one is still optional
invoice number: 314159
name: Santa Claus
address: North Pole
---
invoice number: 314160
name: Santa Claus
address: North Pole
---
invoice number: 314161
name: Santa Claus
address: North Pole
- |
The Document Start is usually on its own line. Mappings or Sequences must
start on the next line.
- |
If a document's top level node is a scalar, then it can also start on the same
line:
- yaml: |
--- | # Top Level Block Scalar
line 1
line 2
line 3
--- top
level
plain scalar
- |
In case of top level scalars, it is recommended to always use the document
start marker, and always indent the content. Some libraries don't accept
a top level scalar which is not indented.
- name: end
title: Document End
content:
- |
There is also the Document End Marker `...`.
- |
It is also optional, but useful or recommended in some cases.
- |
<h3>Open Ended Block Scalars</h3>
- |
Sometimes [Block Scalars](#topic:blockscalar) can have trailing newlines:
- yaml: |
block: |+
line 1
line 2
line 3
more: content
- |
In the previous example, the value for `block` will have three trailing
linebreaks.
- |
In the following example, it also has three linebreaks:
- yaml: |+
block: |+
line 1
line 2
line 3
- |
The problem here is, if this is the last item in the file, it might easily happen
that someone editing the file accidentally adds another line at the end or
saves the file without the last line ending.
- |
In these cases, it's recommended to explicitly end the document:
- yaml: |+
block: |+
line 1
line 2
line 3
...
- <h3>Streaming Context</h3>
- |
When YAML is used in a Stream, for example over network, it might be
important to tell the receiver that the document has ended:
- yaml: |
---
invoice number: 314159
name: Santa Claus
address: North Pole
...
# time passes...
---
invoice number: 314160
name: Santa Claus
address: North Pole
...
# time passes...
---
invoice number: 314161
name: Santa Claus
address: North Pole
...
- |
<b>Theoretically</b> it's also possible to only use the Document End Marker
to separate Documents:
- yaml: |
invoice number: 314159
name: Santa Claus
address: North Pole
...
invoice number: 314160
name: Santa Claus
address: North Pole
...
invoice number: 314161
name: Santa Claus
address: North Pole
...
- |
However, that's not supported by all libraries. To be safe, always use the
Document start marker when using multiple documents.
- name: directive
title: Directives
content:
- |
YAML has two [Directives](#topic:directive):
<ul>
<li>YAML Version Directive</li>
<li>YAML Tag Directive</li>
</ul>
- <h3>YAML Version Directive</h3>
- |
The Version directive is used to tell the YAML processor which version
of YAML the document is written in.
- yaml: |
%YAML 1.2
---
a: mapping
- |
If you use a directive, the Document Start Marker must always follow.
That's why in the YAML Specification, it is called "Directives End Marker".
- |
In YAML 1.2, a directive is <b>only</b> applied to the following document,
not to the whole file or stream.
- |
So if you have multiple documents, you need both the Document Start and End
Markers:
- yaml: |
%YAML 1.2
---
invoice number: 314159
name: Santa Claus
address: North Pole
...
%YAML 1.2
---
invoice number: 314160
name: Santa Claus
address: North Pole
...
%YAML 1.2
---
invoice number: 314161
name: Santa Claus
address: North Pole
- <h3>YAML Tag Directive</h3>
- |
Tag Directives are rarely used.
- |
They provide a way to create shorthand tags for custom processing.
- |
An example is the [Unity3d](https://docs.unity3d.com/Manual/YAMLSceneExample.html)
application (which is using YAML 1.1).
- yaml: |
%YAML 1.1
%TAG !u! tag:unity3d.com,2011:
--- !u!header
SerializedFile:
# ...
- |
It maps tags like `!u!header` to `tag:unity3d.com,2011:header`.
- |
There is only <b>one</b> tag directive which always used by default, so you
don't have to specify this in a YAML file:
- yaml: |
%TAG !! tag:yaml.org,2002:
---
# ...
- |
This allows to use the standard YAML tags like `!!int` or `!!bool` in their
short form.
- |
But the standard YAML tags are rarely needed. Read more about Tags and
Schema in the [Schema Chapter](#topic:schema).