Skip to main content

📘 YAML and JSON Explained

In Quickstart

and Test Your First Endpoint, we touched on how APIs communicate. But what governs the structure of those APIs? That story begins with YAML, a quiet powerhouse behind OpenAPI.

YAML defines endpoints, request bodies, headers, auth flows, and response types. It’s intuitive and readable, but more importantly, it’s convertible to JSON, the default response format of APIs. The distinction between the two shapes how APIs are written, consumed, and validated.

⏳ Timeline of YAML & JSON in APIs​

1
2001

The Rise of JSON

JSON became the standard for lightweight data exchange. Its simplicity made it the go-to format for AJAX and REST APIs.

2
2010

OpenAPI Specification Adopts JSON

Swagger (now OpenAPI) emerged and formalized JSON as the backbone of API definitions. It allowed developers to describe RESTful APIs in a standardized way.

3
2015

YAML Support Introduced in OpenAPI

OpenAPI added support for YAML, offering a cleaner syntax that reduced verbosity, especially in large schema definitions.

4
2020+

YAML Becomes the Default for Specs

Tools like Swagger Editor, Redoc, and Stoplight began defaulting to YAML for authoring. Git-based workflows favored it for its readability.

Figure 1. The evolution of API data formats: from XML to JSON to YAML, showing where OpenAPI gained traction and how readability became a priority.

✍️ YAML Fundamentals​

  • Indentation
  • Scalars
  • Mappings
  • Sequences
  • Anchors

These fundamentals map directly to how APIs are structured. Once you understand these YAML patterns, you’ll start recognizing them inside every OpenAPI spec, no matter the tool you use.

🛠️ Tool Comparison​

Swagger Editor icon

Swagger Editor

Live-edit OpenAPI YAML files and preview their structure.

✅ Pros
  • YAML-first
  • Real-time error checking
  • Mock server integration
⚠️ Cons
  • Limited theming
  • No Git integration
Postman icon

Postman

Use OpenAPI JSON or YAML to generate requests.

✅ Pros
  • Great for testing
  • Collection generation
  • Visual data output
⚠️ Cons
  • YAML support is read-only
  • Editing YAML requires import/export
Redoc icon

Redoc

Reference documentation site built from OpenAPI YAML.

✅ Pros
  • Readable UI
  • Auto-titles and tag grouping
  • Supports all spec versions
⚠️ Cons
  • Static-only
  • Harder to customize without React

Figure 4. Side-by-side look at how Swagger, Postman, and Redoc support YAML and JSON. Helps you choose the right tool for writing, reviewing, and validating specs.

      ✅ Summary & What’s Next​

      🧠 YAML vs JSON Quiz

      Which format is more human-readable?

      Which format uses curly braces and square brackets?

      Which format supports comments?

      Figure 5. Final recap quiz for YAML vs JSON, placed before the transition to test what you’ve retained from the entire section.

      By now, you’ve explored YAML’s syntax, compared it to JSON, seen how specs transform into output, and tried the tools used in every serious API workflow. YAML isn’t just a format, it’s a workflow bridge from design to delivery.

      In the next section, we leave behind the “how” and go into the “why.” You’ll explore the OpenAPI Spec in its entirety; from reusable components to security, tags, validation, and automated contract testing. This is where YAML and JSON evolve into API governance.

      👉 Continue to OpenAPI Specification