Lima Core 1.3 — Normative Specification
Syntax, types, and error behaviour. The single source of truth for what a conforming Core implementation must do.
Status: Final · Version: 1.3.0 · Date: 2026-11-16
This document is the normative specification for Lima Core 1.3. It defines the syntax, semantics, and error behaviour of the Lima frontmatter format. All conforming implementations must produce identical output for any given valid input.
Lima is not a general-purpose data format. It is a small, predictable frontmatter format — the part of YAML that frontmatter actually needs, with well-defined types and no surprises.
Changes from Core 1.2: Lima now reads five forms as YAML front matter writes them. A # begins a comment only at the start of a value or after whitespace (§1), so https://example.org/x#section keeps its #section; \# still yields # (§4, §6.1.4, §8). An entry whose value is only a comment, key: # note, is a bare key, so a block may follow it, as after key:
(§4, §7.1). A tab after the colon separates key and value as a space does (§5.1). An unquoted value that
starts with
&, * or !,
which YAML reads as an anchor, an alias or a tag, throws in strict mode; non-strict mode reads it as a string,
as before (§6.1.1, §10.1). So does a value that is a YAML block scalar header other than
|, such as >, |- or >2
(§6.1.6). Appendix E lists the forms of YAML that Lima does not read, with what a message names for each.
What Core 1.3 reads otherwise than Core 1.2, each named: a value that holds a # after a character other than whitespace, which Core 1.2 cut at the #,
keeps it, in a flow sequence or a flow mapping too (§4); an entry whose value is only a comment, followed by
deeper lines, is the block those lines form, where Core 1.2 read
null
and skipped the lines, or threw in strict mode (§4, §7.1); a line whose colon is followed by a tab, which Core
1.2 did not read as an entry, is one now (§5.1, §5.2, §7.5); in strict mode, a value that starts with
&, * or ! and a value that is a YAML block scalar header other than |
are errors, and a header followed by indented lines is an error at its own line, not at its first indented
line (§6.1.1, §6.1.6). Where Core 1.2 left implementations to differ, Core 1.3 decides: in a flow mapping, the
separator is found before the item is trimmed, so
{k: } is {k: null} (§7.5). Every other value reads as in Core 1.2.
Changes from Core 1.1
(Core 1.2): an unquoted key may be written in any script: it starts with a letter or number of Unicode 18.0 or
with
_, and after its first character it may also hold marks, as accents can be written, and * and ·, as gendered words such as autor*in and autor·in
are written (§5.1). Lima delivers and compares a key as it is written, code point by code point, and
normalises no Unicode (§5.3). A key Core 1.1 recognised reads the same in Core 1.2; a line whose unquoted key
holds characters that Core 1.2 admits and Core 1.1 did not, and which Core 1.1 therefore did not read as an
entry, is an entry now when it otherwise has the form of an entry and stands where an entry may. For clarity,
§1 now says what UTF-8 implies: a string with a lone surrogate is no document, and a parser rejects it. §7.1
states what each kind of line does where it stands in one table, in place of the paragraph that said it in
prose; no outcome changes. In step with it, §6.1.5 and §10.1 say that indented freetext after a bare key
leaves the key
null
only when no later line of its block is a member, as Core 1.1‘s §7.1 already said, and §10.1 lists every other
line the table has strict mode reject.
Errata to Core 1.2:
inline value processing (§4) trims whitespace as §1 defines it, not only spaces, as every value in a block
already did:
draft: false
followed by a no-break space is the boolean. §3 replaces tabs in the run of spaces and tabs at the start of a
line only, as every implementation did: a tab after U+00A0 there stays. Appendix D’s
single-quoted-key-character admits no escape, as §5.2 says: in 'a\'b': x the second ' closes the key, and the line is unrecognised.
Changes from Core 1.0
(errata 1.0.10): strict mode rejects a content line that belongs to no structure, which Core 1.0 skipped in
both modes — a line indented where no block level is open, at the top level as one level down (§7.1 rule 5),
an unindented line that matches no key pattern (§4), and a line of a block mapping whose key the key grammar
rejects (§5.1). Non-strict mode skips these lines, as before. Core 1.1 also settles what Core 1.0 left unsaid,
where implementations differed: a bare key’s sequence may start at the key’s own column, as YAML writes it
(§7.2); a block holds mapping entries or sequence items, as its first entry or item decides, and a line
non-strict mode skips ends neither the block nor the object item before it unless it is less indented (§7.1);
an item whose value is a flow sequence is a nested sequence (§7.2); a
| with no content lines is ''
(§6.1.5); indentation is spaces only, so a line indented by other whitespace, such as U+00A0, is unrecognised
(§7.1), with whitespace defined once (§1); and the end of the input ends the last line as a line terminator
does (§4), so a last
key: is a bare key.
1. Definitions
Document: A UTF-8 encoded string of Lima frontmatter content, without the surrounding ---
delimiters. Stripping delimiters is the caller’s responsibility. Its characters are Unicode scalar values, as
UTF-8 encodes no other: a string that holds a lone surrogate, which some host languages can, is no document,
and a parser rejects it with an error in both modes.
Key: A named field in a Lima document.
Value: The data associated with a key. Values have a type determined by the parsing rules in §6.
Scalar: A single atomic value: string, number, boolean, date, or null.
Block scalar: A multi-line string introduced by a | marker. A block scalar is a scalar, not a block structure.
Block structure: A mapping or sequence written across multiple indented lines.
Mapping: A collection of key-value members. Member order is not semantically significant — consumers must not rely on enumeration order. A formatter may preserve source order.
Sequence: An ordered list of values. Also called an array.
Flow form: An inline mapping ({...}) or sequence ([...]) written on a single line.
Block form: A mapping or sequence written across multiple indented lines.
Whitespace: The characters U+0009, U+000A–U+000D, U+0020, U+00A0, U+1680, U+2000–U+200A, U+2028, U+2029, U+202F, U+205F, U+3000 and U+FEFF — ECMAScript’s WhiteSpace and LineTerminator. A blank line is a line of whitespace only. Indentation is spaces only (§7.1).
UTC Instant: An abstract point in time expressed in UTC with second precision and zero milliseconds. The concrete representation depends on the host language (see §6.5.3).
Reference: A token of the optional References extension (Appendix B): ${document-path}, a document reference, or $(partial-name)
with an optional dotted path, a partial reference, as the References specification defines them. Meaningful
only to a References parser; treated as literal string content by a Lima Core parser.
Strict mode: A parse mode in which a defined set of additional checks are enforced and throw errors instead of falling back silently. See §10.
Non-strict mode: The default parse mode. Tolerant by design — unrecognised syntax is skipped or falls back to a safe value. See §10.
2. Conformance
A conforming Lima Core parser MUST:
- Accept all valid Lima Core syntax as defined in this document.
- Produce the output types specified in §6.
- Enforce all resource limits specified in §9.
- Implement both strict and non-strict mode as specified in §10.
- Produce identical output for identical input, regardless of implementation language.
A conforming Lima Core parser MUST NOT:
- Accept syntax not defined in this document without falling back as specified.
- Silently produce incorrect values (e.g. normalising invalid dates, misidentifying types).
- Rely on host-language-specific behaviour for parsing numbers or dates.
-
Emit warnings to implicit output channels (e.g. console). All diagnostics must be delivered via the
onWarningcallback (see §11.2).
3. Input Normalisation
Before parsing, the input MUST be normalised in the following order:
- Line endings: All
\r\nsequences are replaced with\n. All remaining standalone\rcharacters are replaced with\n. - Tabs in leading indentation:
In the run of spaces and tabs (U+0020, U+0009) at the start of a line, each tab is replaced with two spaces
(
). Every other tab is left unchanged, one after other whitespace of §1 included: a line that starts with U+00A0 and a tab keeps the tab. - Trailing whitespace: Trailing spaces on each line are removed.
Normalisation applies to the entire document before any other processing. These steps are unconditional and apply in both strict and non-strict mode.
4. Document Structure
A Lima document consists of zero or more top-level key-value pairs. Keys must start at column 0 (no leading indentation). Each key-value pair has the form:
key: value
or, for block values:
key:
block content
The separator between key and value is a colon followed by a space or a tab for inline values, or
:\n
(colon followed by a newline) for block values. Whitespace after the separator is ignored (step 3 below); it
makes no separator:
key:
followed by U+00A0 and a value has no separator and is unrecognised (§5.1). The end of the input ends the last
line as a line terminator does: a last
key: is a bare key, null
without a block. An entry whose value is empty after comment removal and trimming (steps 2 and 3 below) is a
bare key too:
key: # note may be followed by the key’s block, as key: may (§7.1). key: null and key: '' are entries with an inline value, not bare keys.
Inline value processing: The inline value scanner processes the full source value while respecting quote boundaries:
- Scan left-to-right, tracking quoted regions (single and double quotes with their respective escape rules).
- The first
#outside a quoted region that is not escaped (§6.1.4) and that is the first character of the value or follows whitespace (§1) begins a comment — it and everything following it are removed. Any other#is text: a#after U+0085, which §1 does not count as whitespace, is text too. The scan runs once over the whole source value, a flow sequence or a flow mapping included (§7.4, §7.5), and looks at the character physically before the#: in[a,#x]and[#x]the#follows,or[and is text, so the items areaand#x; in[a, #x]it follows a space and begins a comment, which leaves[a,unclosed. - Trim leading and trailing whitespace (§1) from the remaining text.
- If the remaining text begins with a quote character, it is a quoted value only when the matching closing quote is the final remaining character after trimming. Any non-whitespace content after the closing quote is invalid: non-strict mode falls back to a string (the entire remaining text), strict mode throws.
- For quoted values: strip the surrounding delimiters and apply the appropriate escape processing (see §6.1.2, §6.1.3). Content inside the quotes is never trimmed or further comment-stripped.
-
For unquoted values: trim leading and trailing whitespace again (a second trim, to handle trailing
whitespace left after comment removal). If the result is empty, produce
null. Apply scalar type conversion.
Examples:
title: "Hello # world" # comment # → 'Hello # world' (# inside quotes is literal; outer comment stripped)
title: "Hello" # comment # → 'Hello' (closing quote is final; outer comment stripped)
title: "Hello" trailing # → error/fallback (non-whitespace after closing quote)
title: Hello World # comment # → 'Hello World' (unquoted; both trims applied)
title: 42 # comment # → 42 (number after double trim)
link: https://example.org/x#top # → 'https://example.org/x#top' (no space before the first #: text)
color: #ff0000 # → null (# at the start of the value: comment)
title: "Hello"# comment # → error/fallback (no space before #: content after closing quote)
An unindented line that does not match any key pattern, and is no item of a compact sequence (§7.2), is unrecognised: non-strict mode skips it silently, strict mode throws (see §10.1). An indented line that is not part of a block value is inconsistently indented (§7.1 rule 5).
5. Key Syntax
5.1 Unquoted Keys
An unquoted key starts with a letter, a number or _. After that it holds letters, marks, numbers and the characters _, :, -, * and · (U+00B7 MIDDLE DOT):
key-initial a letter or a number of any script, or _
key-character a key-initial, a mark, or one of : - * ·
Letters, marks and numbers are the characters whose general category in the Unicode Character Database 18.0.0 is L, M or N; numbers include more than decimal digits, such as Roman numerals. The version is fixed, so that every implementation reads a key alike, whatever version of Unicode its host language knows: a character that Unicode 18.0 does not assign is no letter, mark or number. Whitespace (§1), control characters and format characters, among them U+200B–U+200F and the bidirectional controls U+202A–U+202E and U+2066–U+2069, are in none of these categories and in no unquoted key; a key that holds them must be quoted (§5.2).
Valid examples: title, firstName, h1, _draft, snake_case, kebab-case, og:title, 1st, 42, größe, título, autor:in, autor*in, autor·in, заголовок, 題名
Key-value separator rule: Since unquoted keys may contain colons, the key-value separator is the first colon followed by a space or a tab (U+0020, U+0009), or by a newline or the end of the input (§4), that is not inside a quoted key. Everything before it is the key; everything after is the value.
A line with a separator whose key matches neither this pattern nor a quoted key (§5.2) is unrecognised (§4): skipped in non-strict mode, an error in strict mode — at the top level and in a block mapping alike.
Examples:
og:title: Hello # key = 'og:title', value = 'Hello'
a:b:c: value # key = 'a:b:c', value = 'value'
title: Hello # key = 'title', value = 'Hello' (extra space trimmed)
title:\tHello # key = 'title', value = 'Hello' (a tab separates as a space does)
5.2 Quoted Keys
Keys containing spaces or other characters not permitted in unquoted keys must be quoted. Both single and double quotes are supported.
'first name': Alice
"display name": Bob
'key: with colon': value
'': empty string key
- Single-quoted keys are literal. No escape processing.
- Double-quoted keys decode the same backslash escape sequences as double-quoted string values (see §6.1.2).
The key in the output object is the content between the quotes — delimiters are stripped. After the closing quote, the separator must follow immediately: a colon followed by a space, a tab, a newline or the end of the input (§4). A space between the closing quote and the colon is not valid.
"first name": Alice # valid
"first name" : Alice # invalid — space before colon
Non-strict: treat as unrecognised line, skip. Strict: throw.
A raw line terminator inside a quoted key is not a valid quoted-key character (§15.6, which excludes U+000A
from both single- and double-quoted-key characters). A physical line whose quoted key does not close on that
same line is unrecognised (§4): skipped in non-strict mode, an error in strict mode. The
\n
escape in a double-quoted key is unaffected: it decodes to a key containing U+000A, exactly as in a
double-quoted value.
5.3 Duplicate Keys
Duplicate keys are invalid at all mapping levels (top-level, nested maps, flow mappings, object arrays), with mode-dependent handling:
- Non-strict: Emit a warning via
onWarning. Last value wins. - Strict: Throw. Error message includes the key name and 1-based line number.
Two keys are the same key when they are the same sequence of code points. Lima normalises no Unicode:
größe written with U+00F6 and größe written with o
and U+0308 COMBINING DIAERESIS are two keys, and each is delivered as it is written. A consumer that wants
them to be one normalises the keys itself.
Duplicate detection and resource limit counting (§9) both occur at parse time, before duplicate resolution. Each recognised key entry increments the counter and is checked for duplication independently.
6. Value Types
Lima automatically converts scalar values to their most natural type. Conversion order: null → boolean → number → date → string (fallback).
6.1 Strings
6.1.1 Unquoted Strings
Any value that does not match null, boolean, number, or date is a string.
An unquoted value whose first character is &, * or !
is what YAML reads as an anchor, an alias or a tag, which Lima does not have (Appendix A). Non-strict mode
reads it as a string. Strict mode throws, and the message names the cure: quote the value. This holds for
every unquoted value: an inline value, an item, and a value in a flow sequence or a flow mapping.
note: *new* # non-strict → '*new*'; strict → error (quote it: '*new*')
note: '*new*' # → '*new*'
Inline comments and whitespace are processed according to the complete pipeline defined in §4 (inline value processing). See §8 for comment syntax.
6.1.2 Double-Quoted Strings
A value enclosed in matching double quotes ("...") is a string. Type coercion is not applied. The following backslash escape sequences are decoded:
| Escape | Result |
|---|---|
\\ |
backslash |
\" |
double quote |
\/ |
forward slash |
\n |
newline (U+000A) |
\r |
carriage return (U+000D) |
\t |
tab (U+0009) |
\b |
backspace (U+0008) |
\f |
form feed (U+000C) |
\uXXXX |
Unicode BMP code point (4 hex digits, uppercase or lowercase) |
\UXXXXXXXX |
Unicode supplementary code point (8 hex digits, uppercase or lowercase) |
\xXX |
Latin-1 code point (2 hex digits, uppercase or lowercase) |
Error handling for malformed escapes:
| Condition | Non-strict | Strict |
|---|---|---|
Unknown escape sequence (e.g. \q, \z, \0) |
Leave intact (backslash preserved) | throw |
Incomplete \uXXXX (fewer than 4 hex digits) |
Leave intact | throw |
Incomplete \UXXXXXXXX (fewer than 8 hex digits) |
Leave intact | throw |
Invalid hex digits in \u, \U, \x |
Leave intact | throw |
\UXXXXXXXX outside Unicode range (> U+10FFFF) |
Leave intact | throw |
UTF-16 surrogate in \uXXXX (U+D800–U+DFFF) |
Leave intact | throw |
Unterminated string (no closing ") |
String fallback (from opening quote to end of line) | throw |
Escape sequences left intact in non-strict mode are counted in their preserved literal form for scalar length purposes (§9).
Inside double-quoted strings, # is never a comment — comment stripping does not apply inside quoted strings.
6.1.3 Single-Quoted Strings
A value enclosed in matching single quotes ('...') is a string. Type coercion is not applied.
Single-quoted strings have exactly one special sequence: \' produces a single quote character. All other characters, including backslashes, are literal. \\ is two characters (backslash + backslash), not one backslash.
Backslash pairing.
When the closing quote is located, the content is scanned left to right and each backslash is taken together
with the character after it:
\\ is a two-character run of literal backslashes, and \' is an escaped quote. The second backslash of a \\ run therefore cannot combine with a following quote to form \'. A closing ' preceded by an even number of backslashes (zero included) ends the string; a ' preceded by an odd number of backslashes is the \'
escape — so a single-quoted value whose content would otherwise end in an odd run of backslashes is an
unterminated string (§10.1) and takes the fallback below.
Inside single-quoted strings, # is never a comment.
| Condition | Non-strict | Strict |
|---|---|---|
Unterminated string (no closing ') |
String fallback (from opening quote to end of line) | throw |
6.1.4 Unquoted Value Comment Escaping
In unquoted values, \# is an escaped hash: the backslash is removed and #
is kept as a literal character (not a comment). Only the immediately preceding backslash is considered —
earlier backslashes are not counted. A
# that neither starts the value nor follows whitespace is text without an escape (§4); \# yields # wherever it stands, so a value written for Core 1.2 reads the same.
| Input | Result | Reason |
|---|---|---|
text\#rest |
text#rest |
\# → #, no comment |
text\\#rest |
text\#rest |
second \ escapes #; first \ is literal |
text\\\#rest |
text\\#rest |
third \ escapes #; first two are literal (two backslashes preserved) |
text\\rest |
text\\rest |
no # follows; both \ are literal |
text#rest |
text#rest |
# after a character other than whitespace is text |
text #rest |
text |
unescaped # after a space starts a comment |
text \#rest |
text #rest |
\# → #, no comment |
6.1.5 Multi-line Strings (Block Scalars)
Multi-line strings require an explicit | marker on the first line:
description: |
Line one.
Line two.
The |
must appear alone on its line (after the key separator): the source value after the separator, trimmed of
whitespace, is exactly
|. This is decided before comment removal (§4): key: | # note is no block scalar but the string | (§6.1.6).
Block scalar extent:
A line belongs to a block scalar if and only if its indentation is strictly greater than the indentation of
the key that introduced the scalar. This rule applies to all lines, including lines beginning with
#. An indented # line is literal scalar content; a dedented #
line ends the scalar and is processed as a Lima comment by the surrounding structure. Empty lines between
scalar content lines belong to the scalar regardless of their indentation. An empty line here is one of spaces
only, or none: other whitespace, such as U+00A0, is scalar content, and a line of it at the key’s column or
less ends the scalar like any content line.
Examples:
description: |
Text
# top-level comment ← dedented, ends scalar; Lima comment
title: Hello
→ description = 'Text', title = 'Hello'
description: |
Text
# indented comment ← belongs to scalar, literal content
More text
→ description = 'Text\n# indented comment\nMore text'
Key with empty block and following comment:
empty:
# comment
next: value
→ empty = null, next = 'value' (comment is skipped, no content lines at deeper indentation)
Indentation trimming:
The content indentation is the smallest number of leading spaces among all non-empty content lines, measured
from column 0. Empty lines do not participate in this calculation. This uniform indentation is removed from
the start of every content line. Empty lines are preserved as empty strings in the joined result. Lines are
joined with a single newline character (\n) between each consecutive pair.
Trailing content:
All trailing empty lines and newlines at the end of a block scalar are removed (strip behaviour). The parsed
value ends with the final non-empty content line and contains no trailing newline. A
| with no content lines, at the end of the input too, is the empty string ''.
Tabs within the final content line are preserved — only trailing empty lines and newlines are stripped, not
whitespace within lines.
Inline content without |: Indented freetext without a |
marker is not a valid multi-line string. It is an other line of §7.1: after a bare key it opens the key’s
block but adds nothing to it.
- Non-strict: the line is skipped; the key is
nullunless a later line of its block is a member (§7.1). - Strict: throw. Error includes 1-based line number.
6.1.6 Line Continuation (^^)
Within a | block, a line beginning with ^^
(after indentation trimming) is a continuation line. It is appended to the previous line with a single space,
and the
^^ marker is removed.
description: |
This is a very long sentence that
^^continues on the next line as one.
→ "This is a very long sentence that continues on the next line as one."
Rules:
^^must appear at the very start of the line content (after indentation trimming).- A
^^line with no further content (bare^^) is silently dropped — no trailing space is added to the previous line. ^^on the first content line of a block has no previous line to append to — the marker is stripped and the content is kept as-is.^^is only valid inside|blocks. It has no special meaning in plain scalars or quoted strings.- A line that must literally begin with
^^cannot be represented in Lima Core — this is a documented limitation.
The folded block scalar > is not supported. Lines joining via > must be rewritten using | + ^^.
YAML block scalar headers: An unquoted value that is exactly a YAML block scalar header other than | — > or | or > followed by a chomping indicator (-, +) and an indentation digit (1–9), one or both, in either order, such as >, >-, |-, |+, |2, >2-
— is not a Lima block scalar. Non-strict mode reads it as a string, as Core 1.2 did. Strict mode throws at the
header’s line, whether lines follow or not, and the message names
| and ^^. The test is local to the value and holds for every unquoted value, as the test of §6.1.1 does; yaml-header in Appendix D (§15.7) gives its form.
The test applies to the unquoted value after comment removal and trimming (§4), whereas the | marker is decided on the source value before comment removal (§6.1.5): key: > # note is the header >, an error in strict mode; key: >#c and key: > text are strings; key: | # note is the string |.
6.2 Null
The following values produce null:
- Empty value: a bare key with no block (§4, §7.3), whether no value follows the separator or the value is reduced to empty by the inline value processing pipeline of §4
- The literal string
null - The literal string
~
6.3 Boolean
true→ boolean truefalse→ boolean false
Case-sensitive. True, TRUE, yes, no are strings.
6.4 Numbers
6.4.1 Grammar
The following grammar defines all recognised number forms. Implementations must apply this grammar directly, not delegate to host-language number parsing functions.
number = "-"? significand exponent?
significand = integer-part | decimal | leading
integer-part = "0" | [1-9][0-9]*
decimal = integer-part "." [0-9]+
leading = "." [0-9]+
exponent = [eE] [+-]? [0-9]+
Type determination:
- A number with no decimal point and no exponent is an integer.
- A number with a decimal point or an exponent (or both) is a float.
Valid examples: 42, -1, 0, 3.14, -0.5, .5, -.5, 1e3, 1E+3, .5e2, 1.5e-2
Invalid (remain strings): 1e, 1e+, .5E, 1e-
6.4.2 Range and Overflow
Integers:
Values outside the range −(2^53−1) to 2^53−1 (IEEE 754 safe integer range) fall back to string in both modes.
This ensures identical output across implementations regardless of host-language integer representation.
BigInt and arbitrary-precision integers are not part of the Lima type system.
Zero normalisation: Any numeric value whose parsed mathematical value is zero — whether integer (-0) or float (-0.0)
— and which did not result from underflow, is normalised to positive zero. This ensures identical output
across JavaScript (which distinguishes
+0 and -0) and Rust (which has no negative integer zero). Therefore value: -0 produces the integer 0, and value: -0.0 produces the float 0.0.
Floats: Follow IEEE 754 double precision.
- If conversion produces a non-finite value (
Infinityor-Infinity) due to overflow: non-strict — string fallback; strict — throw. - If a syntactically non-zero float converts to positive or negative zero due to underflow: non-strict — string fallback; strict — throw.
- Subnormal (denormal) values that remain non-zero are accepted as normal float values in both modes.
Lima does not produce Infinity, -Infinity, NaN, or negative zero as output values.
6.4.3 Explicitly Not Numbers
The following forms are not matched by the grammar and remain strings:
| Form | Example |
|---|---|
| Explicit plus sign | +42 |
| Trailing decimal point | 1. |
| Leading zeros (non-zero) | 01, 007 |
| Hexadecimal | 0xFF, 0XFF |
| Octal | 0o77, 0O77 |
| Binary | 0b1010, 0B1010 |
Infinity literal |
Infinity |
NaN literal |
NaN |
| Bare exponent | 1e, 1e+, 1e- |
6.5 Dates
6.5.1 Recognised Formats
Dates are recognised when the value matches one of the following forms exactly. Component validation applies to all forms (see §6.5.2).
ISO 8601 — offset supported:
| Form | Example |
|---|---|
| Date only | 2024-03-01 |
| Date + time | 2024-03-01T09:00 |
| Date + time + seconds | 2024-03-01T09:00:00 |
| Date + time + seconds + Z | 2024-03-01T09:00:00Z |
| Date + time + offset | 2024-03-01T09:00+02:00 |
| Date + time + seconds + offset | 2024-03-01T09:00:00+02:00 |
The T
separator between date and time is required for ISO forms. A space separator is not accepted for ISO forms.
German format (DD.MM.YYYY or D.M.YYYY) — no offset, always UTC:
| Form | Example |
|---|---|
| Date only | 01.03.2024 or 1.3.2024 |
| Date + time | 01.03.2024 14:33 |
| Date + time + seconds | 01.03.2024 14:33:00 |
Day and month may be one or two digits. A space separator between date and time is required.
Slash format (YYYY/MM/DD) — no offset, always UTC:
| Form | Example |
|---|---|
| Date only | 2024/03/01 |
| Date + time | 2024/03/01 14:33 |
| Date + time + seconds | 2024/03/01 14:33:00 |
Month and day must be two digits in slash format. A space separator between date and time is required.
6.5.2 Component Validation
All date and time components are validated individually. Dates use the proleptic Gregorian calendar. Years range from 0001 through 9999.
| Component | Valid range | Notes |
|---|---|---|
| Year | 0001–9999 | |
| Month | 1–12 | ISO and slash: exactly two digits in the format pattern (e.g. 03, not 3); German: one or two digits |
| Day | 1–last day of month | Calendar-aware including leap years; ISO and slash: exactly two digits in the format pattern; German: one or two digits |
| Hour | 00–23 | |
| Minute | 00–59 | |
| Second | 00–59 | Leap seconds not supported |
| Offset hour | 00–14 | |
| Offset minute | 00–59 | If offset hour is 14, offset minute MUST be 00 |
The reconstructed date components must match the input exactly. Invalid calendar dates (e.g. 2024-02-30) are not silently normalised. -00:00 is treated identically to +00:00 (UTC). 24:00 is not accepted.
- Non-strict: String fallback. The value is returned as a string unchanged.
- Strict: Throw. Error includes the invalid value and 1-based line number.
6.5.3 UTC Instant and Language Bindings
All date values represent a UTC Instant: a point in time in UTC with second precision and zero milliseconds.
- ISO 8601 with offset: Converted to UTC by applying the offset.
- ISO 8601 without offset: Interpreted directly as UTC.
- ISO 8601 date-only: Represents UTC midnight.
- German and slash formats: Always interpreted as UTC. Timezone offsets are not supported for these formats. Authors requiring timezone-aware values must use ISO 8601 with an explicit offset.
UTC Instant range:
After applying the timezone offset, the resulting UTC Instant must also fall within years 0001–9999. If the
UTC result falls outside this range (e.g.
0001-01-01T00:00+14:00 → year 0000 UTC, or 9999-12-31T23:59-14:00 → year 10000 UTC), the value is invalid.
- Non-strict: string fallback.
- Strict: throw. Error includes the original input value and 1-based line number.
Language bindings:
| Language | Concrete type |
|---|---|
| JavaScript/TypeScript | Date (milliseconds always 0) |
| JSON serialisation | RFC 3339 string (2024-03-01T09:00:00Z) |
| Rust | Instant { epoch_seconds: i64 } (seconds since the Unix epoch) |
| Go | Instant{ EpochSeconds int64 } (seconds since the Unix epoch) |
6.5.4 Explicitly Not Recognised
The following date-like forms are not recognised and remain strings:
- Space-separated ISO datetime:
2024-03-01 09:00 - Milliseconds:
2024-03-01T09:00:00.000Z - Year only:
2024 - Year + month:
2024-03 - American format
MM/DD/YYYY— ambiguous without locale - British format
DD/MM/YYYY— ambiguous without locale - Offset with German or slash format
- Strings containing
@(guards email addresses)
7. Collections
7.1 Indentation Model
Lima uses indentation to determine block structure. The following rules apply:
- Each block receives its base indentation from the indentation of its first non-empty, non-comment content line.
- All direct children of a block must have exactly this base indentation.
- A line indented deeper than the base indentation belongs to the immediately preceding key’s value as a nested block.
- A line whose indentation is less than the base indentation ends the current block and returns to the parent level.
- A line whose indentation does not correspond to any currently open block level is inconsistently indented — silently skipped in non-strict; throw in strict. This holds at the top level as at any other: a key with an inline value opens no block, so a line indented after it corresponds to no open block level.
- Empty lines (blank or whitespace-only) do not affect base indentation and are skipped.
- Comment lines (first non-whitespace character is
#) do not affect base indentation and are skipped.
What each kind of line does where it stands is the table below; rules 1–7 name its terms, and §6.1.5 and §7.2 define the structures it refers to. The document is a block mapping at column 0, so the rows for a block hold at the top level too.
Kinds of line. A blank line holds whitespace only (§1). A comment line has # as its first non-whitespace character. An entry is a key and its separator (§4, §5): with an inline value, or a bare key: with no value, or with one that is empty after comment removal and trimming (§4). An item is - alone or - followed by whitespace (§7.2): with a value, or a bare item - alone; an object item is an item whose value starts with an entry, and its key column is that entry’s column. An other line
is any other line with content: freetext, a key the key grammar rejects (§5.1), a quoted key that does not
close on its line or has a space before its colon (§5.2),
---, and a line whose content starts after whitespace other than spaces. A line’s column is its indentation, the run of spaces at its start.
The rows of the innermost structure open at a line apply: a |
scalar before the first line after a bare key, that before an object item or a compact sequence, and those
before the block they stand in.
| Where the line stands | Line | Non-strict | Strict |
|---|---|---|---|
In a | scalar of a key at column k (§6.1.5) |
An empty line (spaces only, or none) | Content of the scalar | Same |
| Any non-empty line at a column deeper than k | Content of the scalar, a # line included |
Same | |
| A line with content at column k or less | Ends the scalar; read where it stands | Same | |
| First line with content after a bare key at column k | An entry or an item deeper than k | Opens the key’s block: the line’s column is its base indentation, its kind decides whether the block holds entries or items | Same |
| An other line deeper than k | Opens the key’s block and sets its base indentation, but decides nothing about what it holds; skipped | Throw | |
| An item at column k | Opens the key’s compact sequence (§7.2) | Same | |
| Any remaining line at column k or less | The key is null; the line is read where it stands |
Same | |
| In a block of base indentation b | An entry or an item at column b, while the block holds nothing yet or holds that kind | A member of the block; the first decides what the block holds | Same |
| An entry or an item of the other kind at column b | Skipped; the block keeps its kind | Throw | |
| An other line at column b | Skipped | Throw | |
| A line deeper than b after a bare key | As the first line after a bare key (above) | Same | |
| Any remaining line deeper than b — after an inline value, after an item or a bare item, or at the top level with no block open | Inconsistently indented (rule 5): skipped; the block goes on | Throw | |
| A line less indented than b | Ends the block; read in the enclosing block by these rows | Same | |
| In an object item, its dash at column d and its key column c | An entry at column c | A member of the item’s mapping | Same |
| An item or an other line at column c | Skipped | Throw | |
| A line deeper than c after a bare key | As the first line after a bare key (above) | Same | |
| Any remaining line deeper than c | Inconsistently indented: skipped; the item goes on | Throw | |
| A line deeper than d and less indented than c | Inconsistently indented: ends the item; skipped | Throw | |
| A line at column d or less | Ends the item; read in the sequence by the rows for a block | Same | |
| In a compact sequence of a key at column k | An item at column k | The next item | Same |
| A line deeper than k | As in a block of items of base indentation k | Same | |
| Any remaining line with content at column k or less | Ends the sequence; read where it stands | Same | |
Anywhere but in a | scalar |
A blank line or a comment line | Skipped; it ends nothing and sets no base indentation | Same |
A key whose block ends with no member is null,
as a bare key with no deeper line is (§7.3). A skipped line is no member: it ends a block, an item or a
sequence only where the table says so, by its column.
Minimum indentation is one space. There is no required indentation increment — two spaces is conventional but not normative.
Indentation is the run of spaces at the start of a line, after §3 has replaced its tabs. Other whitespace
there, such as U+00A0, is no indentation: on a line with content, it starts the content, so the line is no
entry and no item but an unrecognised line (§4, §5.1), skipped in non-strict mode and an error in strict mode,
and its indentation is its spaces. A blank line stays empty (rule 6), and a line whose first non-whitespace
character is
# a comment line (rule 7), whatever whitespace precedes it. In a | scalar such whitespace is content (§6.1.5).
7.2 Block Sequences (Arrays)
A block sequence is a list of values, each on its own line, prefixed with - (dash followed by a space):
tags:
- javascript
- webdev
- open-source
A bare - with no following value produces null. So does - # note, an item whose value is empty after comment removal (§4); it is read as - alone is and opens no block (§7.1).
values:
-
- hello
# → [null, 'hello']
Type coercion applies to each item.
Object items:
A sequence item may be a mapping (object). The base indentation for sibling keys within an object item is the
column of the first key following the
-
prefix. All subsequent sibling keys must begin at that same column. A line of the item that no nested block or
|
scalar takes, at another column deeper than the dash, is inconsistently indented (§7.1 rule 5): deeper than
the key column, it is skipped in non-strict mode and the item goes on; less indented, it ends the item (§7.1
rule 4). Strict mode throws for either.
authors:
- name: Alice # 'name' is at column 4 → base indentation = 4
affiliation: MIT # must also be at column 4
- name: Bob
affiliation: Stanford
Nested maps within array object items follow the same indentation model recursively.
Nested sequences:
Array-in-array (nested block sequences) are not supported. In non-strict mode, the entire nested sequence
block is consumed and represented by a single
null
item in the outer sequence — subsequent lines of the inner sequence are not reinterpreted as outer items. In
strict mode, throw. An item’s value is an inline value (§15.3), so an item whose value is a flow sequence,
such as
- [a, b] or - [], is a nested sequence too: non-strict null, strict throw. Any other item value that begins with [ or { is read as any inline value is (§7.4, §7.5: an unclosed [ or { is a string fallback in non-strict mode and throws in strict mode).
Compact sequences: A bare key’s sequence may also start at the key’s own column, as YAML front matter often writes it:
tags:
- javascript
- webdev
title: Hello
→ tags = ['javascript', 'webdev'], title = 'Hello'
This holds at any level, the key of an object item included. A line is a sequence item when it is
- alone or - followed by whitespace; --- and -x
are not. A compact sequence ends at the first content line in its key’s column that is not an item. Only a
bare key opens one: after a key with an inline value, an item in the key’s column belongs to no value —
unrecognised at the top level (§4), a line of the other kind in a block mapping (§7.1).
7.3 Block Mappings (Maps)
A block mapping is a set of key-value pairs at a consistent indentation level:
author:
name: Alice
email: alice@example.com
Nested mappings are supported to any depth (within the limits of §9):
params:
social:
twitter: alice
github: alice-dev
Inline values and nested maps may be freely mixed within the same block.
A key with no inline value and no deeper indented content becomes null:
params:
empty:
title: Hello
# → { empty: null, title: 'Hello' }
empty:
# comment only, no content
next: value
# → { empty: null, next: 'value' }
7.4 Flow Sequences
A flow sequence is an inline list enclosed in square brackets:
tags: [javascript, webdev, open-source]
Empty flow sequence: [] produces an empty sequence.
Parsing rules:
-
A comment is removed from the whole value before it is split into items, by the rule of §4:
[a,#x]holds#x;[a, #x]is unclosed. - Items are separated by commas at the current flow depth, outside quoted strings. A comma inside an immediately nested flow mapping does not separate items of the outer sequence.
- Whitespace around items and commas is trimmed.
- Quoted items may contain commas. Quoting rules follow §6.1.2 and §6.1.3.
- Type coercion applies to unquoted items. Quoted items are returned as strings without coercion.
- Trailing comma: non-strict — trailing empty element ignored; strict — throw.
- Leading or consecutive commas (empty elements): non-strict — empty element becomes
null; strict — throw. - An unclosed
[: non-strict — string fallback for the entire value; strict — throw. - An unclosed
[containing a nested flow mapping (e.g.[{name: Home, url: /}): the outermost unclosed structure determines the fallback — non-strict: string fallback; strict: throw at the line of the opening[.
Nesting:
Flow sequences may contain flow mappings (one level deep). Flow sequences may not contain other flow
sequences, whether directly or via an intermediate flow mapping. The maximum permitted flow nesting depth is
one level — any
[...] or {...} construct nested inside another [...] or {...} at depth greater than one throws in both modes. This means [{key: [1,2]}] (SEQ → MAP → SEQ, depth 2) is also forbidden.
menu: [{name: Home, url: /}, {name: About, url: /about}] # ✓
matrix: [[1, 2], [3, 4]] # ✗ — error in both modes
7.5 Flow Mappings
A flow mapping is an inline set of key-value pairs enclosed in curly braces:
author: {name: Alice, role: editor}
Empty flow mapping: {} produces an empty mapping.
Parsing rules:
-
A comment is removed from the whole value before it is split into items, by the rule of §4:
{a: x#y}has the valuex#y;{a: x #y}is unclosed. -
Items are separated by commas at the current flow depth, outside quoted strings. Both this split and the
comment scan of §4 read every quote by the rules of a quoted string (§6.1.2, §6.1.3), a quote that opens a
key included; §5.2 applies once the key is taken from its item:
{'a\': 1, b: 2}is one item, whose key isa\. - Each item must have the form
key: value— the separator is a colon followed by a space or a tab (§5.1). A colon followed by anything else is no separator: before the first separator it is part of an unquoted key (§5.1), after it part of the value. - The separator is found in the item’s source text before its whitespace is trimmed:
{k: }and{k:\t}have a separator and the valuenull;{k:}has none. - Whitespace around items and commas is trimmed.
-
The first separator in each item separates key and value. Everything after it is the value — colons in
values are permitted:
{url: https://x:y}→url = 'https://x:y'. - Quoted keys follow the same rules as block quoted keys (§5.2).
- Type coercion applies to unquoted values. Quoted values are returned as strings without coercion.
- Trailing comma: non-strict — ignored; strict — throw.
- Leading or consecutive commas: non-strict — skipped; strict — throw.
- Missing separator: non-strict — string fallback for entire mapping; strict — throw.
- An unclosed
{: non-strict — string fallback; strict — throw.
Nesting: Flow mappings may not contain other flow mappings or flow sequences. Invalid nesting throws in both strict and non-strict mode — silent fallback to a broken string is not acceptable.
8. Comments
A #
character begins a comment when it appears outside a quoted string, is not escaped with a preceding backslash,
and is the first character of the value or follows whitespace (§1). Any other
# is text: https://example.org/x#section and C#
keep theirs. Comment recognition uses the same quote-aware scanner defined in §4 (inline value processing) —
it tracks quoted regions and respects escape rules. See §6.1.4 for the
\# escape rule in unquoted values.
Comments are stripped from inline values at all levels: top-level scalars, values inside block mappings, and values inside block array items.
title: My Article # comment stripped
author:
name: Alice # comment stripped here too
role: editor
# inside a quoted string is never a comment:
link: "https://example.com/page#section" # → 'https://example.com/page#section'
A comment after a key’s separator leaves the key bare, so its block may follow (§4):
author: # who wrote it
name: Alice
# → { author: { name: 'Alice' } }
Comment lines (lines where the first non-whitespace character is #)
are skipped entirely at any indentation level. They do not affect block structure or base indentation.
Multi-line | block scalar content: a # line that is more deeply indented than the introducing key is literal scalar content. A #
line that is dedented to the key’s indentation or less ends the scalar and is processed as a Lima comment (see
§6.1.5).
9. Resource Limits
The following limits are enforced in both strict and non-strict mode. Exceeding any limit is a hard error in both modes — limits are security boundaries, not style preferences.
Measurement conventions:
- Document size: UTF-8 byte count of the original input, before normalisation.
- Key and scalar length: Unicode code point count, measured after escape decoding. Escape sequences left intact in non-strict mode are counted in their preserved literal form.
- Nesting depth:
Defined recursively on the final parsed value tree. The document root mapping itself does not count as a
level.
depth(scalar) = 0 depth(array) = 1 + max(depth(element) for each element), or 1 if empty depth(mapping) = 1 + max(depth(value) for each entry), or 1 if empty documentDepth = max(depth(value) for each top-level entry)The limit
documentDepth ≤ 16applies. Flow collections count identically to block collections. This definition is used for Core parsing, partial validation, and the final References output check. - Top-level key count: All recognised top-level key entries, counted at parse time before duplicate resolution. Each occurrence of a duplicate key increments the counter.
| Resource | Limit |
|---|---|
| Document size | 64 KB (65,536 UTF-8 bytes) |
| Nesting depth (maps and arrays combined) | 16 levels |
| Number of top-level key entries | 128 |
| Key length | 128 Unicode code points |
| Scalar length | 16 KB (16,384 Unicode code points) |
When a limit is exceeded, the parser MUST throw an error with a descriptive message indicating which limit was exceeded and the 1-based line number where it was detected.
10. Strict Mode
Lima has two parse modes: non-strict (default) and strict.
Non-strict is tolerant by design. Unrecognised lines are skipped. Invalid syntax falls back to the nearest safe value. The mode is suitable for authoring environments where partial results are useful.
Strict adds a defined set of additional checks. The list is normatively closed — strict mode does not mean “validate everything”. Constructs not on this list are handled identically in both modes.
10.1 Strict Error List
| Condition | Non-strict | Strict |
|---|---|---|
| Duplicate key (any mapping level) | warn via onWarning + last wins |
throw |
Indented freetext first after a bare key, without a | marker |
skip; the key is null unless its block gains a member (§7.1) |
throw |
| Invalid date value (component validation) | string fallback | throw |
| Float overflow to non-finite, or non-zero float underflow to zero | string fallback | throw |
| Flow mapping missing its separator (§7.5) | string fallback for mapping | throw |
| Flow nesting deeper than one level | throw | throw |
Unclosed [ or { |
string fallback | throw |
| Trailing comma in flow sequence or mapping | ignore | throw |
| Empty element in flow sequence or mapping | null / skip |
throw |
Unknown escape sequence (e.g. \q, \z) |
leave intact (backslash preserved) | throw |
Incomplete or invalid escape sequence (e.g. \u12, \xZZ) |
leave intact | throw |
| Unterminated quoted string | string fallback | throw |
| Inconsistent indentation (§7.1 rule 5, at any level) | skip | throw |
| A sequence item in a block of mapping entries, or the reverse (§7.1) | skip | throw |
| Nested sequence, in block or flow form (§7.2) | null item |
throw |
| Unrecognised line: an unindented line that matches no key pattern (§4), or a line of a block mapping whose key the key grammar rejects (§5.1) | skip | throw |
An other line (§7.1) where the table of §7.1 says Throw, such as freetext or --- at the base indentation of a block of items |
skip | throw |
| Space before colon in quoted block key | skip | throw |
| Non-whitespace content after closing quote in an inline value | string fallback for entire value | throw |
An unquoted value that starts with &, * or ! (§6.1.1) |
string | throw |
An unquoted value that is a YAML block scalar header other than |, such as > or |- (§6.1.6) |
string | throw |
10.2 Error Messages
All errors (strict and resource limit) MUST include:
- A descriptive message identifying the problem.
- The 1-based line number where the error occurs (
at line N).
Non-strict duplicate key warnings delivered via onWarning MUST also include the line number.
Where an error stems from a form of YAML that Lima does not read, the message SHOULD say so and name the Lima form to write instead. Appendix E lists these forms; it is not normative.
11. API
11.1 Core Parse Function
parseCore(input: string, options?: CoreParseOptions): Record<string, unknown>
input
is the raw Lima content between the frontmatter delimiters. Stripping delimiters is the caller’s
responsibility.
The return value is a prototype-free plain object (equivalent to Object.create(null) in JavaScript). Keys are strings. Values are one of: string, number, boolean, Date (UTC Instant, §6.5.3), null, Array,
or a nested prototype-free mapping object. Member order is not semantically significant (see §1).
11.2 CoreParseOptions
| Option | Type | Default | Description |
|---|---|---|---|
strict |
boolean |
false |
Enable strict mode (§10) |
onWarning |
(diagnostic: Diagnostic) => void |
undefined |
Callback for non-strict warnings (e.g. duplicate keys). If not provided, warnings are silently discarded. |
Diagnostic object:
Diagnostic {
message: string // Human-readable description
line: number // 1-based line number
}
Implementations MUST NOT emit warnings to any implicit output channel (e.g. console.warn). All diagnostics must be delivered via onWarning.
11.3 Errors
All errors thrown by the parser are plain Error instances with a descriptive message
property. No custom error subclasses are required by this spec, but implementations may provide them.
12. Appendix A — What Lima Core Does Not Support
The following constructs are explicitly outside Lima Core. Their absence is intentional.
| Construct | Reason |
|---|---|
> folded block scalar |
Confusing semantics; | + ^^
covers the use case. Strict mode throws at the marker (§6.1.6); non-strict mode reads it as a string and
skips the lines that follow it as inconsistently indented (§7.1 rule 5)
|
Chomping and indentation indicators (|-, |+, |2) |
Not needed without >. As for > |
| Nested flow structures (depth > 1) | Not needed for frontmatter; block syntax is clearer |
| Nested sequences (array-in-array) | No real frontmatter use case. A nested sequence is a null item in non-strict mode and throws in strict mode (§7.2) |
| Space separator in ISO datetime | Non-standard; T separator required for ISO forms |
| Milliseconds in dates | No frontmatter use case |
| Timezone offset with German/slash date formats | Ambiguous; ISO 8601 required for timezone-aware values |
American date format MM/DD/YYYY |
Ambiguous without locale |
British date format DD/MM/YYYY |
Ambiguous without locale |
| Year 0000 and negative years | Edge case in host libraries; 0001–9999 sufficient for all real dates |
| UTC offsets beyond ±14:00 | No real timezone exceeds this range |
\0 escape sequence |
Treated as unknown escape — non-strict: intact; strict: throw. Use \u0000 if a null codepoint is genuinely needed |
partials option in Core API |
References Extension only — see §13 |
YAML anchors and aliases (&, *) |
Out of scope. An unquoted value that starts with & or * throws in strict mode (§6.1.1) |
YAML tags (!!str, !!int) |
Out of scope. An unquoted value that starts with ! throws in strict mode (§6.1.1) |
Multi-document streams (---, ...) |
Out of scope. A --- or ... line is unrecognised (§4) |
| Transitive references | References Extension only; at most three reference edges (References §4.2) |
| BigInt / arbitrary-precision integers | Not part of Lima type system |
| Non-finite float output | Lima never produces Infinity or NaN. The literal strings Infinity and NaN
are never parsed as numbers (grammar mismatch). A syntactic float that overflows to a non-finite value
falls back to string in non-strict mode and throws in strict mode (see §6.4.2 and §10.1).
|
13. Appendix B — Lima Core vs. References Extension
Lima Core defines the data format. The References Extension defines an optional resolution layer on top.
A Lima Core conforming parser implements parseCore as defined in §11. It does not need to implement reference resolution. ${key} and $(partial) tokens are plain strings to a Core parser.
The complete syntax, semantics, error behaviour, resource checks, and API additions of the optional References Extension are defined exclusively in the Lima References 2.1 specification; References 1.0 is frozen and normative only for its own conformance corpus. References 2.1 is an addition to Core 1.2 and, unchanged, to Core 1.3, as its own text says. In case of any discrepancy between this appendix and the References specification, the References specification is authoritative.
14. Appendix C — Design Principles
- Lima is a data format with convenience features, not an evaluation system. References and partials are author convenience, not a programming language. Features that move Lima toward a template language or evaluation system do not belong in Core.
- The YAML subset is the product. References and partials are features. Lima Core is a complete and useful format without references. The extension layer must not take over the identity of Core.
- The spec is implementation-language-agnostic. No rule may depend on host-language-specific behaviour. Every rule must be precise enough for a Rust implementation to follow directly.
Implementation Notes
These notes document known engineering trade-offs that arise from the design decisions above. They are not normative.
Float serialisation (References Extension only)
The canonical float serialisation (References §3.5.1) is normatively defined via the ECMAScript
Number::toString
algorithm, including its fixed-versus-exponential thresholds (exponent range −6 to 20). This is a deliberate
trade-off: it guarantees cross-language output parity at the cost of additional engineering effort in
non-JavaScript implementations. A Rust implementation must reproduce these thresholds exactly — using Ryu or
Dragonbox internally is fine, but the fixed/exponential boundary and the digit sequence must match ECMAScript
semantics. This is the one place where the spec is normatively ECMAScript-anchored; all other rules are
language-neutral.
Source position tracking (References Extension only) References orders the errors associated with source tokens by the source position (line number and character offset) of the token, and a token copied by a pure reference keeps the position of its original spelling (References §4.4, §5). A minimal streaming parser that deserialises directly into output structures without an intermediate representation cannot satisfy this requirement. Implementations of the References Extension must retain every active token’s source position and insertion provenance until resolution and final-result validation are complete. This is an intentional trade-off: deterministic error reporting requires this metadata.
The characters of a key An unquoted key’s letters, marks and numbers are the general categories of Unicode 18.0 (§5.1). A host language’s own Unicode support follows the version it was built with, and Rust’s standard library has no test for a mark; so every implementation carries its own table of the three categories, generated from the Unicode Character Database 18.0.0, rather than a dependency. Reading a key byte by byte while it is ASCII, and looking a category up only for a code point beyond U+007F, keeps a document of ASCII keys as fast as before.
Partial validation overhead
Partial values are fully validated and deep-copied before document parsing begins (References §6.2). For host
applications that pass large partial objects of which only a small fraction is actually referenced in a given
document, this validation occurs on every parse call regardless of usage. If this overhead is measurable, the
recommended approach is to pre-validate and cache the deep-copied Lima partial structure on the host side, and
pass the already-validated copy to
parseReferences — avoiding repeated validation of the same partial data.
15. Appendix D — Normative Grammar
15.1 Scope and Precedence
This appendix gives a consolidated EBNF description of Lima Core syntax. It is normative for the forms it describes, but it does not replace the procedural rules in the main specification.
The grammar describes the token and structural shape of valid Lima input after the normalisation steps in §3. The following remain governed by the cited prose sections:
- indentation measurement and block ownership (§7.1),
- quote-aware comment stripping and inline-value processing (§4 and §8),
- scalar type conversion and validation (§6),
- strict and non-strict fallback behaviour (§10),
- duplicate handling and resource limits (§5.3 and §9).
If this appendix and a procedural rule in the main specification appear to conflict, the procedural rule is authoritative.
15.2 Notation
The grammar uses ISO-style EBNF conventions:
rule = expression ;
alternative = first | second ;
sequence = first, second ;
optional = [ expression ] ;
repetition = { expression } ;
group = ( expression ) ;
Quoted text denotes a literal terminal. ? ... ? denotes a lexical condition or token supplied by the scanner.
The scanner operates on the normalised input and supplies these structural tokens:
NL = ? U+000A line ending; the last line of the input needs none (§4) ? ;
INDENT = ? entry into a deeper block level under §7.1 ? ;
DEDENT = ? return to a shallower block level under §7.1 ? ;
EOF = ? end of input ? ;
Blank lines and comment-only lines are ignored by the structural grammar except while collecting block-scalar
content. They do not produce
INDENT or DEDENT transitions.
15.3 Document and Block Structure
document = { top-level-entry | ignored-line }, EOF ;
top-level-entry = mapping-entry ;
block-value = block-mapping
| block-sequence ;
block-mapping = mapping-entry, { mapping-entry | ignored-line } ;
mapping-entry = key, inline-separator, block-scalar-marker, NL,
[ INDENT, block-scalar-body, DEDENT ]
| key, inline-separator, inline-value, NL
| key, block-separator, NL,
[ INDENT, block-value, DEDENT ]
| key, block-separator, NL, block-sequence ;
block-sequence = sequence-entry, { sequence-entry | ignored-line } ;
sequence-entry = "-", [ item-separator, sequence-value ], NL,
[ INDENT, sequence-continuation, DEDENT ] ;
sequence-value = inline-value
| object-entry-head ;
object-entry-head = key, inline-separator, inline-value
| key, block-separator ;
sequence-continuation
= block-mapping ;
item-separator = ? one or more whitespace characters (§1, §7.2) other
than U+000A, which alone ends a line after §3 ? ;
ignored-line = ? blank or comment-only line outside a block scalar ? ;
mapping-entry and sequence-entry
are accepted only when their indentation corresponds to the current block level under §7.1. The first content
line establishes the base indentation of a block. The grammar therefore does not assign a fixed number of
spaces to
INDENT.
The last form of mapping-entry
is a compact sequence: its items start at the key’s own column (§7.2), and it ends at the first content line
there that is not a
sequence-entry.
A sequence item beginning with object-entry-head
starts an object item. Subsequent sibling keys belong to that object only when they use the base indentation
defined in §7.2.
15.4 Keys and Separators
key = unquoted-key | single-quoted-key | double-quoted-key ;
unquoted-key = key-initial, { key-character } ;
key-initial = unicode-letter | unicode-number | "_" ;
key-character = key-initial | unicode-mark
| ":" | "-" | "*" | "·" ;
single-quoted-key = "'", { single-quoted-key-character }, "'" ;
double-quoted-key = '"', { double-quoted-character }, '"' ;
inline-separator = ":", ( " " | TAB ) ;
TAB = ? U+0009 ? ;
block-separator = ":" ;
For an unquoted key, the separator is the first colon followed by a space or a tab, or a colon that ends the
line or the input, outside a quoted key, as specified in §5.1. An
inline-separator whose value is empty after comment removal and trimming makes a bare key (§4): it is read as a block-separator.
A colon followed by any other character remains part of an unquoted key. For a quoted key, the separator must
immediately follow the closing quote (§5.2).
15.5 Inline Values
inline-value = quoted-string
| flow-sequence
| flow-mapping
| unquoted-source ;
quoted-string = single-quoted-string | double-quoted-string ;
single-quoted-string
= "'", { single-quoted-character }, "'" ;
double-quoted-string
= '"', { double-quoted-character }, '"' ;
unquoted-source = ? non-newline source text processed by the
quote-aware pipeline in §4 ? ;
unquoted-source ends before the first unescaped #
outside quoted regions that is its first character or follows whitespace (§4). Strict mode rejects an unquoted
value that starts with
&, * or ! (§6.1.1) or is a YAML block scalar header other than |
(§6.1.6). After comment removal and trimming, the resulting token is converted according to the scalar order
in §6. An empty result produces
null.
15.6 Quoted Characters and Escapes
single-quoted-character
= "\\'"
| ? any character except U+000A and an unescaped "'" ? ;
single-quoted-key-character
= ? any character except U+000A and "'" ? ;
double-quoted-character
= escape-sequence
| ? any character except U+000A, '"', and "\\" ? ;
escape-sequence = "\\\\" | "\\\"" | "\\/"
| "\\n" | "\\r" | "\\t" | "\\b" | "\\f"
| "\\u", hex-digit, hex-digit, hex-digit, hex-digit
| "\\U", hex-digit, hex-digit, hex-digit, hex-digit,
hex-digit, hex-digit, hex-digit, hex-digit
| "\\x", hex-digit, hex-digit ;
Unicode-range checks and strict/non-strict handling of malformed or unknown escapes are defined in §6.1.2 and §10.
15.7 Block Scalars
block-scalar-marker
= "|" ;
block-scalar-body = { block-scalar-line } ;
block-scalar-line = ? a physical line whose indentation is strictly
greater than that of the introducing key, or an
intervening empty line, under §6.1.5 ? ;
A block scalar is selected only when the source value after the separator, trimmed of whitespace, is exactly
|, before comment removal (§6.1.5). Content indentation removal, trailing-strip behaviour, and ^^ continuation processing are defined in §6.1.5–§6.1.6.
An unquoted value that, after comment removal and trimming, is exactly a yaml-header is no block scalar; strict mode rejects it (§6.1.6):
yaml-header = ">"
| ( "|" | ">" ), ( chomping, [ indent-digit ]
| indent-digit, [ chomping ] ) ;
chomping = "-" | "+" ;
indent-digit = nonzero-digit ;
15.8 Flow Collections
flow-sequence = "[", [ flow-sequence-items ], "]" ;
flow-sequence-items
= flow-sequence-item,
{ ",", flow-sequence-item } ;
flow-sequence-item = flow-scalar | flow-mapping ;
flow-mapping = "{", [ flow-mapping-items ], "}" ;
flow-mapping-items = flow-mapping-item,
{ ",", flow-mapping-item } ;
flow-mapping-item = flow-key, inline-separator, flow-scalar ;
flow-key = key ;
flow-scalar = quoted-string | unquoted-flow-source ;
unquoted-flow-source
= ? source text up to a current-depth comma or closing
delimiter, outside quoted strings, after the
comment removal of §4 on the whole value ? ;
Leading, consecutive, and trailing commas are recovery cases rather than valid grammar productions. Their mode-dependent handling is defined in §7.4–§7.5 and §10.
The nesting restrictions in §7.4–§7.5 are additional constraints: a flow sequence may contain flow mappings at one level; flow mappings may not contain flow collections; and flow nesting deeper than one level throws in both modes.
15.9 Scalar Lexemes
The following productions describe scalar forms before semantic range and calendar validation:
null-literal = "null" | "~" ;
boolean-literal = "true" | "false" ;
number = [ "-" ], significand, [ exponent ] ;
significand = integer-part | decimal | leading-decimal ;
integer-part = "0" | nonzero-digit, { decimal-digit } ;
decimal = integer-part, ".", decimal-digit, { decimal-digit } ;
leading-decimal = ".", decimal-digit, { decimal-digit } ;
exponent = ( "e" | "E" ), [ "+" | "-" ],
decimal-digit, { decimal-digit } ;
iso-date = year4, "-", digit2, "-", digit2 ;
iso-time = digit2, ":", digit2, [ ":", digit2 ] ;
iso-offset = "Z"
| ( "+" | "-" ), digit2, ":", digit2 ;
iso-datetime = iso-date, "T", iso-time, [ iso-offset ] ;
german-date = digit1-or-2, ".", digit1-or-2, ".", year4 ;
german-datetime = german-date, " ", iso-time ;
slash-date = year4, "/", digit2, "/", digit2 ;
slash-datetime = slash-date, " ", iso-time ;
date-literal = iso-date | iso-datetime
| german-date | german-datetime
| slash-date | slash-datetime ;
The productions recognise lexical shapes only. Numeric range, overflow, underflow, safe-integer checks, date-component validation, UTC conversion, and year bounds remain governed by §6.4–§6.5.
15.10 Character Classes
unicode-letter = ? a character of general category L
(Lu, Ll, Lt, Lm, Lo) in Unicode 18.0 ? ;
unicode-mark = ? a character of general category M
(Mn, Mc, Me) in Unicode 18.0 ? ;
unicode-number = ? a character of general category N
(Nd, Nl, No) in Unicode 18.0 ? ;
ASCII-letter = "A" | "B" | "C" | "D" | "E" | "F" | "G"
| "H" | "I" | "J" | "K" | "L" | "M" | "N"
| "O" | "P" | "Q" | "R" | "S" | "T" | "U"
| "V" | "W" | "X" | "Y" | "Z"
| "a" | "b" | "c" | "d" | "e" | "f" | "g"
| "h" | "i" | "j" | "k" | "l" | "m" | "n"
| "o" | "p" | "q" | "r" | "s" | "t" | "u"
| "v" | "w" | "x" | "y" | "z" ;
decimal-digit = "0" | "1" | "2" | "3" | "4"
| "5" | "6" | "7" | "8" | "9" ;
nonzero-digit = "1" | "2" | "3" | "4" | "5"
| "6" | "7" | "8" | "9" ;
hex-digit = decimal-digit
| "A" | "B" | "C" | "D" | "E" | "F"
| "a" | "b" | "c" | "d" | "e" | "f" ;
digit2 = decimal-digit, decimal-digit ;
digit1-or-2 = decimal-digit, [ decimal-digit ] ;
year4 = decimal-digit, decimal-digit,
decimal-digit, decimal-digit ;
16. Appendix E — YAML Forms Lima Does Not Read (non-normative)
Front matter is often written as YAML. Where Lima reads a YAML form otherwise or not at all, an error message should say so and name what to write instead (§10.2). This table lists the forms and what a message names; the wording is the implementation’s.
| YAML | What Lima does | What the message names |
|---|---|---|
&anchor, *alias, !tag at the start of a value |
Strict: throws (§6.1.1) | Lima has no anchors, aliases or tags; quote the value |
'It''s' |
Strict: throws, content after the closing quote (§4) | YAML doubles the quote; write 'It\'s' or "It's" |
key: >, key: |-, key: |+, key: |2, with or without indented lines |
Strict: throws at the header (§6.1.6) | Write |, and ^^ to join lines (§6.1.5, §6.1.6) |
<<: *base |
Strict: throws, unrecognised line (§4) | Lima has no merge keys |
%YAML 1.2, ---, ... |
Strict: throws, unrecognised line (§4) |
Lima has no directives or document markers; the caller strips the front matter’s own
--- |
my key: followed by a block |
Strict: throws, unrecognised line (§5.1) | Quote a key with spaces: 'my key': |
seo.title: Hello |
Strict: throws, unrecognised line (§5.1) | Nest by indentation: seo: and title: below it |
| A plain value continued on a deeper line | Strict: throws at that line (§7.1 rule 5) | A value spans lines only after | |
| A quoted value continued on the next line | Strict: throws, unterminated quoted string (§6.1.2) | A quoted value ends on its line; write | |
[a, and b] on the next line |
Strict: throws, unclosed [ (§7.4) |
A flow sequence ends on its line; write a block sequence with - |