03_options.md

Options

import { parse, stringify } from 'yaml'

parse('number: 999')
// { number: 999 }

parse('number: 999', { intAsBigInt: true })
// { number: 999n }

parse('number: 999', { schema: 'failsafe' })
// { number: '999' }

The options supported by various yaml are split into various categories, depending on how and where they are used. Options in various categories do not overlap, so it's fine to use a single "bag" of options and pass it to each function or method.

Parse Options

Parse options affect the parsing and composition of a YAML Document from it source.

Used by: parse(), parseDocument(), parseAllDocuments(), new Composer(), and new Document()

Name	Type	Default	Description
intAsBigInt	boolean	false	Whether integers should be parsed into BigInt rather than number values.
lineCounter	LineCounter		If set, newlines will be tracked, to allow for lineCounter.linePos(offset) to provide the { line, col } positions within the input.
prettyErrors	boolean	false	Include line position & node type directly in errors.
strict	boolean	true	When parsing, do not ignore errors required by the YAML 1.2 spec, but caused by unambiguous content.

Document Options

Document options are relevant for operations on the Document object, which makes them relevant for both conversion directions.

Used by: parse(), parseDocument(), parseAllDocuments(), stringify(), new Composer(), and new Document()

Name	Type	Default	Description
anchorPrefix	string	'a'	Default prefix for anchors, resulting in anchors a1, a2, ... by default.
keepUndefined	boolean	false	Keep undefined object values when creating mappings and return a Scalar node when stringifying undefined.
logLevel	'warn' ⎮ 'error' ⎮ 'silent'	'warn'	Control the verbosity of parse(). Set to 'error' to silence warnings, and to 'silent' to also silence most errors (not recommended).
version	'1.1' ⎮ '1.2'	'1.2'	The YAML version used by documents without a %YAML directive.

By default, the library will emit warnings as required by the YAML spec during parsing. If you'd like to silence these, set the logLevel option to 'error'.

Schema Options

parse('3') // 3 (Using YAML 1.2 core schema by default)
parse('3', { schema: 'failsafe' }) // '3'

parse('No') // 'No'
parse('No', { schema: 'json' }) // SyntaxError: Unresolved plain scalar "No"
parse('No', { schema: 'yaml-1.1' }) // false
parse('No', { version: '1.1' }) // false

Schema options determine the types of values that the document is expected and able to support.

Aside from defining the language structure, the YAML 1.2 spec defines a number of different schemas that may be used. The default is the core schema, which is the most common one. The json schema is effectively the minimum schema required to parse JSON; both it and the core schema are supersets of the minimal failsafe schema.

The yaml-1.1 schema matches the more liberal YAML 1.1 types (also used by YAML 1.0), including binary data and timestamps as distinct tags. This schema accepts a greater variance in scalar values (with e.g. 'No' being parsed as false rather than a string value). The !!value and !!yaml types are not supported.

Used by: parse(), parseDocument(), parseAllDocuments(), stringify(), new Composer(), new Document(), and doc.setSchema()

Name	Type	Default	Description
customTags	Tag[] ⎮ function		Array of additional tags to include in the schema
merge	boolean	1.1: true 1.2: false	Enable support for << merge keys. Default value depends on YAML version.
resolveKnownTags	boolean	true	When using the 'core' schema, support parsing values with these explicit YAML 1.1 tags: !!binary, !!omap, !!pairs, !!set, !!timestamp. By default true.
schema	'core' ⎮ 'failsafe' ⎮ 'json' ⎮ 'yaml-1.1'	1.1: 'yaml-1.1 1.2: 'core'	The base schema to use. Default value depends on YAML version.
sortMapEntries	boolean ⎮ (a, b: Pair) => number	false	When stringifying, sort map entries. If true, sort by comparing key values using the native less-than < operator.

const src = `
  source: &base { a: 1, b: 2 }
  target:
    <<: *base
    b: base`
const mergeResult = parse(src, { marge: true })
mergeResult.target
// { a: 1, b: 'base' }

Merge keys are a YAML 1.1 feature that is not a part of the 1.2 spec. To use a merge key, assign an alias node or an array of alias nodes as the value of a << key in a mapping.

ToJS Options

parse('{[1, 2]: many}') // { '[1,2]': 'many' }
parse('{[1, 2]: many}', { mapAsMap: true }) // Map { [ 1, 2 ] => 'many' }

These options influence how the document is transformed into "native" JavaScript representation.

Used by: parse() and doc.toJS()

Name	Type	Default	Description
mapAsMap	boolean	false	Use Map rather than Object to represent mappings.
maxAliasCount	number	100	Prevent exponential entity expansion attacks by limiting data aliasing; set to -1 to disable checks; 0 disallows all alias nodes.
onAnchor	(value: any, count: number) => void		Optional callback for each aliased anchor in the document.
reviver	(key: any, value: any) => any		Optionally apply a reviver function to the output, following the JSON specification but with appropriate extensions for handling Map and Set.

ToString Options

stringify(
  { this: null, that: 'value' },
  { defaultStringType: 'QUOTE_SINGLE', nullStr: '~' }
)
// 'this': ~
// 'that': 'value'

The doc.toString() method may be called with additional options to control the resulting YAML string representation of the document.

Used by: stringify() and doc.toString()

Name	Type	Default	Description
defaultKeyType	Type ⎮ null	null	If not null, overrides defaultStringType for implicit key values.
defaultStringType	Type	'PLAIN'	The default type of string literal used to stringify values.
directives	boolean ⎮ null	null	Include directives in the output. If true, at least the document-start marker --- is always included. If false, no directives or marker is ever included. If null, directives and marker may be included if required.
doubleQuotedAsJSON	boolean	false	Restrict double-quoted strings to use JSON-compatible syntax.
doubleQuotedMinMultiLineLength	number	40	Minimum length for double-quoted strings to use multiple lines to represent the value.
falseStr	string	'false'	String representation for false values.
indent	number	2	The number of spaces to use when indenting code. Should be a strictly positive integer.
indentSeq	boolean	true	Whether block sequences should be indented.
lineWidth	number	80	Maximum line width (set to 0 to disable folding). This is a soft limit, as only double-quoted semantics allow for inserting a line break in the middle of a word.
minContentWidth	number	20	Minimum line width for highly-indented content (set to 0 to disable).
nullStr	string	'null'	String representation for null values.
simpleKeys	boolean	false	Require keys to be scalars and always use implicit rather than explicit notation.
singleQuote	boolean	false	Prefer 'single quote' rather than "double quote" where applicable.
trueStr	string	'true'	String representation for true values.