DEV Community

Farasat Ali Shahzad
Farasat Ali Shahzad

Posted on

YAML vs JSON: The Hidden Problems Most Developers Discover Too Late

#yaml #json #programming #webdev

For years, I assumed YAML was simply a more readable version of JSON.

Many developers do.

Then I spent time debugging configuration files across Docker, Kubernetes, CI/CD pipelines, GitHub Actions, and infrastructure deployments. That's when I learned that YAML's flexibility is both its greatest strength and its biggest trap.

If you've ever spent an hour chasing a configuration bug caused by indentation, unexpected type conversion, or a mysterious parser error, this article is for you.

Why Developers Love YAML

YAML was designed to be human-friendly.

Compare this JSON:

{
  "name": "web-api",
  "port": 8080,
  "enabled": true,
  "hosts": [
    "api.example.com",
    "api2.example.com"
  ]
}
Enter fullscreen mode Exit fullscreen mode

with the equivalent YAML:

name: web-api
port: 8080
enabled: true

hosts:
  - api.example.com
  - api2.example.com
Enter fullscreen mode Exit fullscreen mode

Most people find YAML easier to read.

That's why tools like:

  • Kubernetes
  • Docker Compose
  • GitHub Actions
  • Ansible
  • CircleCI

all heavily rely on YAML.

Why JSON Continues to Dominate APIs

JSON won the web.

Almost every modern API uses JSON because it is:

  • Simple
  • Predictable
  • Strictly structured
  • Easy for machines to process

A parser reading JSON doesn't need to guess much.

The syntax rules are explicit.

For example:

{
  "enabled": true
}
Enter fullscreen mode Exit fullscreen mode

There is very little ambiguity.

This predictability is one reason JSON became the standard format for API communication.

The YAML "Norway Problem"

One of the strangest YAML issues is known as the Norway Problem.

Consider this YAML:

country: NO
Enter fullscreen mode Exit fullscreen mode

Depending on the parser and configuration, NO might be interpreted as:

false
Enter fullscreen mode Exit fullscreen mode

instead of the country code for Norway.

The same can happen with values such as:

yes
no
on
off
Enter fullscreen mode Exit fullscreen mode

Some YAML parsers automatically convert them into boolean values.

That means:

feature: on
Enter fullscreen mode Exit fullscreen mode

might become:

feature: true
Enter fullscreen mode Exit fullscreen mode

without you intending it.

Many production bugs have been caused by this behavior.

Indentation Can Break Everything

JSON ignores visual formatting.

YAML does not.

This works:

services:
  web:
    image: nginx
Enter fullscreen mode Exit fullscreen mode

This does not:

services:
 web:
   image: nginx
Enter fullscreen mode Exit fullscreen mode

A single misplaced space can invalidate an entire configuration file.

Anyone who has worked with Kubernetes manifests has probably experienced this frustration.

Security Risks Most Teams Ignore

A surprising number of developers assume YAML is just a text format.

The reality is more complicated.

Certain YAML parsers support advanced object serialization features.

Historically, insecure parser configurations have allowed:

  • Arbitrary object creation
  • Remote code execution
  • Unsafe deserialization attacks

This is one reason security-conscious teams often prefer JSON when exchanging data between systems.

JSON's simpler structure reduces the attack surface.

JSON Is Boring — And That's Good

One thing I've learned over time:

Boring technologies are often the safest technologies.

JSON is intentionally limited.

You can't add comments.

You can't create complex references.

You can't do fancy tricks.

And that's exactly why JSON behaves consistently across languages, frameworks, and platforms.

When reliability matters, boring wins.

When YAML Is the Better Choice

YAML shines when humans frequently edit the file.

Examples include:

  • Kubernetes manifests
  • Docker Compose
  • CI/CD pipelines
  • Infrastructure as Code
  • Application configuration files

In these scenarios, readability matters more than strict machine efficiency.

When JSON Is the Better Choice

JSON is usually the better option for:

  • APIs
  • Data exchange
  • Microservices communication
  • Browser applications
  • Logging systems
  • Event streams

If a machine writes the file and another machine reads it, JSON is often the safer choice.

Performance Differences

Many developers ask:

"Which is faster?"

In most real-world scenarios:

JSON parsers are generally faster.

Why?

Because JSON has:

  • Simpler grammar
  • Fewer parsing rules
  • Less ambiguity

The performance difference usually won't matter for small files, but it becomes noticeable at scale.

My Rule of Thumb

After working with both formats across multiple projects, my rule is simple:

  • Humans editing configuration → YAML
  • Machines exchanging data → JSON

This approach avoids most of the headaches while preserving the strengths of both formats.

Want to Experiment with YAML and JSON Yourself?

While researching and testing the examples in this article, I found it useful to switch between formats and compare their behavior directly rather than relying only on theory.

If you're working with configuration files, APIs, Docker Compose, Kubernetes manifests, or CI/CD pipelines, these browser-based resources may be useful:

Everything runs locally in the browser, so you can experiment with sample payloads without sending data to a server.

Final Thoughts

YAML isn't bad.

JSON isn't outdated.

They're tools designed for different jobs.

The problem happens when we use one where the other would have been a better fit.

Understanding the tradeoffs can save hours of debugging and help prevent subtle production issues that are surprisingly difficult to diagnose.

What has been your most frustrating YAML or JSON bug?

I'd love to hear your stories in the comments.

Top comments (0)