*! version 1.9.2 22Feb2026

help yamlversion 1.9.2

Title

yaml -- Read and write YAML files in Stata

Syntax

yaml subcommand [using filename] [, options]

Subcommands

subcommand

read read YAML file into current dataset (default) or frame

write write Stata data to YAML file

describe display structure of loaded YAML data

list list keys and values

get get metadata attributes for a specific key

validate validate YAML data against requirements

dir list all YAML data in memory (dataset and frames)

frames list only YAML frames in memory (Stata 16+)

clear clear YAML data from memory

See What's New for version history.

Description

yaml provides a unified interface for working with YAML files in Stata.
YAML (YAML Ain't Markup Language) is a human-readable data serialization format
commonly used for configuration files and data exchange.

Default behavior: YAML data is loaded into the current dataset.
This allows the command to work with Stata 14 and later.

Frame option: Use frame(name) to store YAML data in a separate Stata
frame, allowing multiple YAML files in memory simultaneously. This requires
Stata 16 or later.

yaml read

yaml read
using filename
[, frame(name) locals scalars prefix(string) replace verbose
fastread fields(string) listkeys(string) cache(string)]

Reads a YAML file and parses its contents into the current dataset (default) or a frame.

options

frame(name) load into frame yaml_name instead of dataset (Stata 16+)

locals also store values as local macros in r()

scalars also store numeric values as Stata scalars

prefix(string) prefix for macro/scalar names; default is "yaml_"

replace replace existing data in memory

verbose display parsing progress

fastread use fast-read parser (speed-first, limited YAML subset)

fields(string) restrict extraction to specific field keys

listkeys(string) extract list blocks for specified fields (fastread only)

blockscalars capture block scalars in fast-read mode (opt-in)

targets(string) early-exit targets for canonical parse (exact keys)

earlyexit stop parsing once all targets are found (canonical)

stream use streaming tokenization for canonical parse

index(string) materialize an index frame for repeated queries (Stata 16+)

cache(string) cache parsed results in a frame (Stata 16+)

bulk use Mata bulk-load parser for high-performance parsing

collapse produce wide-format output (use with _yaml_collapse helper)

colfields(string) filter collapsed output to specific field names (semicolon-separated)

maxlevel(#) limit collapsed columns by depth (1=no underscores, 2=one underscore, etc.)

indicators preset for wbopendata/unicefdata indicator metadata (implies bulk collapse)

strl use strL storage for values exceeding 2045 characters

fastread is not compatible with locals or scalars.

targets() and earlyexit apply to canonical parsing only and are not supported
with fastread.

cache() accepts a frame name (e.g., cache(mycache)) or a named form
cache(frame=mycache). The stored frame is prefixed as yaml_ if not already.

The following variables are created in canonical mode:

key - Full key name (nested keys use underscore separator)

value - Value as string

level - Nesting level (1 = root)

parent - Parent key name

type - Value type (string, numeric, boolean, null, parent)

In fastread mode, the following variables are created:

key - Top-level key (e.g., indicator code)

field - Field name under the key

value - Field value

list - 1 if list item, 0 otherwise

line - Line number in the YAML file

yaml write

yaml write
using filename
[, frame(name) scalars(namelist)
replace verbose indent(#) header(string)]

Writes Stata data from the current dataset (default) or a frame to a YAML file.

options

frame(name) write from frame yaml_name (Stata 16+)

scalars(namelist) write specified scalars

replace replace existing file

verbose display progress

indent(#) spaces per indent level; default is 2

header(string) custom header comment

Note: To write scalar values to YAML, create scalars first, then use the scalars() option.
Local macros cannot be passed to programs in Stata.

yaml describe

yaml describe
[, frame(name) level(#)]

Displays the structure of YAML data in the current dataset (default) or a frame.

options

frame(name) describe frame yaml_name (Stata 16+)

level(#) maximum nesting level to display; default is all

yaml list

yaml list
[parent]
[, frame(name) keys values separator(string) children stata noheader]

Lists keys and values from YAML data. Optional parent filters to keys under that parent.

options

frame(name) list from frame yaml_name (Stata 16+)

keys return matching keys as delimited list in r(keys)

values return matching values as delimited list in r(values)

separator(string) delimiter for lists; default is space

children return only immediate children of parent

stata format output as Stata compound quotes: `"item1"' `"item2"'

noheader suppress column headers in listing

yaml get

yaml get
parent:keyname | keyname
[, frame(name) attributes(namelist) quiet]

Gets metadata attributes for a specific key (e.g., indicator code) and returns them
as separate r() macros. This is useful for querying indicator metadata by code.

Colon syntax: Use parent:keyname to specify the parent hierarchy.
For example, indicators:CME_MRY0T4 searches for CME_MRY0T4 under indicators.
This is equivalent to searching for key indicators_CME_MRY0T4_*.

options

frame(name) get from frame yaml_name (Stata 16+)

attributes(namelist) specific attributes to retrieve; default is all

quiet suppress output display

Stored results:

r(key) - the key that was searched

r(parent) - the parent hierarchy (if colon syntax used)

r(found) - 1 if attributes found, 0 otherwise

r(n_attrs) - number of attributes found

r(attribute) - value for each attribute found (e.g., r(label), r(unit))

yaml dir

yaml dir
[, detail]

Lists all YAML data currently loaded in memory. This includes both the current
dataset (if it contains YAML data) and any YAML frames (Stata 16+).

YAML data is identified by:

1. Presence of standard YAML variables: key, value, level, parent, type

2. The _dta[yaml_source] characteristic set by yaml read

3. Frame names with yaml_ prefix (for frames)

options

detail show number of entries and source file for each

Stored results:

r(n_total) - total number of YAML sources in memory

r(n_dataset) - 1 if YAML data in current dataset, 0 otherwise

r(n_frames) - number of YAML frames loaded

yaml frames

yaml frames
[, detail]

Lists only YAML frames currently loaded in memory. Requires Stata 16+.
Use yaml dir to see both the current dataset and frames.

YAML frames are identified by the yaml_ prefix in their frame name.

options

detail show number of entries and source file for each frame

Stored results:

r(n_frames) - number of YAML frames loaded

yaml clear

yaml clear
[framename]
[, all]

Clears YAML data from memory.

options

(no argument) clear current dataset (default)

framename clear specific frame yaml_framename (Stata 16+)

all clear all yaml_* frames (Stata 16+)

Examples

Example YAML file (config.yaml):

name: My Project

version: 1.0

indicators:

CME_MRY0T4:

label: Under-5 mortality rate

unit: deaths per 1000 live births

CME_MRY0:

label: Neonatal mortality rate

unit: deaths per 1000 live births

Example 1: Read YAML into current dataset (default)

. yaml read using "config.yaml", replace

Example 2: Read YAML into a frame (Stata 16+)

. yaml read using "config.yaml", frame(config)

// Creates frame yaml_config, preserves current dataset

Example 2b: Fast-scan for large metadata (opt-in)

. yaml read using "indicators.yaml", fastread fields(name description source_id topic_ids)

. listkeys(topic_ids topic_names) cache(ind_cache)

. list in 1/5

Example 3: Work with multiple YAML files using frames

. yaml read using "config.yaml", frame(cfg)

. yaml read using "settings.yaml", frame(settings)

. yaml frames, detail

1. cfg (12 entries) - frame: yaml_cfg

2. settings (8 entries) - frame: yaml_settings

Example 4: Get indicator codes for looping

. yaml read using "indicators.yaml", replace

. yaml list indicators, keys children

Keys under indicators: CME_MRY0T4 CME_MRY0

. foreach ind in `r(keys)' {

. display "Processing: `ind'"

. }

Example 5: Get values with Stata compound quotes

. yaml list indicators, keys children stata

Keys under indicators: `"CME_MRY0T4"' `"CME_MRY0"'

. foreach ind in `r(keys)' {

. display "Processing: `ind'"

. }

Example 6: Get indicator metadata by code (colon syntax)

. yaml read using "config.yaml", replace

. yaml get indicators:CME_MRY0T4

label: Under-five mortality rate

unit: Deaths per 1000 live births

dataflow: CME

. return list

r(key) : "CME_MRY0T4"

r(parent) : "indicators"

r(label) : "Under-five mortality rate"

r(unit) : "Deaths per 1000 live births"

r(dataflow) : "CME"

Example 7: Get specific attributes only

. yaml get indicators:CME_MRY0T4, attributes(label unit)

label: Under-five mortality rate

unit: Deaths per 1000 live births

Example 8: Loop over indicators and get metadata

. yaml list indicators, keys children

. foreach ind in `r(keys)' {

. yaml get indicators:`ind', quiet

. display "`ind': `r(label)' (`r(unit)')"

. }

Example 9: Query from frame

. yaml read using "config.yaml", frame(cfg)

. yaml get indicators:CME_MRY0, frame(cfg)

label: Infant mortality rate

unit: Deaths per 1000 live births

dataflow: CME

Example 10: Parse wbopendata/unicefdata indicator metadata

. yaml read using "indicators.yaml", indicators replace

// Creates wide-format dataset with one row per indicator:

// key, code, name, source_id, source, topic_ids_*, topic_names_*, ...

. list key code name in 1/3

The indicators preset automatically enables bulk + collapse with
default colfields() for standard indicator metadata fields. This replaces
custom vectorized parsers and delivers ~60% faster performance.

Example 11: Write from dataset to YAML

. yaml write using "output.yaml", replace

Example 12: Clear YAML data

. yaml clear

// Clears current dataset

. yaml clear config

// Clears yaml_config frame (Stata 16+)

. yaml clear, all

// Clears all yaml_* frames (Stata 16+)

Stored results

yaml read stores the following in r():

Scalars

r(n_keys) number of keys parsed

r(max_level) maximum nesting depth

Macros

r(filename) name of file read

r(frame) name of frame created (if frame option used)

r(yaml_mode) parsing mode: canonical or fastread

r(cache_hit) 1 if cache was used, 0 otherwise

r(yaml_*) values from YAML file (when locals specified)

yaml list stores the following in r() when keys or values specified:

Macros

r(keys) delimited list of matching keys

r(values) delimited list of matching values

r(parent) parent key used for filtering

Limitations

yaml requires Stata 14.0 for basic functionality.
The frame() option requires Stata 16.0 or later.

yaml handles common YAML structures but does not support:

- Anchors and aliases (&anchor, *alias)

- Complex keys

- Flow style ({key: value})

- Document markers (---)

Block scalars (multi-line strings with | or >) are supported via
blockscalars in fast-read mode and in the canonical parser.

fastread mode is optimized for shallow mappings and list blocks, and does not
support anchors, aliases, or complex nested structures. Use the canonical parser
for full YAML compliance.

Phase 2 options (bulk, collapse, strl) enable high-performance
parsing via Mata. The bulk option uses a Mata-based parser that loads the
entire file into memory for vectorized processing. Use _yaml_collapse after
bulk to produce wide-format output with one row per top-level key.
The strl option stores values as strL to allow values exceeding 2045 characters.

Collapse filter options (v1.8.0): When using collapse, the default behavior
creates columns for every field path in the YAML structure. For deeply nested YAML files
(like indicator metadata), this can produce hundreds of columns. Use these options to
filter the collapsed output:

colfields(string) filters columns to include only specified field names.
Provide fields as a semicolon-separated list (e.g., colfields(code;name;source_id)).
Uses exact case-sensitive matching against the final field name (the part after the last underscore).

maxlevel(#) limits columns by nesting depth, measured as the number of underscores
in the field name plus one. Level 1 includes fields with no underscores (e.g., code, name).
Level 2 adds fields with one underscore (e.g., source_id, topic_names).
Level 3 adds fields with two underscores (e.g., array elements like topic_ids_1).

Example: For wbopendata/unicefdata indicator metadata with fields like code, name,
source_id, description, use:

yaml read using "indicators.yaml", bulk collapse colfields(code;name;source_id;description)

This produces a dataset with one row per indicator and only the four specified columns,
instead of the hundreds that would be created with full collapse.

Author

João Pedro Azevedo

UNICEF

jpazevedo@unicef.org

Also see

Help: yaml examples, what's new, frames, infile, import delimited, file