fast-yaml (fy) Tool

Professional YAML validation, formatting, and conversion tool with YAML 1.2.2 spec compliance and parallel processing capabilities.

[!IMPORTANT] fast-yaml follows YAML 1.2.2 specification, which differs from PyYAML (1.1). Notable differences: yes/no/on/off are strings (not booleans), octal numbers use 0o prefix.

Quick Reference

Operation	Command	Description
Validate	fy parse config.yaml	Check YAML syntax
Format	fy format -i config.yaml	Format file in-place
Lint	fy lint config.yaml	Validate with diagnostics
YAML → JSON	fy convert json config.yaml	Convert YAML to JSON
JSON → YAML	fy convert yaml config.json	Convert JSON to YAML
Batch format	fy format -i src/	Format entire directory
Parallel	fy format -i -j 8 project/	Use 8 parallel workers

Installation

CLI Tool

# Rust (recommended for CLI)
cargo install fast-yaml-cli

# Verify installation
fy --version

Python API

# Python bindings
pip install fastyaml-rs

# Verify installation
python -c "import fast_yaml; print(fast_yaml.__version__)"

Node.js API

# Node.js bindings
npm install fastyaml-rs

# Verify installation
node -e "const fy = require('fastyaml-rs'); console.log('OK')"

[!NOTE] Requires Rust 1.88+, Python 3.10+, or Node.js 20+ depending on the installation method.

Common Workflows

Single File Validation

# Validate syntax only
fy parse config.yaml

# Validate with detailed diagnostics
fy lint config.yaml

# Format and save
fy format -i config.yaml

Batch Processing

# Format all YAML files in directory
fy format -i src/

# Use glob patterns
fy format -i "**/*.yaml"

# Parallel processing (8 workers)
fy format -i -j 8 project/

# Lint with exclusions
fy lint --exclude "tests/**" .

[!TIP] Use parallel processing (-j flag) for large codebases. Batch mode provides 6-15x speedup on multi-file operations.

Format Conversion

YAML → JSON

# Convert to JSON (pretty-printed)
fy convert json config.yaml

# Compact JSON (no whitespace)
fy convert json --pretty false config.yaml

# Save to file
fy convert json config.yaml > config.json

JSON → YAML

# Convert to YAML
fy convert yaml config.json

# Convert and save
fy convert yaml config.json > config.yaml

# In-place conversion
fy convert yaml -i config.json

[!TIP] Bidirectional conversion is seamless. Use fy convert yaml for JSON → YAML and fy convert json for YAML → JSON.

Python Integration

For programmatic YAML processing in Python:

import fast_yaml

# Load YAML
data = fast_yaml.safe_load(yaml_string)

# Dump YAML with formatting
yaml_str = fast_yaml.safe_dump(data, indent=2, width=80)

# Lint with diagnostics
from fast_yaml._core.lint import lint
diagnostics = lint(yaml_string)
for diag in diagnostics:
    print(f"{diag.severity}: {diag.message} at line {diag.span.start.line}")

See references/python-api.md for complete Python API reference.

Node.js Integration

For TypeScript/JavaScript projects:

import { safeLoad, safeDump } from 'fastyaml-rs';

const data = safeLoad(`name: fast-yaml`);
const yamlStr = safeDump(data);

See references/nodejs-api.md for complete Node.js API reference.

YAML 1.2.2 Compliance

[!WARNING] fast-yaml uses YAML 1.2.2 spec, which differs from PyYAML (1.1). Review references/yaml-spec.md for migration guide.

Key differences from PyYAML (1.1):

Value	PyYAML (1.1)	fast-yaml (1.2.2)
yes/no	Boolean	String
on/off	Boolean	String
014	12 (octal)	14 (decimal)
0o14	Error	12 (octal)

Performance Characteristics

• Small/medium files: Matches PyYAML C (1.3-1.4x faster than js-yaml)
• Batch mode: 6-15x faster than sequential processors
• Parallel documents: 3-6x speedup on 4-8 core systems

[!CAUTION] Process startup overhead (~15ms Python, ~20-25ms Node.js) affects single-file benchmarks. Use persistent servers or batch mode for best performance.

When to Use This Skill

Use fast-yaml when you need to:

• Validate YAML files before deployment or CI/CD
• Format YAML consistently across a codebase
• Convert YAML to JSON for tooling compatibility
• Lint YAML files for syntax errors and best practices
• Batch process multiple YAML files with parallel execution
• Ensure YAML 1.2.2 compliance for standards conformance

Additional Resources

• CLI Reference: references/cli-commands.md - Complete CLI command documentation
• Python API: references/python-api.md - Python integration examples
• Node.js API: references/nodejs-api.md - TypeScript/JavaScript usage
• YAML 1.2.2 Spec: references/yaml-spec.md - Specification differences and migration guide

Examples

Format All Kubernetes Manifests

# Format all k8s manifests in parallel
fy format -i -j 4 k8s/

# Verify no syntax errors
fy lint k8s/

CI/CD Validation

# Validate all YAML in repository
fy lint --exclude "node_modules/**" --exclude ".git/**" .

# Format check (exit code 1 if changes needed)
fy format --check .

Python Data Validation

import fast_yaml
from fast_yaml._core.lint import lint

# Load and validate config
config_yaml = open("config.yaml").read()
diagnostics = lint(config_yaml)

if diagnostics:
    for diag in diagnostics:
        print(f"Error at line {diag.span.start.line}: {diag.message}")
    exit(1)

config = fast_yaml.safe_load(config_yaml)

Troubleshooting

Boolean Values Not Parsing as Expected

fast-yaml follows YAML 1.2.2, where yes/no/on/off are strings. Use explicit true/false:

# Old (YAML 1.1 - PyYAML)
enabled: yes

# New (YAML 1.2.2 - fast-yaml)
enabled: true

See references/yaml-spec.md for complete migration guide.

Performance Not Improving in Batch Mode

Ensure you're using directory paths or glob patterns to activate batch mode:

# ❌ Sequential (slow)
for f in *.yaml; do fy format -i "$f"; done

# ✅ Batch mode (fast)
fy format -i .