YAY (Yet Another YAML) is a human readable, writable, and diffable data document format
npm install libyayA parser for the YAY data format, implemented in JavaScript (ES2024+).
- Node.js 22+ (for Uint8Array.fromHex)
- Or any JavaScript runtime with ES2024 support
``bash`
npm install libyay
`js
import { parseYay } from 'libyay';
// Parse a YAY document
const result = parseYay('key: "value"');
// => { key: "value" }
// Parse with filename for error messages
const data = parseYay(source, 'config.yay');
`
Parses a YAY document string and returns the corresponding JavaScript value.
Parameters:
- source - A string containing the YAY document (UTF-8)filename
- - Optional filename for error messages
Returns: A JavaScript value representing the parsed document.
Throws: Error with line:column location if parsing fails.
| YAY Type | JavaScript Type |
|----------|-----------------|
| null | null |bigint
| big integer | |number
| float64 | |boolean
| boolean | |string
| string | |Array
| array | |Object
| object | |Uint8Array
| bytes | |
The keyword null denotes a null value.
null-literal.yay
`yay`
null
null-literal.js
`js`
null
The literals true and false denote booleans.
A true boolean value.
boolean-true.yay
`yay`
true
boolean-true.js
`js`
true
A false boolean value.
boolean-false.yay
`yay`
false
boolean-false.js
`js`
false
Unquoted decimal digit sequences are big integers (arbitrary precision).
A leading minus sign denotes a negative big integer; the minus must not be followed by a space.
Spaces may be used to group digits for readability; they do not change the value.
A basic positive integer.
integer-big-basic.yay
`yay`
42
integer-big-basic.js
`js`
42n
A negative integer.
integer-big-negative.yay
`yay`
-42
integer-big-negative.js
`js`
-42n
Spaces group digits for readability without changing the value.
integer-big.yay
`yay`
867 5309
integer-big.js
`js`
8675309n
A decimal point must be present to distinguish a float from a big integer.
Decimal literals with a decimal point, or the keywords infinity, -infinity, and nan, denote 64-bit floats.
A leading minus must not be followed by a space.
Spaces may group digits.
A basic floating-point number.
number-float.yay
`yay`
6.283185307179586
number-float.js
`js`
6.283185307179586
A float with a leading decimal point (no integer part).
number-float-leading-dot.yay
`yay`
.5
number-float-leading-dot.js
`js`
0.5
A float with a trailing decimal point (no fractional part).
number-float-trailing-dot.yay
`yay`
1.
number-float-trailing-dot.js
`js`
1
Negative zero is distinct from positive zero.
number-float-negative-zero.yay
`yay`
-0.0
number-float-negative-zero.js
`js`
-0
Positive infinity.
number-float-infinity.yay
`yay`
infinity
number-float-infinity.js
`js`
Infinity
Negative infinity.
number-float-negative-infinity.yay
`yay`
-infinity
number-float-negative-infinity.js
`js`
-Infinity
Not-a-number (canonical NaN).
number-float-nan.yay
`yay`
nan
number-float-nan.js
`js`
NaN
Spaces group digits for readability in floats.
number-float-grouped.yay
`yay`
6.283 185 307 179 586
number-float-grouped.js
`js`
6.283185307179586
Block strings use the backtick ( `) introducer.#
The body continues until the next line that is indented the same or less.
The first two spaces of each content line are stripped; any further indentation is preserved.
Empty lines are interpreted as newlines.
Trailing empty lines collapse to a single trailing newline.
Block strings do not support escape sequences—a backslash is just a backslash.
Comments are also not recognized inside block strings; is literal content.
At root level or as an array item, content may appear on the same line after ` (backtick + space + content).
When the backtick is alone on a line, the result has an implicit leading newline.
Content on the same line as the backtick starts the string without a leading newline.
string-block-root-same-line.yay
`yay I think you ought to know I'm feeling very depressed.
This will all end in tears.
``
string-block-root-same-line.js
`js`
"I think you ought to know I'm feeling very depressed.\nThis will all end in tears.\n"
Backtick alone on its line produces a leading newline because content starts on the following line.
string-block-root-next-line.yay
`yay
I've calculated your chance of survival,
but I don't think you'll like it.
``
string-block-root-next-line.js
`js`
"\nI've calculated your chance of survival,\nbut I don't think you'll like it.\n"
An empty line in the middle of a block string is preserved as a newline.
string-block-empty-middle.yay
`yay
I'm getting better!
No you're not.
``
string-block-empty-middle.js
`js`
"\nI'm getting better!\n\nNo you're not.\n"
The # character inside a block string is literal content, not a comment.
string-block-root-hash.yay
`yay # this is not a comment
it is content
``
string-block-root-hash.js
`js`
"# this is not a comment\nit is content\n"
A block string may be deeply nested and the indentation prefix will be absent
in the value.
The string will end with a single newline regardless of any subsequent newlines
in the YAY text.
string-block-nested-in-object-and-array.yay
`yay
parrot:
condition:
No, no, it's just resting!
remarks:
- Remarkable bird, the Norwegian Blue.
Beautiful plumage, innit?
- It's probably pining for the fjords.
Lovely plumage.
``
string-block-nested-in-object-and-array.js
`js`
({
"parrot": {
"condition": "No, no, it's just resting!\n",
"remarks": [
"Remarkable bird, the Norwegian Blue.\nBeautiful plumage, innit?\n",
"It's probably pining for the fjords.\nLovely plumage.\n",
],
},
})
In property context, the backtick must be alone on the line (no content after it).
There is no implicit leading newline.
The first content line becomes the start of the string.
string-block-property.yay
`yay
message:
By Grabthar's hammer, we live to tell the tale.
``
string-block-property.js
`js`
({
"message": "By Grabthar's hammer, we live to tell the tale.\n",
})
An empty line in the middle of a block string property is preserved.
string-block-property-empty-middle.yay
`yay
message:
It's not pining!
It's passed on! This parrot is no more!
``
string-block-property-empty-middle.js
`js`
({
"message": "It's not pining!\n\nIt's passed on! This parrot is no more!\n",
})
A block string property followed by another property: the block ends when a line at the same or lesser indent appears.
Trailing empty lines collapse to a single trailing newline.
string-block-property-trailing-empty.yay
`yay
message:
By Grabthar's hammer... what a savings.
next: 1
``
string-block-property-trailing-empty.js
`js`
({
"message": "By Grabthar's hammer... what a savings.\n",
"next": 1n,
})
Strings may be quoted with double or single quotes.
Double-quoted strings support escape sequences: \", \\, \/, \b, \f, \n, \r, \t, and \u{XXXXXX} for Unicode code points.
Single-quoted strings are literal (no escape sequences).
A double-quoted string.
string-inline-doublequote-basic.yay
`yay`
"This will all end in tears."
string-inline-doublequote-basic.js
`js`
"This will all end in tears."
A single-quoted string (literal, no escapes).
string-inline-singlequote-basic.yay
`yay`
'Are you suggesting coconuts migrate?'
string-inline-singlequote-basic.js
`js`
"Are you suggesting coconuts migrate?"
A double-quoted string with escape sequences.
string-inline-doublequote-escapes.yay
`yay`
"\"\\\/\b\f\n\r\t\u{263A}"
string-inline-doublequote-escapes.js
`js`
'"\\/\b\f\n\r\t☺'
A double-quoted string with a Unicode emoji (literal UTF-8).
string-inline-doublequote-unicode-emoji.yay
`yay`
"😀"
string-inline-doublequote-unicode-emoji.js
`js`
"😀"
A Unicode code point escape for a character outside the BMP (U+1F600), which requires a surrogate pair in UTF-16.
The \u{...} escape accepts 1 to 6 hexadecimal digits representing a Unicode code point (e.g. \u{41} for "A", \u{1F600} for "😀").\u{...}
Surrogate code points (U+D800 through U+DFFF) are forbidden in escapes.\uXXXX
Unlike JSON, the four-digit form is not supported; use \u{XXXX} instead.
string-inline-doublequote-unicode-surrogate-pair.yay
`yay`
"\u{1F600}"
string-inline-doublequote-unicode-surrogate-pair.js
`js`
"😀"
Arrays are written as a sequence of items, each introduced by - (dash and space).-
The two-character prefix is the list marker; the value follows immediately.-
Items may be nested: a bullet line whose content starts with begins an inner list.:
An array may be given a name as a key followed by .
A basic block array with three integer items.
array-multiline.yay
`yay`
- 5
- 3
array-multiline.js
`js`
[5n, 3n]
Nested arrays where each top-level item contains an inner array.
array-multiline-nested.yay
`yay`
- - "a"
- "b"
- - 1
- 2
array-multiline-nested.js
`js`
[["a", "b"], [1n, 2n]]
An array as the value of an object property.
array-multiline-named.yay
`yay`
complaints:
- "I didn't vote for you."
- "Help, help, I'm being repressed!"
array-multiline-named.js
`js`
({
"complaints": [
"I didn't vote for you.",
"Help, help, I'm being repressed!",
],
})
Inline arrays use JSON-style bracket syntax with strict spacing rules: no space after [, no space before ], exactly one space after each ,.
A simple inline array with string values.
array-inline-doublequote.yay
`yay`
["And there was much rejoicing.", "yay."]
array-inline-doublequote.js
`js`
["And there was much rejoicing.", "yay."]
An inline array containing big integers.
array-inline-integers.yay
`yay`
[42, 404, 418]
array-inline-integers.js
`js`
[42n, 404n, 418n]
An inline array containing byte array literals.
array-inline-bytearray.yay
`yay`
[
array-inline-bytearray.js
`js`
[
Uint8Array.from([0xb0, 0xb5]),
Uint8Array.from([0xca, 0xfe]),
]
Inline arrays nested within an inline array.
array-inline-nested.yay
`yay`
[["I feel happy!", "yay."], ["And there was much rejoicing.", "yay."]]
array-inline-nested.js
`js`
[
["I feel happy!", "yay."],
["And there was much rejoicing.", "yay."],
]
Objects are key–value pairs.
A key is followed by : and then the value.key: {}
Object keys must be either alphanumeric (letters and digits) or quoted (double or single quotes, same rules as string values).
Nested objects are indented by two spaces.
Empty objects are written as .
A simple object with two key-value pairs at the root level.
object-multiline.yay
`yay`
answer: 42
error: 404
object-multiline.js
`js`
({ "answer": 42n, "error": 404n })
An object nested within another object, demonstrating indentation.
object-multiline-nested.yay
`yay`
parrot:
status: "pining for the fjords"
plumage: "beautiful"
object-multiline-nested.js
`js`
({
"parrot": { "plumage": "beautiful", "status": "pining for the fjords" },
})
Object keys containing spaces or special characters must be quoted.
object-multiline-doublequote-key.yay
`yay`
"key name": 1
object-multiline-doublequote-key.js
`js`
({ "key name": 1n })
An empty object as a property value.
object-inline-empty.yay
`yay`
empty: {}
object-inline-empty.js
`js`
({ "empty": {} })
Inline objects use JSON-style brace syntax with strict spacing rules: no space after {, no space before }, exactly one space after each ,.
A simple inline object with integer values.
object-inline-integers.yay
`yay`
{answer: 42, error: 404}
object-inline-integers.js
`js`
({ "answer": 42n, "error": 404n })
An inline object with string and integer values.
object-inline-mixed.yay
`yay`
{name: 'Marvin', mood: 'depressed'}
object-inline-mixed.js
`js`
({ "mood": "depressed", "name": "Marvin" })
An inline object containing both a nested object and an array.
object-inline-nested.yay
`yay`
{luggage: {combination: 12345}, air: ["canned", "Perri-Air"]}
object-inline-nested.js
`js`
({
"air": ["canned", "Perri-Air"],
"luggage": { "combination": 12345n },
})
Block byte arrays use the > introducer (as opposed to <...> for inline).#
Each line may hold hex chunks and comments (comments start with ).
Spaces within hex content are ignored.
At root level or as an array item, hex may appear on the same line after > .>
The leader must have hex digits or a comment on the line—> alone is invalid.
A block byte array at root level with hex on the same line as the > introducer.
bytearray-block-basic.yay
`yay`
> b0b5
c0ff
bytearray-block-basic.js
`js`
Uint8Array.from([0xb0, 0xb5, 0xc0, 0xff])
A block byte array with a comment on the first line instead of hex.
bytearray-block-comment-only.yay
`yay`
> # header comment
b0b5 c0ff
bytearray-block-comment-only.js
`js`
Uint8Array.from([0xb0, 0xb5, 0xc0, 0xff])
Hex and comments on the same lines for inline documentation of byte sequences.
bytearray-block-hex-and-comment.yay
`yay`
> b0b5 # first chunk
c0ff # second chunk
bytearray-block-hex-and-comment.js
`js`
Uint8Array.from([0xb0, 0xb5, 0xc0, 0xff])
In property context, the > must be alone on the line (optionally followed by a comment).
Hex content starts on the following lines, preserving column alignment.
bytearray-block-property.yay
`yay`
data: >
b0b5 c0ff
eefa cade
bytearray-block-property.js
`js`
({
"data": Uint8Array.from([0xb0, 0xb5, 0xc0, 0xff, 0xee, 0xfa, 0xca, 0xde]),
})
A block byte array property with a comment on the leader line.
bytearray-block-property-comment.yay
`yay`
data: > # raw bytes
b0b5 c0ff
bytearray-block-property-comment.js
`js`
({ "data": Uint8Array.from([0xb0, 0xb5, 0xc0, 0xff]) })
Binary data is written as hexadecimal inside angle brackets.
Hexadecimal must be lowercase.
An odd number of hex digits is forbidden.
<> denotes an empty byte array.
Spaces inside the brackets are allowed for readability.
An empty byte array.
bytearray-inline-empty.yay
`yay`
<>
bytearray-inline-empty.js
`js`
new Uint8Array(0)
An inline byte array with hex content.
bytearray-inline-even.yay
`yay`
bytearray-inline-even.js
`js`
Uint8Array.from([0xb0, 0xb5, 0xc0, 0xff, 0xee, 0xfa, 0xca, 0xde])
An inline byte array as an object property value.
bytearray-inline-named.yay
`yay`
data:
bytearray-inline-named.js
`js`
({
"data": Uint8Array.from([0xb0, 0xb5, 0xc0, 0xff, 0xee, 0xfa, 0xca, 0xde]),
})
Errors include line and column numbers for debugging:
`js`
try {
parseYay('invalid: [', 'config.yay');
} catch (e) {
console.error(e.message);
// "Unexpected newline in inline array at 1:11 of
}
YAY has strict whitespace rules that the parser enforces:
- Two spaces for indentation (tabs are illegal)
- No trailing spaces on lines
- Exactly one space after : in key-value pairs,
- Exactly one space after in inline arrays/objects[
- No spaces after or {, or before ] or }
- No space before in keys
`bash`
cd js
node --test yay.test.js
The test runner uses fixture files from ../test/..yay
Files with extension contain YAY input..js` extension contain expected JavaScript output.
Files with
Examples in this document pay homage to:
- The Hitchhiker's Guide to the Galaxy (Douglas Adams)
- Monty Python and the Holy Grail
- Monty Python's Flying Circus ("Dead Parrot" sketch)
- Galaxy Quest
- Spaceballs
- Tommy Tutone ("867-5309/Jenny")
- The Tau Manifesto
Apache 2.0
Copyright (C) 2026 Kris Kowal