YAML to JSON Types: What Converts and What Is Lost

YAML and JSON do not have the same information model

The YAML 1.2.2 specification separates presentation, serialization, representation, and native construction. Presentation includes indentation, comments, scalar styles, directives, and anchor spelling. The representation model is a rooted, connected, directed graph of tagged nodes. A node may appear in more than one collection, and cycles are possible.

RFC 8259 defines a JSON value as an object, array, number, string, boolean, or null. An object is a collection of name/value pairs, and a name is a string. JSON text has no syntax for comments, tags, anchors, aliases, typed timestamps, binary scalars, complex object keys, or several documents in one stream.

YAML 1.2 was designed so that JSON syntax can be accepted as YAML, but that subset relationship goes from JSON text into YAML—not from every YAML feature into JSON. Converting richer YAML requires either rejecting unsupported input, transforming it under a documented policy, or silently losing information. Rejection and explicit warnings are safer than silent guessing.

YAML to JSON type mapping

A conversion that fits the common subset

service: catalog
enabled: true
retries: 3
regions:
  - us-east
  - eu-west
limits:
  timeout_ms: 2500

{
  "service": "catalog",
  "enabled": true,
  "retries": 3,
  "regions": ["us-east", "eu-west"],
  "limits": { "timeout_ms": 2500 }
}

This example uses a single document, string mapping keys, a sequence, nested mappings, and scalar values common to both models. Layout differs, but the intended data tree is straightforward. Even here, the selected YAML schema matters: under YAML 1.1, plain words such as on and no could resolve as booleans rather than strings. Review the YAML 1.1 vs 1.2 guide before converting legacy files.

Comments, quotes, block style, and ordering

YAML comments are presentation details intended for human maintainers. JSON has no comment grammar. If a comment records an operational warning, approval requirement, unit, or provenance fact, plain JSON cannot carry it unless you remodel it as an ordinary property. Automatically turning comments into properties is also dangerous because it changes application data. LiveParse omits comments and reports COMMENTS_DROPPED.

Single quotes, double quotes, plain scalars, literal blocks, and folded blocks are YAML presentation choices. Conversion keeps the resolved string value, not the original style. A literal block and a quoted string may serialize to the same JSON string once line folding, chomping, and escapes are resolved. If source fidelity matters, keep the original YAML alongside the converted artifact.

YAML's representation model treats mapping key order as a serialization detail. JSON objects are also semantically collections of names and values; consumers differ in how they expose order. Use a sequence when order is application data. Do not turn an ordered procedure into a mapping and expect formatter or converter output order to serve as a contract.

String keys, scalar coercion, and complex keys

JSON object names are strings. YAML mapping keys can be scalar nodes of other types and can even be sequences or mappings. A converter therefore needs a key policy. LiveParse leaves string keys unchanged. Null, finite number, bigint, and boolean keys are converted to their string spellings with a NON_STRING_KEY_COERCED warning. If two distinct YAML keys become the same JSON string, conversion stops with a collision error.

1: numeric key
"1": string key

Both entries would need the JSON property name "1". Choosing one silently would discard data, so rejection is the honest result. A sequence, mapping, or alias used as a YAML key is more fundamental: alias resolution can collapse identity, while collections have no single JSON property-name equivalent. LiveParse rejects alias and complex collection keys rather than inventing a serialization.

Tags and application-specific types

A YAML tag identifies a node's type. The recommended core schema resolves familiar scalar types, while YAML 1.1 and custom schemas can add timestamps, binary values, ordered mappings, sets, or application-defined types. A tag such as !Duration 5m might construct a duration object in one application and be unknown in another.

Stripping a tag and keeping only its content can change meaning without an error. LiveParse stops YAML-to-JSON conversion for !!omap, !!pairs, !!binary, !!set, unresolved tags, and application-specific custom tags. Convert such data only after defining a trusted, testable mapping in the system that owns the type.

Date-shaped scalars demonstrate why schema identity matters. Under YAML 1.2 core, 2026-08-04 is a string. Under a YAML 1.1 schema it may construct a date value; LiveParse serializes a valid constructed date as an ISO 8601 JSON string and emits a timestamp conversion diagnostic. Invalid ranges are rejected, and non-zero digits beyond milliseconds stop conversion rather than being truncated. The resulting JSON string no longer carries a native YAML timestamp tag.

Anchors, aliases, cycles, and expansion limits

An anchor labels a node for later aliases. The alias refers to the same node in YAML's representation graph; it is not merely text substitution. JSON text has no reference identity, so conversion normally expands each occurrence into an ordinary object, array, or scalar. The values may look equal afterward, but the fact that two paths shared one node is gone.

defaults: &defaults
  retries: 3
primary: *defaults
secondary: *defaults

Nested aliases can multiply the constructed output, and YAML graphs can contain cycles that a JSON tree cannot express. LiveParse bounds alias construction with a maximum alias count of 50 per YAML document and rejects cyclic aliases during JSON serialization. Learn why in the anchors, aliases, and merge keys guide.

The legacy << merge key is separate from core anchor and alias syntax. Under YAML 1.1, an unquoted << receives the legacy merge tag and stops LiveParse conversion because merge expansion is disabled. A quoted "<<" key in YAML 1.1 or a literal << key under YAML 1.2 Core remains an ordinary string key. Do not assume a target application shares that policy.

Multiple documents need an explicit container policy

A YAML presentation stream can contain several documents separated by ---. One JSON text contains one top-level JSON value. There is no universal rule saying multiple YAML documents should become newline-delimited JSON, an array, an object, or several output files.

---
name: first
---
name: second

LiveParse converts this stream to [{"name":"first"},{"name":"second"}], formatted with the chosen indentation, and emits DOCUMENT_STREAM_TO_ARRAY. That policy preserves document order and produces one valid JSON value, but it changes the top-level shape. Confirm that an array is acceptable to the receiving API before using the result.

Number syntax and interoperability

JSON's grammar allows decimal numbers but excludes NaN and infinity. RFC 8259 notes that implementations commonly use IEEE 754 binary64 and that exact interoperability for integers is strongest in the range from negative 2^53 + 1 through positive 2^53 - 1. JSON text can contain a larger integer token, yet a JavaScript Number consumer may round it.

LiveParse parses YAML integers as big integers and can emit their exact decimal token into JSON. For finite decimals, it stops before runtime rounding, underflow, or overflow would change the value; an equivalent spelling may still normalize. These policies preserve the supported token through this conversion step but do not make every later parser lossless. When an identifier exceeds a consumer's safe integer range, use a quoted string or a documented arbitrary-precision pipeline.

A defensible conversion workflow

1. Validate syntax under the intended YAML schema. Do not let an accidental 1.1/1.2 default determine booleans and dates.
2. Inspect the graph. Review documents, anchors, aliases, tags, comments, and non-string keys with the YAML Viewer.
3. Define loss policy. Decide whether comments may be omitted, aliases may be expanded, timestamps may become strings, and multiple documents may become an array.
4. Reject unsupported meaning. Stop on alias or complex keys, key collisions, unsupported tags, YAML 1.1 merge-tag keys, cycles, non-finite values, precision-losing decimals or timestamps, and resource limits.
5. Validate generated JSON. Open the result in the JSON Formatter and Validator and test it with the actual receiving API or schema.
6. Compare application values. Use the JSON Compare tool for compatible snapshots, while remembering that comments and alias identity have already left the model.

This layered workflow parallels XML conversion: an XML Viewer can expose a parsed tree, but transforming attributes, namespaces, comments, mixed content, and ordered children into JSON still requires an application-specific mapping. Syntax alone never invents the right domain model.