-
Notifications
You must be signed in to change notification settings - Fork 16
/
yaml.format.txt
493 lines (372 loc) · 28.6 KB
/
yaml.format.txt
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
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
YAML
ALTERNATIVES ==> #See serialization formats summary
VERSION ==> #1.2
#Extension: .yml, .yaml
PREVIOUS VERSIONS ==> #1.1 backward incompatible differences:
# - null must be 'null' (not ~ nor nothing)
# - no NaN Inf 0... 0x... 0b...
# - no !<TAG> %TAG nor ! (but !!TYPE allowed)
# - no schemas (always use the most advanced one)
# - not 100% JSON compatible:
# - in flow style:
# - VAR max length 1024
# - must use space after colon or comma
# - no \/ (escaping of /)
# - no UTF-32
SUMMARY ==> #Serialization format, concurrent to JSON:
# - JSON superset
# - more human-friendly, indentation-based, comments
# - more featureful, i.e. also more complex and slower (around 4-6 times)
# - can encode many arbitrary|native types (including as object keys):
# - string, boolean, int, float, null, object, array
# - date, binary
# - pairs, sets, unordered maps
# - (with js-yaml) undefined, function, regex, custom types
# - can use references, including circular
# - document-streaming-friendly
# - conceptually close to Python, not to JavaScript
NOTATION ==> +##js-yaml-specific
-##Not supported by js-yaml
|##Not allowed in JSON:
|## - for all, could write custom JSON.stringify() to serialize to STR though
/=+===============================+=\
/ : : \
)==: BASIC SYNTAX :==(
\ :_______________________________: /
\=+===============================+=/
ENCODING ==> #UTF-8 (preferred), UTF-16 or UTF-32.
MIME TYPE ==> #application/yaml, application/x-yaml, text/x-yaml, text/yaml
WHITESPACES ==> #Newline: CR or LF or CRLF
#Whitespace: space or tab
#Blank lines are ignored (except inside STR)
CASE ==> #Case sensitive
NESTED LEVELS ==> #Is newline + indentation:
# - no tabs, only spaces
# - any number of spaces, even if not consistent
#Must be done before any new ARR|OBJ (just like [ or { in JSON), with exceptions:
# - newline optional on new OBJ inside ARR:
# - VAR: VAL same as -
# ... VAR: VAL
# ...
# - indentation optional on new ARR inside OBJ:
# VAR: same as VAR:
# - VAL - VAL
# - ... - ...
# - in precedent exceptions, VAR: VAL can be ? VAR : VAL too
#COMMENT #On its own line, or at end of line
/=+===============================+=\
/ : : \
)==: TYPES :==(
\ :_______________________________: /
\=+===============================+=/
TYPES ==> #Spec divides types into three "kinds":
# - mappings (OBJ-like): !!map !!set
# - sequences (ARR-like): !!omap !!pairs !!seq
# - scalar: all others
#Can create custom TYPEs (how to is implementation-specific):
# - TYPE must be [[:alnum:]-]
SCHEMAS ==> #Set of supported TYPEs, among:
# - failsafe (minimalist): !!map !!seq !!str
# - JSON: also !!null !!bool !!int !!float, but only in their JSON form
# - core: also allows alternative forms of null|BOOL|INT|FLOAT
# - implementation-specific new ones, e.g.:
# - with all spec types (!!set, !!binary, etc.)
# - with language-specific types
#Has impact on performance, see e.g. js-yaml documentation
!<URI> VAR|VAL #Explicitely transtypes VAR|VAL
#URI uses tag: URI scheme, usually tag:DOMAIN,YEAR:TYPE
!!TYPE #Same as !<tag:yaml.org,2002:TYPE>, i.e. for core types, described in this doc
!TYPE #Same as !<tag: local:TYPE>, i.e. for custom types
! #Same as !!map or !!seq or !!str
%TAG !VAL! VAL2 #Make !VAL![...] being same as !<VAL2[...]>
TRANSTYPING ORDER ==> #Implicit transtyping is performed
#The following do not require explicit transtyping, because unambiguous:
# - contains/starts with a specific character: !!str (quoted or unquoted with symbol),
# !!map, !!seq, aliases, exotic
# - specific sets of values: !!null, !!bool, !!int, !!float, !!date, !!merge, !!value
#!!str (unquoted with no symbol):
# - needs transtyping if is any valid value for null|bool|int|float|date
# - best is to just quote
# - cannot:
# - start with " ' { [ @ ` & * -+space ?+space
# - contain :+space
#Always need transtyping:
# - or interpreted as !!map: !!set, !!omap, !!pairs, !!yaml
# - or interpreted as !!str: !!binary, !!js/undefined, !!js/regexp, !!js/function
/=+===============================+=\
/ : : \
)==: OBJECT :==(
\ :_______________________________: /
\=+===============================+=/
VAR: VAL #Is OBJ
... #TYPE !!map
#Mandatory space after colon, unless VAR quoted
#VAR behaves like any STR value:
# - can be quoted or unquoted
# - but has to use ? VAR alternate syntax for multiline
? VAR #Is alternate syntax for OBJ
: VAL # - ? must be followed by space
... # - : VAL must be on next line, same indentation
# - : VAL is optional (def: null)
#Allows VAR to be any VAL, any type
+##(js-yaml) VAR is always parsed as STR
{VAR: VAL,...} #OBJ alternative syntax ("flow style") as opposed to normal syntax ("block style"):
# - difference: the indentation|whitespaces rules for follow JSON not YAML
# - exceptions:
# - can omit {} if only one VAR
# - can use trailing commas
# - can embed flow style inside block style, but not inverse
/=+===============================+=\
/ : : \
)==: ARRAY :==(
\ :_______________________________: /
\=+===============================+=/
- VAL #Is ARR
... #TYPE !!seq
[VAL, ...] #Same as {VAR: VAL,...} (see above)
/=+===============================+=\
/ : : \
)==: SET :==(
\ :_______________________________: /
\=+===============================+=/
? VAR #Is a set, i.e. like OBJ (unordered, no duplicate keys) with no values
... #TYPE !!set
#Requires explicit transtyping
+##(js-yaml) parsed as OBJ with null values
/=+===============================+=\
/ : : \
)==: ORDERED MAP :==(
\ :_______________________________: /
\=+===============================+=/
- VAR: VAL #Is an ordered map, i.e. ordered like ARR but has key-value mapping like OBJ.
... #No duplicate keys
#TYPE !!omap
#Requires explicit transtyping
+##(js-yaml) parsed as ARR containing single-keyed OBJ
/=+===============================+=\
/ : : \
)==: PAIRS :==(
\ :_______________________________: /
\=+===============================+=/
PAIRS ==> #Same as ordered map, except:
# - allow duplicate keys
# - TYPE !!pairs
#Requires explicit transtyping
+##(js-yaml) parsed as ARR containing [KEY, VAL] children
/=+===============================+=\
/ : : \
)==: NULL :==(
\ :_______________________________: /
\=+===============================+=/
null
~ #Is null (case-insensitive)
(nothing) #TYPE !!null
/=+===============================+=\
/ : : \
)==: UNDEFINED :==(
\ :_______________________________: /
\=+===============================+=/
(any scalar VAL) +|##Is undefined
+|##TYPE !!js/undefined, must transtype
+|##Requires explicit transtyping
/=+===============================+=\
/ : : \
)==: BOOLEAN :==(
\ :_______________________________: /
\=+===============================+=/
true|false #Is BOOL (case-insensitive)
#TYPE !!BOOL
on|off -##
yes|no -##
y|n -##Other syntaxes (deprecated), case-insensitive
/=+===============================+=\
/ : : \
)==: INTEGER :==(
\ :_______________________________: /
\=+===============================+=/
INT #Integer
#TYPE !!int
#Can contain _ (with no space after), which are ignored (e.g. used for thousands separator)
#Precision is implementation-specific, but at least four bytes and signed
0b... #Binary
0... #Octal
0x...
0X... #Hex
...:... #Base 60
#Base delimiter can be used several times
/=+===============================+=\
/ : : \
)==: FLOAT :==(
\ :_______________________________: /
\=+===============================+=/
FLOAT #Float
#TYPE !!float
#Can use exponent
#Can use base 60 and _ like INT
#Precision is implementation-specific, but at least single floats
.inf
-.inf |##
nan |##Case-insensitive
/=+===============================+=\
/ : : \
)==: STRING :==(
\ :_______________________________: /
\=+===============================+=/
"..." #String (TYPE !!str), until next unescaped "
'...' #String, until next unescaped '
... #String ("unquoted"), until next non-indented line
|
...
|+
...
|-
...
>
...
>+ #Other forms of unquoted strings ("literal" with |, "folded" with >)
... #Symbol itself:
>- # - is ignored
... # - must be the only chars in first line of STR value, except whitespaces (error otherwise)
|NUM[+|-] #Like |[+|-] or >[+|-] but defines how many spaces is the indentation, i.e. to know
>NUM[+|-] #what is the "additional indentation"
#Def: guessed from initial indented line
ESCAPING/NEWLINES/WHITESPACES ==> #The following rules are observed, by category:
#
# +----------------------------------+----------------------------+
# | Categories | " ' N | |+ |- > >+ >- |
# +------------------+----------------------------------+----------------------------+
# | Transyping | Restrictions (see above) | x |
# +------------------+----------------------------------+----------------------------+
# | Escaping | Backslash sequences | x |
# | | Only escape ' as '' | x |
# | | No need | x x x x x x x |
# +------------------+----------------------------------+----------------------------+
# | Newlines | Always kept | x x x |
# | | Replaced with single space | x x x x x x |
# | | Ignored if force-escaped | x x |
# | | Kept before and after line | |
# | | with additional identation | x x x |
# | | Appended to end | x x x x |
# +------------------+----------------------------------+----------------------------+
# | Whitespaces-only | Replaced with newline | x x x x x x x x x |
# | lines | Ignored at end | x x x x x |
# | | Ignored if force-escaped | x x |
# +------------------+----------------------------------+----------------------------+
# | Whitespaces | Leading ones on first line | x |
# | ignored | Leading ones on other lines | |
# | | - unless force-escaped | x x x |
# | | - except additional indentation | x x x x x x |
# | | Trailing ones | x |
# +------------------+----------------------------------+----------------------------+
#
#Notes:
# - N is unquoted with no symbol
# - "force-escaped" means also escaped following blank lines or indentation
BACKSLASH SEQUENCES ==> # - \" \\ required
# - \0 \a \b \t \n \v \f \r \e
# - \xNN \uNNNN \UNNNNNNNN
# - \/ (same as /)
# - \N (U-0085 NEXT_LINE)
# - \_ (U-00A0 NO_BREAK_SPACE)
# - \L (U-2028 LINE_SEPARATOR)
# - \P (U-2029 PARAGRAPH_SEPARATOR)
# - only way to include Unicode chars that are non-printable, i.e. control chars
# (except \t \n \r), DEL and surrogate block (U-D800 to U-DFFF, U-FFFE, U-FFFF)
/=+===============================+=\
/ : : \
)==: DATE :==(
\ :_______________________________: /
\=+===============================+=/
YYYY-MM-DD[THH:MM:SS[TZ]] |##DATE[TIME]
|##TYPE !!timestamp
|##Can add space instead of T, or before timezone
+|##(js-yaml) parsed as DATE
/=+===============================+=\
/ : : \
)==: BINARY :==(
\ :_______________________________: /
\=+===============================+=/
BASE64_STR #Binary string
#TYPE !!binary
#Uses standard base64 (RFC 4648)
#Requires explicit transtyping
+##(js-yaml) parsed as BUFFER
/=+===============================+=\
/ : : \
)==: REGEXP :==(
\ :_______________________________: /
\=+===============================+=/
REGEXP +|##Is regexp
/REGEXP/FLAGS +|##TYPE !!js/regexp
+|##Does not support ES6 flags
+|##Requires explicit transtyping
/=+===============================+=\
/ : : \
)==: FUNCTION :==(
\ :_______________________________: /
\=+===============================+=/
function [FUNC](...) {...} +|##Is function
... => ... +|##TYPE js/function
+|##Requires explicit transtyping
/=+===============================+=\
/ : : \
)==: EXOTIC :==(
\ :_______________________________: /
\=+===============================+=/
'!': '!...' -##Standardized way to serialize !... or &VAL or *VAL
'&': VAL -##Is just serialization i.e., as is, just like an OBJ
'*': VAL -##TYPE !!yaml
-##Requires explicit transtyping
@...
`... #Both are reserved, so must be escaped|quoted
/=+===============================+=\
/ : : \
)==: ALIASES :==(
\ :_______________________________: /
\=+===============================+=/
&REF VAL #Like VAL, but also assigns it to REF ("alias")
#If VAL:
# - OBJ|ARR: must be on line before
# - multiline STR: must be first on the first line
#Can be:
|## - circular
# - defined several times (last one wins)
-##Has to be used by a *REF
&REF VAR -##Same for VAR
*REF #Reuse REF ("anchor"), by reference (when language permits it)
#Must be after &REF
-##Can be used on VAR too
/=+===============================+=\
/ : : \
)==: MERGES :==(
\ :_______________________________: /
\=+===============================+=/
<<: OBJ[_ARR] #Merge OBJ with siblings
#Has less priority than (either previous|next) siblings
#If OBJ_ARR, applied in turns, i.e. first ones have priority
#Often used with *REF
-##<< actually has special TYPE !!merge
=: VAL -##Same as VAL
-##= actually has TYPE !!value
/=+===============================+=\
/ : : \
)==: STREAMS :==(
\ :_______________________________: /
\=+===============================+=/
--- #First line of a document, optional if only one document in the file.
#Also allows to separate several documents in one file, e.g. for streaming
... #Last line of a document, always optional
BETWEEN STREAMS ==> #There can be directives or comments between ... (or start of file) and --- (or end of file)
/=+===============================+=\
/ : : \
)==: DIRECTIVES :==(
\ :_______________________________: /
\=+===============================+=/
%DIRECTIVE VAL #Directices to parser
#See above about where to put them
#Can be:
# - %YAML VERSION
# - %TAG: see above
#Cannot be custom directives