Work with YAML in OpenAPI Specs

YAML, which stands for "YAML Ain't Markup Language" or sometimes "Yet Another Markup Language," is a human-readable data serialization language for all programming languages. It's often used for configuration files and data exchange where human readability is a concern. YAML is often used in programming languages where data structures like arrays, dictionaries, and lists must be communicated or stored. YAML files often have a .yaml or .yml extension. In integrator.io, it's used to generate an OpenAPI specification.

YAML relies on indentation for hierarchy and structure, using spaces (not tabs) for indentation. Proper indentation is crucial because it defines the relationships between data elements. Comments can be added using the hashtag (#) symbol, allowing you to annotate your YAML files for better understanding. The basic building blocks include strings, numbers, booleans, lists (arrays), and objects (dictionaries/maps).

Data types and syntax

Strings

A string value is any combination of characters, sometimes surrounded by double quotes. Strings can be written without quotes unless they contain special characters. Multi-line strings can be represented with the | or indicator. Use quotes for strings if they contain special characters.

#string
name: "John Doe"

#special string
description: "This is a 'special' string."


#multiline string (|)
multiline: |
  This is a multi-line
  string in YAML.

#multiline string ()
multiline: 
  This is another way to write
  multi-line strings without
  preserving newlines and spaces.

#quoted string (“ ”)
description: "This is a 'special' string."

Numbers

A number value is any integer or floating point. Number values do not use quotes.

age: 30

Booleans

A boolean value can either be true or false. Boolean values do not use quotes.

isDeveloper: true

Special characters

Special characters have a specific meaning or need special handling due to their significance in the YAML syntax. If your string starts with a special character like :, use quotes to denote it as a string.

Colon (:) – Colons are used to separate keys from values in key-value pairs.

name: John Doe
age: 30

Dash (-) – Dashes are used to denote elements in a YAML list (array).

  fruits:
  - apple
  - banana
  - orange

Double Quotation Marks (") and Single Quotation Marks (') – Strings in YAML can be enclosed in either double or single quotation marks. This is especially useful when a string contains special characters.

message1: "This is a string with a colon: and a dash -"
message2: 'Another string with a colon: and a dash -'

Ampersand (&) and Asterisk (*) – Ampersand and asterisk create anchors and aliases. Anchors mark a position in the YAML document and aliases refer back to that anchor. This is useful for reusing data structures. In this example, original is anchored with &id001, and alias is an alias of that anchor using *id001.

original: &id001
name: John
age: 30

alias: *id001

Tags – YAML provides explicit data typing using tags (e.g., !!str, !!int, !!float, !!bool, etc.) to specify the data type of a scalar value. Tags are used to specify the node data type. In this example, !!int and !!float are tags indicating that 42 is an integer and 3.14 is a floating-point number.

integer: !!int 42
float: !!float 3.14

Lists (arrays)

A list (array) is represented using a list of items indicated by hyphens.

  skills:
  - Java
  - Python
  - YAML

Arrays can be nested inside other arrays, creating multi-dimensional arrays. For example, a list of tasks can contain sub-lists representing task details:

  tasks:
  - task: Task 1
    details:
      - Subtask 1
      - Subtask 2
  - task: Task 2
    details:
      - Subtask 1
      - Subtask 2

Objects (dictionaries/maps)

An object is represented using key-value pairs. In nested structures, objects can also be called maps.

  address:
  city: New York
  zip: '10001'  # Strings containing numbers can be enclosed in quotes

Objects can be nested inside other objects, allowing for the creation of deeply nested data structures. For example, a person object can contain an address object:

  person:
  name: Alice
  age: 30
  address:
    city: New York
    zip: '10001'

In this example, the person object contains name, age, and address keys. The address key contains another object with city and zip keys.

Combine nested arrays and objects

You can also have a combination of nested arrays and objects. For instance, a library can have books represented as objects, and each book can have an array of authors:

  library:
  - title: Book 1
    authors:
      - Author 1
      - Author 2
  - title: Book 2
    authors:
      - Author 3