yaml
2.9.1 · 11 Sep 2026ISC330.2M / weekRepositoryHomepagenpmAtom feed
2.9.1 is the newest release of 2.x.
In short
30 breaking28 new1 fixed
- Breaking
The breaking changes introduced here are mostly originating from the v1 CST parser having become a rather difficult beast to work with.
- Breaking
The following is an overview of the breaking changes and new features introduced in each of the prerelease steps leading up to this release; the individual releases' notes and the PRs will contain more detail, along with specific migration guides.
- Breaking
Drop deprecated end points, members, options & defaults
- Breaking
Breaking changes to Document & createNode APIs
- Breaking
When creating a mapping from a JS Object, drop undefined values
- Breaking
Retain existing nodes when using
set()in mappings & sequences - Breaking
Improve JSON compatibility
- Breaking
Refactor tag
resolve()API
Security
2 advisories affect 2.0.0; 2.8.3 fixes them
- HighUncaught Exception in yamlGHSA-f9xv-q969-pqx4 · 24 Apr 2023Fixed in 2.2.2
- Moderateyaml is vulnerable to Stack Overflow via deeply nested YAML collectionsGHSA-48c2-rrv3-qjmp · 25 Mar 2026Fixed in 2.8.3
Release note
This update has been in the works for the last year and a half. Its prerelease versions have been thoroughly tested by a wide number of users, and I think it's finally ready for "actual" release, for use in the mythical "production".
The breaking changes introduced here are mostly originating from the v1 CST parser having become a rather difficult beast to work with. So it's here rewritten pretty much completely, now with a lexer as a first stage. Along the way, the whole project was rewritten in TypeScript and the export paths and options refactored pretty deeply.
If you've been using the library just via its parse(), parseDocument() and stringify() functions, then it's quite likely that none of the changes affect your experience in any way. However, if you've been doing something more involved, then I would strongly recommend that you review the library's documentation site for the v2 docs.
Going forward, it's finally time to start experimenting with new YAML spec features that may eventually be included in YAML 1.3 and later. Those will be made available by specifying the version: 'next' option. However, beware! Any features available this way may be removed or have their API broken by any minor release of this library, and no compatibility guarantees with other libraries are given. In general, semver compatibility is guaranteed for features that are explicitly included in the documentation; everything else should be considered as internal implementation details.
The following is an overview of the breaking changes and new features introduced in each of the prerelease steps leading up to this release; the individual releases' notes and the PRs will contain more detail, along with specific migration guides.
Breaking changes
- Breaking
Drop deprecated end points, members, options & defaults
- Breaking
Breaking changes to Document & createNode APIs
- Breaking
When creating a mapping from a JS Object, drop undefined values
- Breaking
Retain existing nodes when using
set()in mappings & sequences - Breaking
Improve JSON compatibility
- Breaking
Refactor tag
resolve()API - Breaking
Drop
'yaml/parse-cst'endpoint - Breaking
Update build configs & minimum supported versions
- Breaking
Refactor options
- Breaking
Refactor parsing completely
- Breaking
Merge all of
'yaml/types'and some of'yaml/util'into'yaml' - Breaking
Refactor node identification
- Breaking
Drop
typeproperty from all but Scalar nodes - Breaking
Refactor as TypeScript
- Breaking
Make anchor & alias resolution lazier
- Breaking
Split flow collections into items in Parser
- Breaking
Make Pair not extend NodeBase; drop its prop forwarding (#245, #250)
- Breaking
Rename the
tokensnamespace asCST - Breaking
Turn the Lexer, Parser & Composer into generators
- Breaking
Refactor Node range as
[start, value-end, node-end] - Breaking
Replace
error.offsetwitherror.pos: [number, number] - Breaking
Fix empty lines & trailing comments
- Breaking
Drop Node.js 10 support
- Breaking
Allow disabling single & block quotes completely
- Breaking
The TS type of
doc.directivesnow indicates it as optional - Breaking
YAML.defaultOptionsis removed - Breaking
directives.markeris renamed asdirectives.docStart - Breaking
Drop Node.js 12 support (end-of-life 2022-04-30)
New Features
Resolve known tags in core schema
Create intermediates for
set()&setIn()on doc with empty contentsFix intermediate collection creation for parsed documents
Improve quoted string flexibility
Add
defaultKeyTypeoption for finer control of scalar outputRemember source string for null scalars
Support
asBigIntoption for sexagesimal integer valuesRefactor logging control, adding
logLeveloptionAdd
visit(node, visitor)to'yaml'Stringify top-level block scalars with header on marker line
Add a couple of things to
'yaml/util'that weren't exposed beforeAdd Collection, Value & Node visitor aliases
Add error codes
Always include offset in CST tokens
Add CST tools
Check key uniqueness; add
uniqueKeysoptionDrop special-casing
COMMENT_SPACEerror; useMISSING_CHARfor it insteadSupport immediate map values for
<<merge keys, in addition to alias valuesAdd a new createNode option
aliasDuplicateObjectsAdd
clone()methods to Document, Directives, Schema and all NodesAdd
keepSoureTokenparse option, addingsrcTokenvalues to NodesAllow for custom schema id, provided that
customTagsis definedExpose tags & types required by custom composers
Add a compatibility checker
Add warning for aliases & anchors ending with a colon
Add
directives.docEnd, for...markerAdd
YAML.visitAsync()Allow for a
'next'YAML version
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.