DocumentationBlogMy Account
Go to App

YAML Quickstart ​

Diagram descriptions in Desgram are crafted using the YAML syntax. Familiarity with YAML allows for a smoother understanding of this process. If you are already acquainted with YAML, feel free to proceed to the next chapter.

What is YAML ? ​

YAML is a human-readable data serialization format. In simple terms, it's a way to structure and represent data in a format that is easy for both humans to read and write.

Think of YAML as a set of rules for organizing information. It uses indentation (spacing at the beginning of lines) to indicate the structure of data, similar to how you might outline tasks or ideas with different levels of indentation.

Here's a very basic example:

yaml
person:
  name: John Doe
  age: 30
  occupation: Developer

In this example, we have a person with attributes like name, age, and occupation. The indentation (spaces before "name," "age," and "occupation") shows that these attributes belong to the "person" category.

YAML is commonly used in configuration files for various applications and is also used in data exchange between languages that can easily interpret this simple and readable structure.

Key-value ​

YAML is expecially useful for expressing key-value pairs, also known as mappings, dictionaries or hashes. This combination is separated by a colon and a space, as in this example:

yaml
from: Website

In this example, we wrote that the value of the field named from is Website.

YAML is hierarchical, meaning that the value of a mapping can be another mapping, as in this example:

yaml
flows:
  HTTP:
    from: Website
    to: Backend
  SQL:
    from: Backend
    to: Database

In this example, we wrote that the value of field named flows is another mapping with 2 keys: HTTP and SQL. The value of the field HTTP is another mapping, composed of 2 key-value pairs: from equal to Website and to equal to Backend. In the same way, the value of the field SQL is another mapping, composed of 2 key-value pairs: from equal to Backend and to equal to Database.

WARNING

As evident in this example, hierarchy in YAML is denoted by indentation using spaces. It's essential that key-value pairs at the same level in the hierarchy are indented with the exact number of spaces. In the Desgram App, this process is simplified by using the tab key, enabling swift indentation and alignment of YAML lines.

Lists ​

Lists of objects (also known as arrays) can be defined by enclosing the list between brackets and separating the elements by a comma, as in this example:

yaml
networks:
  backend:
    nodes: [Website, Backend, Database]

In this example, we wrote that the value of nodes (for the network backend) is a list composed of 3 elements: Website, Backend and Database.

Another way to write lists is by placing one item per line and prefexing them with an hyphen. The previous example can be rewritten:

yaml
networks:
  backend:
    nodes:
      - Website
      - Backend
      - Database

WARNING

Notice how the elements of the list are indented one-level more that the key (nodes) they are associated to.

TIP

In the case of brief lists, the bracket syntax generally proves simpler and quicker to type. Conversely, for more extensive lists, the hyphen syntax might enhance readability. Ultimately, the choice between the two is a matter of personal preference, as both are supported.

Comments ​

Comments begin with # and can start anywhere on a line and continue until the end of the line. Comments must be separated from other tokens by whitespace characters.

Example:

yaml
networks:
#backend network: mostly used to serve API requests to frontend
  backend:
    nodes:
      - Website
      - Backend
      - Database #currently running on PostgreSQL

Supported Types ​

YAML support primitives like strings, numbers, and more. In Desgram, strings are predominantly utilized, typically appearing unquoted. However, they can be enclosed in either double-quotes (") or single-quotes ('). It's important to note that integers and floats are never quoted.

This example illustrates various types and demonstrates the use of quotes to prevent ambiguity:

yaml
a: backend                 # a string
b: "backend"               # a string
c: 123                     # an integer
d: "123"                   # a string, disambiguated by quotes
e: 123.0                   # a float

Additional Resources ​

This is a list of tutorials and guides to learn YAML: