Serialization 05 📄 Choosing a Serialization Format — A Decision Framework
The choice between YAML, TOML, JSON, and XML is not a matter of taste. Each format was designed for a specific job, and selecting the wrong one creates a gap that teams fill with external documentation, custom tooling, and workarounds for limitations the format was never meant to overcome. The decision framework in this chapter is organized around three questions: who edits the file (humans or machines), what the file represents (configuration or data exchange), and what ecosystem already consumes it.
This chapter covers the strengths and constraints of each format, the security considerations that differentiate them, and the decision matrix that maps project types to format choices. The sections that follow walk through the four formats and their native capabilities, the security and parsing risks, and the selection strategy that prioritizes human context for hand-edited files and machine efficiency for API payloads.
Key point: Use YAML for CI/CD and Kubernetes because the ecosystem requires it, TOML for application configuration because it balances explicit typing with comment support, JSON for API responses because it is universal and safe, and XML only when a schema-driven enterprise system already uses it.
Why a decision framework exists
The “best format” myth. There is no universal winner. A 2026 comparison concludes directly: “There’s no universal winner. Each format excels in different scenarios” . YAML wins for DevOps and CI/CD because those ecosystems standardized on it; TOML is best for application configuration; JSON is the safe choice for data exchange. The decision is contextual, not absolute.
The human-editing problem. A file that a person edits needs comments to explain why a value is set. JSON has no native comments; the OpenJDK project filed a ticket to extend its bot configuration format specifically because “JSON is pretty nice to work with, but has a major drawback that makes it unsuitable for config files, it doesn’t support comments” . TOML and YAML both support comments natively, which is why they dominate configuration use cases.
The security problem. YAML’s flexibility is a liability at the boundary. The yaml.load() function in Python can execute arbitrary code through tags like !!python/object/apply:os.system, and the recommendation is to always use yaml.safe_load() . JSON has no such risk: it cannot express code execution, includes, or references. TOML is safe by design because its expressive range is too narrow to embed executable constructs .
a. YAML: the DevOps standard, with caveats
YAML’s position is ecosystem-driven. GitHub Actions, GitLab CI, CircleCI, Docker Compose, Kubernetes, and Ansible all use YAML as their configuration language . A team writing CI/CD pipelines does not choose YAML because it is the best format; they choose it because the tools require it.
The format’s strengths are native comments, human readability for nested structures, and anchor/alias support for reusing configuration blocks . Its weaknesses are equally well-documented: indentation sensitivity makes whitespace errors common, implicit typing produces the “Norway problem” where unquoted NO parses as false in YAML 1.1, and the full specification is complex enough that different parsers implement different subsets .
YAML is the correct choice when the ecosystem mandates it (CI/CD, Kubernetes, Docker) and when the configuration is deeply nested and human-readable comments are essential. It is the wrong choice for simple flat configuration (TOML is simpler) or for API payloads (JSON is faster and safer).
b. TOML: the application configuration format
TOML occupies the space YAML leaves open: configuration that humans edit, with explicit typing and no implicit resolution. The format was created as a reaction to YAML’s complexity, and its design philosophy is “minimal, obvious” . A string is always quoted, a boolean is always true or false, and there is no resolver guessing whether NO means the country or a boolean.
The format’s adoption is concentrated in package management and application settings. Rust’s Cargo.toml and Python’s pyproject.toml are the two most visible use cases, and they demonstrate TOML’s strengths: table headers provide clear structure, dotted keys handle nesting without indentation sensitivity, and the type system is small enough to be predictable . A 2016 Python packaging discussion summarized the trade-off: TOML was chosen over YAML because YAML “ended up over-engineered” and JSON “sucks as a human-editable format, because it’s too strict over things like commas and has no comments” .
TOML is the correct choice for application configuration files, especially in Rust and Python projects, and for any configuration where explicit typing matters and the file is small enough that nested arrays of tables do not become unwieldy. It is the wrong choice for deeply nested data where the header syntax becomes repetitive, and for data interchange, because TOML requires a hash table at the root and cannot represent top-level arrays .
c. JSON and XML: data exchange versus schema-driven systems
JSON is the universal data exchange format. It is supported by every language’s standard library, every HTTP client, and every API framework. Its strict syntax (double-quoted keys, no trailing commas, no comments) makes parsers simple and fast, and its lack of executable constructs makes it safe at the boundary . The trade-off is that the strictness that makes JSON good for machines makes it poor for humans: no comments, no trailing commas, and quoted keys add noise to hand-edited files.
XML occupies a different niche. It is verbose, but it is expressive: attributes, namespaces, mixed content, and schema validation are native. The format remains dominant in enterprise systems, document formats (Office Open XML, SVG), and protocol definitions where schema enforcement matters . For configuration, XML has been largely overtaken by YAML and TOML “due to their content-forward syntax” . XML is the correct choice when a schema already exists (enterprise integration, document formats) or when the data model genuinely requires attributes distinct from child elements. It is the wrong choice for new application configuration.
Complete Example Session
# ============================================
# PART 1: THE SAME CONFIGURATION IN FOUR FORMATS
# ============================================
# YAML: readable, comments, indentation-sensitive
# server:
# host: localhost
# port: 8080 # dev port
# debug: true
# TOML: explicit types, table headers, no indentation
# [server]
# host = "localhost"
# port = 8080 # dev port
# debug = true
# JSON: strict, no comments, machine-first
# {
# "server": {
# "host": "localhost",
# "port": 8080,
# "debug": true
# }
# }
# XML: verbose, attributes and elements, schema-ready
# <config>
# <server host="localhost" port="8080" debug="true"/>
# </config>
# ============================================
# PART 2: DECISION BY FILE PURPOSE
# ============================================
# CI/CD pipeline → YAML (GitHub Actions requires it)
# Kubernetes manifest → YAML (ecosystem standard)
# App config (Rust) → TOML (Cargo.toml)
# App config (Python) → TOML (pyproject.toml)
# App config (generic) → TOML (explicit, comments)
# REST API response → JSON (universal, safe)
# Enterprise schema → XML (existing schema)
# ============================================
# PART 3: THE SECURITY DIMENSION
# ============================================
# YAML: yaml.load() can execute code
# → always yaml.safe_load()
# JSON: no execution risk (no includes, no references)
# TOML: no execution risk (too narrow to embed code)
# XML: external entity attacks possible (XXE)
# → disable external entity processing
# ============================================
# PART 4: HYBRID STACKS ARE NORMAL
# ============================================
# A single project often uses:
# TOML for pyproject.toml / Cargo.toml
# YAML for CI/CD workflows
# JSON for API schemas and package.json
# XML for legacy integration if required
#
# The choice is per-file, not per-project.The parts covered the same data in four formats, the decision by file purpose, the security dimension per format, and the hybrid stack that most projects actually use.
Quick Reference
Format Comparison
| Format | Comments | Typing | Indentation | Best For |
|---|---|---|---|---|
| YAML | Yes | Implicit | Significant | CI/CD, K8s |
| TOML | Yes | Explicit | Not significant | App config |
| JSON | No | Strict | Not significant | APIs |
| XML | Yes | Schema-driven | Not significant | Enterprise |
Decision Matrix
| Requirement | Format | Reason |
|---|---|---|
| CI/CD pipeline | YAML | Ecosystem standard |
| Kubernetes manifest | YAML | Ecosystem standard |
| Rust package config | TOML | Cargo.toml |
| Python project config | TOML | pyproject.toml |
| Generic app config | TOML | Explicit + comments |
| API response | JSON | Universal, safe |
| Enterprise integration | XML | Schema exists |
Security Comparison
| Format | Risk | Mitigation |
|---|---|---|
| YAML | Code execution via yaml.load | yaml.safe_load |
| JSON | None (no executable constructs) | — |
| TOML | None (too narrow) | — |
| XML | XXE (external entities) | Disable external entities |
Best Practices
✅ Do This:
# Use YAML when the ecosystem requires it
# GitHub Actions, K8s, Docker Compose # ✅
# Use TOML for application config
# [server]
# port = 8080 # ✅
# Use JSON for API payloads
# {"status": "ok"} # ✅
# Use safe_load for YAML
yaml.safe_load(file) # ✅❌ Don’t Do This:
# Force YAML into a TOML-shaped flat config
# (TOML is simpler for flat key-value) # ❌
# Use JSON for hand-edited config
# (no comments, trailing comma errors) # ❌
# Use XML for new application config
# (verbose, no advantage over TOML/YAML) # ❌
# Use yaml.load on untrusted input
yaml.load(file) # ❌Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Choosing YAML for flat config | Familiarity, not fit | TOML is simpler and typed |
| JSON config loses intent | No comments | Use TOML or YAML |
YAML NO parsed as boolean | Implicit typing | Quote ambiguous values or use TOML |
| XML schema complexity for simple config | Over-engineering | Use TOML or YAML |
Security audit flags yaml.load | Code execution risk | Replace with safe_load |
Real-World Examples
1. CI/CD workflow (YAML)
on: push
jobs:
test:
runs-on: ubuntu-latest2. Rust package (TOML)
[package]
name = "my-crate"
version = "0.1.0"3. Python project (TOML)
[project]
name = "my-package"
dependencies = ["requests"]4. API response (JSON)
{"status": "ok", "data": {"id": 1}}5. Kubernetes manifest (YAML)
apiVersion: apps/v1
kind: Deployment6. Docker Compose (YAML)
services:
web:
image: nginx7. Generic app config (TOML)
[server]
port = 8080
debug = true8. Safe YAML load
config = yaml.safe_load(open("config.yaml"))9. JSON schema validation
{"$schema": "...", "type": "object"}10. XML with schema
<config xmlns="...">
<server port="8080"/>
</config>Visual
The Decision Tree
┌─────────────────────────────────────────────────────────┐
│ WHAT IS THE FILE FOR? │
│ │
│ Machine-to-machine data exchange? │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ YES NO │
│ │ │ │
│ ▼ ▼ │
│ JSON Is a schema already required? │
│ (safe, │ │
│ universal) │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ YES NO │
│ │ │ │
│ ▼ ▼ │
│ XML Is the ecosystem CI/CD? │
│ (schema) │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ YES NO │
│ │ │ │
│ ▼ ▼ │
│ YAML TOML │
│ (standard) (explicit, │
│ comments) │
└─────────────────────────────────────────────────────────┘Format Strengths
┌─────────────────────────────────────────────────────────┐
│ STRENGTH MATRIX │
│ │
│ YAML: comments ✓ readability ✓ typing ✗ safety ✗ │
│ TOML: comments ✓ readability ✓ typing ✓ safety ✓ │
│ JSON: comments ✗ readability ✗ typing ✓ safety ✓ │
│ XML: comments ✓ readability ✗ typing ✓ safety ⚠ │
│ │
│ YAML wins on nesting, loses on typing and safety │
│ TOML wins on config, loses on ecosystem lock-in │
│ JSON wins on exchange, loses on human editing │
└─────────────────────────────────────────────────────────┘The Hybrid Stack
┌─────────────────────────────────────────────────────────┐
│ A TYPICAL 2026 PROJECT │
│ │
│ pyproject.toml ◄── TOML (project metadata) │
│ .github/workflows/ ◄── YAML (CI/CD) │
│ package.json ◄── JSON (JS dependencies) │
│ config.toml ◄── TOML (app settings) │
│ api-response.json ◄── JSON (data exchange) │
│ │
│ No single format wins. Each file uses the format │
│ its consumer requires. │
└─────────────────────────────────────────────────────────┘Security Boundary
┌─────────────────────────────────────────────────────────┐
│ TRUSTED VS UNTRUSTED │
│ │
│ Internal config (trusted): │
│ YAML or TOML, comments matter, human edits │
│ │
│ External input (untrusted): │
│ JSON only, no execution risk │
│ YAML requires safe_load, no exceptions │
│ XML requires entity disabling │
│ │
│ The boundary determines the format, not preference │
└─────────────────────────────────────────────────────────┘Summary
| Format | Comments | Typing | Safety | Primary Use |
|---|---|---|---|---|
| YAML | Native | Implicit | Requires safe_load | CI/CD, K8s |
| TOML | Native | Explicit | Safe | App config |
| JSON | None | Strict | Safe | APIs |
| XML | Native | Schema | XXE risk | Enterprise |
Key takeaways:
- The ecosystem decides more than the specification. YAML is the standard for CI/CD and Kubernetes not because it is objectively best, but because those tools standardized on it. Fighting the ecosystem costs more than any format advantage .
- TOML is the best generic application configuration format. It has comments, explicit typing, and a syntax simple enough to avoid YAML’s implicit-typing traps. Its adoption by Cargo and
pyproject.tomlconfirms the fit . - JSON is for data exchange, not human editing. Its lack of comments and strict comma rules make it hostile to hand-maintained configuration, but its universality and safety make it the default for APIs .
- Security is format-dependent. YAML can execute code through
yaml.load; JSON and TOML cannot. Any YAML from an untrusted source must usesafe_load. - A project uses multiple formats, not one. TOML for package metadata, YAML for CI, JSON for APIs, and XML only where a schema already exists. The choice is per-file, determined by the consumer .
Remember: The question is not “which format is best” but “who edits this file and who reads it.” If a human edits it and a build tool reads it, TOML or YAML. If a machine produces it and a machine consumes it, JSON. If the ecosystem already requires a format—GitHub Actions, Kubernetes, Cargo, pyproject.toml—use that format and stop evaluating alternatives. The cost of choosing against the ecosystem is paid in custom tooling, missing editor support, and explanations to every new contributor. Choose the format the file’s consumers expect, and reserve the debate for the few files where no consumer dictates the answer.
Stop using slow, ad-bloated tool sites! 🤮
🔎 Search “KandZ Tools” on Google to use many professional utilities for free.
KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)
⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free
🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!