1. I'd Rather Be Writing
2. Docs
3. Chapter 4: OpenAPI spec and generated reference docs

Working in YAML (OpenAPI tutorial)

Download PDF

Before we dive into the steps of the OpenAPI Tutorial, it will help to have a better grounding in YAML, since this is the most common syntax for the OpenAPI specification document. (You can also use JSON, but the prevailing trend with the OpenAPI document format is YAML.)

YAML stands for “YAML Ain’t Markup Language.” This means that the YAML syntax doesn’t have markup tags such as < or >. Instead, it uses colons to denote an object’s properties and hyphens to denote an array.

• Working with YAML
• YAML is a superset of JSON
• YAML syntax
• Comparing JSON to YAML
• Some features of YAML not present in JSON
• JSON versus YAML for the spec format
• Review and summary
• Let’s get started

Working with YAML

YAML is easier to work with because it removes the brackets, curly braces, and commas that get in the way of reading content.

YAML is an attempt to create a more human-readable data exchange format. It’s similar to JSON (which is actually a subset of YAML) but uses spaces, colons, and hyphens to indicate the structure.

Many computers ingest data in a YAML or JSON format. It’s a syntax commonly used in configuration files and an increasing number of platforms (like Jekyll), so it’s a good idea to become familiar with it.

Smart technical documentation with easy content reuse.

All-in-one platform to create, share, and manage your documentation

YAML is a superset of JSON

For the most part, YAML and JSON are different ways of structuring the same data. Dot notation accesses the values the same way. For example, the Swagger UI can read the openapi.json or openapi.yaml files equivalently. Pretty much any parser that reads JSON will also read YAML. However, some JSON parsers might not read YAML because there are a few features YAML has that JSON lacks (more on that below).

YAML syntax

With a YAML file, spacing is significant. Each two-space indent represents a new level:

level1:
  level2:
    level3:

Each new level is an object. In this example, the level1 object contains the level2 object, which contains the level3 object.

With YAML, you generally don’t use tabs (since tab spacing is non-standard). Instead, you space twice.

Each level can contain either a single key-value pair (also referred to as a dictionary in YAML lingo) or a sequence (a list of hyphens):

level3:
  -
    itema: "one"
    itemameta: "two"
  -
    itemb: "three"
    itembmeta: "four"

The values for each key can optionally be enclosed in quotation marks. If your value has a colon or quotation mark in it, enclose it in quotation marks.

Comparing JSON to YAML

Earlier in the course, we looked at various JSON structures involving objects and arrays. So let’s look at the equivalent YAML syntax for each of these same JSON objects.

You can use Unserialize.me to make the conversion from JSON to YAML or YAML to JSON.

Here are some key-value pairs in JSON:

{
"key1":"value1",
"key2":"value2"
}

Here’s the same structure expressed in YAML syntax:

key1: value1
key2: value2

Here’s an array (list of items) in JSON:

["first", "second", "third"]

In YAML, the array is formatted as a list with hyphens:

- first
- second
- third

Here’s an object containing an array in JSON:

{
"children": ["Avery","Callie","lucy","Molly"],
"hobbies": ["swimming","biking","drawing","horseplaying"]
}

Here’s the same object with an array in YAML:

children:
  - Avery
  - Callie
  - lucy
  - Molly
hobbies:
  - swimming
  - biking
  - drawing
  - horseplaying

Here’s an array containing objects in JSON:

[  
   {  
      "name":"Tom",
      "age":43
   },
   {  
      "name":"Shannon",
      "age":41
   }
]

Here’s the same array containing objects converted to YAML:

-
  name: Tom
  age: 42
-
  name: Shannon
  age: 41

Hopefully, by seeing the syntax side by side, it will begin to make more sense. Is the YAML syntax more readable? It might be difficult to see in these simple examples, but generally it is.

JavaScript uses the same dot notation techniques to access the values in YAML as it does in JSON. (They’re pretty much interchangeable formats.) The benefit to using YAML, however, is that it’s more readable than JSON.

About Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.