Lima Guide
A practical walkthrough of Lima syntax, the References Extension, resource limits, and the JavaScript/TypeScript API.
A practical walkthrough of Lima syntax, the References Extension, resource limits, and the JavaScript/TypeScript API. This guide is descriptive, not normative — Lima Core 1.3 and Lima References 2.1 are the source of truth. Where this guide and a spec disagree, the spec wins.
Installation
npm install @limaformat/lima
# or
bun add @limaformat/lima
Quick example
import { parse } from '@limaformat/lima'
const result = parse(`
title: Hello World
published: 2024-03-01
draft: false
tags:
- javascript
- webdev
`)
// {
// title: 'Hello World',
// published: 2024-03-01T00:00:00.000Z, // a Date
// draft: false,
// tags: ['javascript', 'webdev']
// }
parse accepts the raw Lima content between the frontmatter delimiters (---) — stripping those delimiters is the caller’s job, Lima never sees them.
Syntax
Key names
An unquoted key starts with a letter, number, or underscore, in any script, followed by any combination of
letters, accents and other marks, numbers, underscores, hyphens, colons, asterisks, or middle dots (·).
Letters, marks and numbers are those of Unicode 18.0; numbers include more than the digits 0–9, such as Roman
numerals.
| Format | Example | Valid unquoted |
|---|---|---|
| camelCase | firstName |
yes |
| snake_case | first_name |
yes |
| kebab-case | first-name |
yes |
| number start | 1st, 42 |
yes |
| colon-namespaced | og:title |
yes |
| other languages | größe, título, 題名 |
yes |
| gendered | autor:in, autor*in, autor·in |
yes |
| spaces, other characters | first name, 🙂 |
needs quoting |
Lima reads a key as it is written and does not normalise Unicode: an ö typed as one character and an ö typed as o plus a combining mark are two different keys. Editors write the first almost always.
Since unquoted keys may themselves contain colons, the key/value separator is the first colon followed by a space or a tab, or :\n, that isn’t inside a quoted key:
og:title: Hello # key = 'og:title', value = 'Hello'
a:b:c: value # key = 'a:b:c', value = 'value'
Quoted keys — single or double quotes, for keys with spaces or other characters an unquoted key can’t hold. Delimiters are stripped from the output key:
'first name': Alice # → { 'first name': 'Alice' }
"display name": Bob # → { 'display name': 'Bob' }
'': empty string key # → { '': 'empty string key' }
Double-quoted keys decode the same backslash escapes as double-quoted string values (below). Single-quoted
keys are literal. The separator must immediately follow the closing quote —
"key" : value
(space before the colon) is rejected at the top level (throws in strict mode, skipped as an unrecognised line
in non-strict). Enforcement is less consistent for a quoted key nested inside a block or flow mapping — don’t
rely on a space there being caught either way; simply avoid it.
Strings
Unquoted:
title: My Article
Double-quoted — suppresses type coercion, decodes escapes:
title: "Lima: A Primer" # → 'Lima: A Primer' (colon is safe inside quotes)
count: "42" # → '42' (string, not number)
flag: "true" # → 'true' (string, not boolean)
| Escape | Result |
|---|---|
\\ |
backslash |
\" |
double quote |
\/ |
forward slash |
\n \r \t |
newline / CR / tab |
\b \f |
backspace / form feed |
\uXXXX |
Unicode BMP code point (4 hex digits) |
\UXXXXXXXX |
Unicode supplementary code point (8 hex digits) |
\xXX |
Latin-1 code point (2 hex digits) |
An unrecognised escape (including \0 — there is no null-byte escape) is left intact in non-strict mode and throws in strict mode.
Single-quoted — also suppresses coercion, but has exactly one special sequence: \' for a literal quote. Everything else, including backslashes, is literal — 'a\\b' is the four characters a\\b, not a\b.
Comments in unquoted values — # starts a comment at the start of a value or after whitespace; a # right after other text is text. \# always keeps a literal #; only the immediately preceding backslash counts:
link: https://example.com/page#section # → 'https://example.com/page#section'
lang: C# # → 'C#'
color: #ff0000 # → null — the whole value is a comment
link: https://example.com/page #section # → 'https://example.com/page'
link: https://example.com/page \#section # → 'https://example.com/page #section'
A key whose value is only a comment is a bare key, so its block may follow:
author: # who wrote it
name: Alice # → { author: { name: 'Alice' } }
#
inside a single- or double-quoted string is never a comment — comment stripping only ever applies to unquoted
values.
Multi-line strings require an explicit | marker — plain indented continuation lines without | are not joined automatically:
description: |
Line one.
Line two.
A line belongs to the block scalar as long as its indentation is strictly greater than the introducing key’s —
including lines starting with
# (they’re literal content, not comments, as long as they’re still indented further than the key).
Merge two lines into one with ^^ at the start of the continuing line, inside a | block only
— it has no special meaning elsewhere. The line is joined to the one before it with a single space:
description: |
This is a very long sentence that
^^continues on the next line as one.
There is no YAML-style > folded scalar — | + ^^ covers the same need with less ambiguity. A YAML header such as >, |- or >2 reads as a string in non-strict mode and throws in strict mode, at its own line.
Types
| Value | Type |
|---|---|
null, ~, (empty) |
null |
true, false (case-sensitive) |
Boolean |
42, 3.14, .5 |
Number |
0xFF, 0o77, 0b1010 |
String (not parsed as numbers) |
01, 007, +42, 1. |
String (not parsed as numbers) |
2024-03-01, 2024-03-01T09:00:00Z |
Date |
01.03.2024 14:33 |
Date |
2024/03/01 14:33 |
Date |
| anything else | String |
Leading zeros, an explicit +
sign, a trailing bare decimal point, and hex/octal/binary literals are all deliberately kept as strings — no
silent reinterpretation.
Dates are always UTC, second precision, no milliseconds:
| Form | Example |
|---|---|
| ISO date only | 2024-03-01 |
| ISO date + time | 2024-03-01T09:00, ...T09:00:00, ...T09:00:00Z, ...T09:00+02:00 |
German (DD.MM.YYYY, no offset) |
01.03.2024, 01.03.2024 14:33 |
Slash (YYYY/MM/DD, no offset) |
2024/03/01, 2024/03/01 14:33 |
ISO forms require the T separator — a space between date and time is not
accepted for ISO forms. German and slash forms require a space between date and time, and never carry a
timezone offset (an offset there falls through to a string, not an error). An ISO offset is applied and
converted to UTC:
published: 2024-03-01T09:00:00+02:00
# → Date, 2024-03-01T07:00:00.000Z
Years run 0001–9999. An out-of-range calendar value (2024-02-30)
or an offset that pushes the resulting UTC year outside that range falls back to a string in non-strict mode,
or throws in strict mode.
Arrays
Block sequence — dash-prefixed, one item per line:
tags:
- javascript
- webdev
A bare - with nothing after it is null:
values:
-
- hello
# → [null, 'hello']
Flow sequence — comma-separated in brackets, same type coercion rules, same result as the block form:
tags: [javascript, webdev, open-source]
values: [1, true, hello]
values: ["42", "true", hello] # quoted items skip coercion → ['42', 'true', 'hello']
Arrays of objects — multiple keys per item, indented block style:
authors:
- name: Alice
affiliation: MIT
- name: Bob
affiliation: Stanford
Flow mapping — inline objects, useful as array items or map values:
menu:
- {name: Home, url: /, weight: 1}
- {name: About, url: /about, weight: 2}
Array items can be scalars or mappings, never another array or another flow collection nested inside a flow collection — Lima intentionally doesn’t support array-of-arrays or flow nesting deeper than one level (see Appendix A).
Maps
author:
name: Alice
email: alice@example.com
Nested to any depth (up to the nesting limit), and inline values / nested maps can be freely mixed at the same level:
params:
weight: 1
social:
twitter: alice
draft: false
Tabs
Only tabs in leading indentation — before the first non-whitespace character on a line — are normalised to two spaces. A tab that appears within scalar content, quoted or not, is left exactly as written:
a:
b: 1 # → { a: { b: 1 } } — leading tab normalised to indentation
c: x y # → { c: 'x\ty' } — tab inside the value is preserved literally
Comments
title: My Article # this is a comment
Stripped from single-line values. Multi-line (|) block scalars don’t process comments the same way — see Multi-line strings above for the indentation-based rule that applies there instead.
References (optional extension)
Everything in this section is Lima References 2.1, layered on top of Core. A Core-only parser (parseCore) treats ${key} and $(key) as plain strings. parse enables References by default; parseReferences is its deprecated compatibility alias with identical semantics.
Document reference — ${key} or a dotted path ${a.b.c}:
total: 42
count: ${total} # → 42 (number, not string — type preserved)
Partial reference — $(key), resolved against a partials object you pass in. Later dotted components traverse mappings; / remains literal namespace content in the partial name:
author: $(defaultAuthor)
city: $(people/alice.address.city)
parse(frontmatter, {
partials: {
defaultAuthor: { name: 'Alice', email: 'alice@example.com' },
'people/alice': { address: { city: 'London' } },
}
})
Pure reference vs. interpolation — a value that is exactly one reference token (after trimming) preserves the target’s original type. Anything else — surrounding text, or more than one token — is interpolation and always produces a string:
firstName: Alice
fullName: ${firstName} ${lastName} # interpolation → 'Alice Wonderland'
greeting: Hello ${firstName}! # interpolation → 'Hello Alice!'
A reference inside a quoted string is inactive — literal text, never resolved:
title: "${key}" # NOT a reference — stays the literal string "${key}"
Forward and bounded transitive references work. Targets may occur before or after their source. A chain may contain at most three reference edges, connecting at most four values:
a: ${b}
b: ${c}
c: 42
Both a and b resolve to 42.
A fourth edge is unresolved: non-strict mode leaves that source token literal, while strict mode throws.
Suffixes that fit within three edges may still resolve.
Partial mappings may be traversed by the token’s dotted path. Their stored strings remain inert: reference-looking text inside a partial is always literal, even after insertion.
Resource limits
Checked in both strict and non-strict mode; exceeding any of these throws RESOURCE_LIMIT in both modes (there is no silent-fallback variant for resource limits).
| Limit | Value |
|---|---|
| Document size | 65,536 bytes (UTF-8) |
| Key length | 128 code points |
| Scalar length | 16,384 code points |
| Nesting depth | 16 |
| Top-level keys | 128 |
| Partials: count / name length / value depth / total nodes | 128 / 128 / 16 / 4,096 |
| References result: total node count | 65,536 |
Strict mode
Most malformed values are recoverable in non-strict mode — parsing falls back to a string, null, or skips the offending content, and reports what it can via onWarning. A handful of conditions throw in both modes, because there is no safe fallback to recover to: the resource limits
above, flow nesting deeper than one level (Core §10.1 itself), and — once References is layered on top —
several reference/interpolation/partial conditions (below). Check the “Non-strict” column of each table; don’t
assume it always means “never throws”.
Since Core 1.1, strict mode has one plain rule for lines: every line with content belongs to the structure. A
line it cannot place — a key without its
:,
a YAML document marker, a line indented after a value that opens no block — is an error with its line, where
non-strict mode skips it silently. What each kind of line does where it stands is one table in Core §7.1.
| Condition | Non-strict | Strict |
|---|---|---|
| Duplicate key | warn + last value wins | throw |
Indented freetext first after a bare key, without | |
skipped; the key is null unless a later line of its block is a member |
throw |
| Invalid date (calendar validation) | string fallback | throw |
| Float overflow / non-zero underflow to zero | string fallback | throw |
Flow mapping missing : |
string fallback | throw |
| Flow nesting deeper than one level | throw | throw |
Unclosed [ or { |
string fallback | throw |
| Trailing comma in flow sequence/mapping | ignored | throw |
| Empty flow element | null / skipped |
throw |
| Unknown or malformed escape sequence | left intact | throw |
| Unterminated quoted string | string fallback | throw |
| Inconsistent indentation (also a line indented after a top-level inline value) | skipped | throw |
Unrecognised line: an unindented line that is no key (author Odile, ---), or a key the key grammar rejects (a.b: value) at any level |
skipped | throw |
| Space before colon in a quoted block key | skipped | throw |
| Content after a closing quote on an inline value | string fallback | throw |
An unquoted value that starts with &, * or ! (a YAML anchor, alias or tag) |
string | throw |
A YAML block scalar header other than |, such as > or |- |
string | throw |
References 2.1 adds (Core §10.1 + References §7):
| Condition | Non-strict | Strict |
|---|---|---|
| Unresolved reference after resolution | left as token string | throw |
| More than three reference edges | left as token string | throw |
| Dependency cycle | left as token string | throw |
| Mapping value used in interpolation | throw | throw |
| Array/nested-array element in interpolation | throw | throw |
| Scalar limit exceeded after interpolation/copy | throw | throw |
| Nesting depth exceeded after reference insertion | throw | throw |
| Invalid partial value | throw | throw |
API
import { parseCore, type CoreOptions } from '@limaformat/lima'
import { parse, parseReferences, type ParseOptions, type ParseMode } from '@limaformat/lima'
import { outline, type LimaOutline } from '@limaformat/lima'
parseCore and parse both take (input: string, options?) => T, T defaulting to Record<string, unknown>
— pass your own interface for a typed result. This is a compile-time assertion only, not runtime validation:
Lima does not check that the parsed data actually matches
T,
it just tells TypeScript to treat the return value as that type. Validate separately (e.g. with
zod or a manual check) if the input isn’t trusted:
interface PostMeta {
title: string
published: Date
draft: boolean
tags: string[]
}
const meta = parse<PostMeta>(frontmatter)
meta.title.toUpperCase() // TypeScript knows title is a string
parseCore(input, options?: CoreOptions) — Core only. ${key} and $(key) are plain strings.
| Option | Type | Default |
|---|---|---|
strict |
boolean |
false |
onWarning |
(diagnostic) => void |
undefined |
parse(input, options?: ParseOptions) — the primary Core plus References 2.1 parser. parseReferences is a deprecated exact alias; new code should use parse.
| Option | Type | Default |
|---|---|---|
strict |
boolean |
false |
onWarning |
(diagnostic) => void |
undefined |
partials |
Record<string, unknown> |
{} |
mode |
'references' | 'core' |
'references' |
parse(input, { mode: 'core' }) uses the same reference-unaware path as parseCore. Supplying partials together with mode: 'core' throws before parsing begins.
outline(input)
— where each key, comment and error stands in the source, for editors. It never throws for content: an
unfinished line leaves the keys below it in place.
import { outline } from '@limaformat/lima'
const { keys, comments, diagnostics } = outline('Autor:in: Michael # byline\n')
keys[0].key // 'Autor:in'
keys[0].span.start // { line: 1, column: 1, offset: 0 }
Spans are half-open; lines and columns start at 1, and columns and offsets count UTF-16 code units in the
input without a leading BOM.
diagnostics holds what a strict parse would report. JavaScript only.
Duplicate keys never go to console.warn — or any other implicit output channel. Diagnostics are only ever delivered through onWarning; without one, they’re silently discarded:
parse(frontmatter, {
onWarning: (d) => console.warn(d.message, 'at line', d.line),
})
Strict mode throws a plain Error with a descriptive .message on the conditions listed above — this is the guaranteed contract (Core §11.3):
try {
const meta = parse(frontmatter, { strict: true })
} catch (e) {
console.error((e as Error).message)
}
Internally the thrown object also carries a .code, .line,
and other structured fields, but that richer shape isn’t currently exported as a named type from the package —
don’t rely on
instanceof
against a class you can’t import, or on the extra fields being present in a future version, until that’s a
documented, stable export.
Implementation notes
- Zero runtime dependencies.
- Avoids backtracking-specific regex features. Every pattern in the implementation avoids lookahead, lookbehind, backreferences, and nested-quantifier constructions — the grammar doesn’t require a backtracking engine, the same property linear-time engines like RE2 require. Not a claim of immunity to slow input in general, just that the grammar itself doesn’t force worst-case regex behaviour.
- Speed. Measured against
js-yamlon Bun, on representative frontmatter documents: reproduce it yourself withbun run bench:vs-yamlfromjs/. Numbers are runtime-specific — don’t assume they transfer proportionally to other JavaScript engines. - Conformance corpus. Every claim about parsing behaviour in this guide is backed by cases in the conformance corpus, checked against both this implementation and (where applicable) any future one — see the corpus design.
Where to go next
- Lima Core 1.3 and Lima References 2.1 — the normative specs; this guide simplifies, they decide.
- Repository README — why Lima exists, the case against YAML, security rationale.