Skip to content
Tutorials Center
My learning

Topics

Lesson 7 of 37 ยท Specification Basics

YAML and JSON Syntax for OpenAPI Documents

Learn the YAML and JSON syntax you need to write OpenAPI by hand: maps, lists, quoting, multiline text, anchors and the pitfalls that break documents.

OpenAPI documents are written in YAML or JSON. They carry exactly the same data model: objects (maps), arrays (lists), strings, numbers, booleans and null. Most teams choose YAML because it is shorter and allows comments, and use JSON when a program produces the file. This lesson gives you just enough of both syntaxes to be confident, and warns about the traps that cause the most confusing errors.

The same data, two syntaxes

YAML
info:
  title: Pet Store
  version: 1.0.0
tags:
  - name: pets
  - name: owners
JSON
{
  "info": { "title": "Pet Store", "version": "1.0.0" },
  "tags": [{ "name": "pets" }, { "name": "owners" }]
}
Idea YAML JSON
Object key: value on indented lines { "key": "value" }
Array - item lines [ "item" ]
Comments # comment not allowed
Strings usually unquoted always double-quoted
Structure indentation (spaces only) braces and brackets

Because YAML is a superset of JSON, a JSON file is valid YAML. Many people mix: YAML for the main structure and short JSON-style { } for tiny objects, like id: { type: integer }.

YAML rules you will use every day

  1. Indent with spaces, never tabs. Two spaces per level is the convention.
  2. Lists of maps: each item starts with - and the following keys line up under the first key.
  3. Quote tricky strings. A string starting with *, &, !, {, [ or containing : or # must be quoted.
  4. Quote status codes: "200" (they are map keys, and some tools reject integer keys).
  5. Multiline text uses | (keep line breaks) or > (fold lines into one paragraph):
YAML
description: |
  First line.
  Second line, keeps its line break.
summary: >
  This long summary is written over
  several lines but becomes one line.

Traps that bite in practice

You write YAML reads it as Fix
version: 1.0 the number 1.0 (a float, not a string) version: "1.0" or 1.0.0
enum: [no, yes] booleans false, true (in YAML 1.1) enum: ["no", "yes"]
example: 08 possibly an octal or integer example: "08"
country: NO boolean in YAML 1.1 parsers country: "NO"
title: Pets: a guide error (: inside) title: "Pets: a guide"
pattern: ^\d+$ works unquoted, but \d inside double quotes needs \\d prefer single quotes: '^\d+$'

Anchors and aliases: avoid them in OpenAPI

YAML has &anchor and *alias to repeat a block. OpenAPI has its own reuse mechanism, $ref, which every tool understands (see components and $ref). Anchors vanish when a tool converts YAML to JSON, so many linters ban them. Use $ref.

Parse both syntaxes and compare

This stand-in reads the same document from YAML and from JSON and shows that the data is identical, then shows two of the traps above in action. (Real tools use the same kind of parser before anything else happens.)

Python Stand-in: YAML and JSON give the same data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Note the PyYAML library follows YAML 1.1 for some details (for example it reads yes as a boolean). Different tools use different YAML versions, which is another reason to quote ambiguous values.

Converting between the two

Terminal
# YAML to JSON and back with Redocly CLI (bundle writes the format of the output file)
npx @redocly/cli bundle openapi.yaml -o openapi.json
npx @redocly/cli bundle openapi.json -o openapi.yaml

Converters remove comments (JSON has none), so keep the YAML as your source of truth and treat the JSON as a build artifact.

Splitting a big document

OpenAPI lets $ref point to other files. Large teams split paths and schemas into folders and bundle them into one file for publishing:

TEXT
openapi.yaml
paths/
  pets.yaml
  owners.yaml
schemas/
  Pet.yaml
YAML
# openapi.yaml
paths:
  /pets:
    $ref: ./paths/pets.yaml
components:
  schemas:
    Pet:
      $ref: ./schemas/Pet.yaml

Bundlers such as Redocly CLI and swagger-cli resolve those references and write a single file that every viewer and generator can read.

Add an editor setting or .editorconfig that forces two-space indentation and no tabs for *.yaml. It prevents the most common YAML mistake before it happens.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why should you write the status code as "200" in YAML?

    Object keys in the data model are strings; quoting keeps YAML from reading an integer.
  2. 2. What does version: 1.0 become in most YAML parsers?

    It is parsed as a float. Quote it, or use a three-part version like 1.0.0, which is a string.
  3. 3. Which multiline marker keeps line breaks in a description?

    | is the literal block style; > folds lines together.
  4. 4. What is the recommended way to reuse a block in OpenAPI?

    $ref is part of the specification and survives conversion between formats; anchors do not.
  5. 5. Which can contain comments?

    YAML supports # comments; standard JSON does not.

Summary

  • YAML and JSON carry the same data; YAML is a superset of JSON, shorter, and allows comments.
  • Indent with spaces; quote status codes, versions and strings with : or special characters.
  • Beware YAML coercions (1.0, no, NO, 08).
  • Reuse with $ref, not anchors; bundle split files into one for publishing.

Next: Data types and formats