YAML Tutorial: How To’s, Best Practices & Getting Started

What is YAML?

YAML (YAML Ain’t Markup Language) is a human-readable data format that simplifies configuration files, offering a lightweight alternative to JSON, INI, and XML. Its clear, indentation-based structure makes it ideal for managing configuration settings in a variety of applications, from web development to embedded systems and infrastructure as code (IaC).

What sets YAML apart is its readability by both humans and machines, making it a favorite in DevOps for tools like Docker and Kubernetes. In embedded projects, YAML excels at organizing hardware configurations, settings, and testing scenarios in a clean, easily understandable format, reducing the need for complex code. Consider the following example:

device:
  name:           SensorNode         # Device name
  version:        1.2.3              # Firmware version
  manufacturer:   DojoFive           # Manufacturer details
  settings:
    led_blink_rate_hz: 5             # LED blink rate in hertz
    power_mode:      low             # Set to low for energy efficiency
    interfaces:
      usb:
        enabled:    true             # USB interface is enabled
        vid:        1234             # USB vendor ID
        pid:        5678             # USB product ID
      wifi:
        enabled:    true             # Wi-Fi interface is enabled
        ssid:       "SensorNet"      # Wi-Fi network SSID
        password:   "SecurePass123"  # Wi-Fi password

Even without any knowledge of YAML, this configuration file is easy to understand.

Why to Use YAML in Embedded Software Development

YAML competes with other data serialization formats such as JSON and INI files, each of which has its own strengths. However, YAML offers distinct advantages over these formats, particularly for embedded software development.

While JSON is also readable by humans, it relies on brackets, commas, and quotes, which can make larger configuration files more difficult to manage and less intuitive. YAML, in contrast, uses indentation to represent structure, reducing visual clutter and making it easier to comprehend at a glance.

YAML also supports comments, while JSON does not. This feature is especially valuable in embedded projects, where complex configuration files often need to be reviewed and edited by multiple team members, including non-developers.

INI files are limited to basic key-value pairs and cannot easily represent more complex data structures. YAML, on the other hand, is more straightforward, making it more suitable for embedded systems that require detailed and dynamic configuration settings, such as peripheral setups and hardware configurations.

Getting Started with YAML: Key-Value Pairs, Dictionaries, and Lists

YAML files center on key-value pairs. The concept is intuitive, as shown in the following example of a YAML definition that captures metadata about a device. YAML is often used for tracking device versions, manufacturers, and other essential metadata.

version: 1.0.0
manufacturer: Dojo Five

Key-value pairs can be nested to create dictionaries. Nesting is indicated by indentation (Note: Indentation is defined by spaces, not tabs.) Here we see a dictionary defining device-specific parameters such as LED blink rates, power-saving modes, and USB configurations:

parameters:
  led_blink_rate_hz: 1
  sleep_mode: off
  usb:
    vid: 0001
    pid: 1234
    Enable_hs: false

In embedded projects, this structure is useful for storing settings that are adjustable via firmware updates.

YAML also supports lists, which are defined by dashes nested under a key. Among other functions, lists can be used to manage device entitlements, licensing, and feature configurations, allowing easy adjustment without modifying the core codebase:

parameters:
  license: 123456789
  entitlements:
    - deep_sleep_mode
    - real_time_clock
    - free_run

Together, these examples highlight how YAML is often used in embedded systems to handle configurations like device metadata, adjustable settings, and even licensing and entitlements—essential tasks for maintaining flexibility without modifying source code.

Adding Comments in YAML

Comments in YAML are denoted by the # symbol and are ignored by the parser, making them a useful tool for improving the readability of configuration files. By adding comments, developers can explain the purpose of specific settings or provide guidance for future updates, which is especially helpful in larger, collaborative projects. For example:

# This section configures the device's power settings
power_mode: low  # Set to low for power-saving mode

# USB configuration details
usb:
  enabled: true  # USB interface is enabled
  vid: 1234
  pid: 5678

Comments can be placed on their own lines or at the end of a line, as shown above. They help ensure that configuration files are clear and maintainable by the entire development team.

Common Pitfalls

As with any language, YAML is sensitive to syntax errors and other basic mistakes. Common pitfalls include:

• Indentation errors: YAML relies heavily on indentation, and mixing tabs with spaces can cause parsing errors.
• Case sensitivity: Ensure consistency in how keys are defined—e.g., Enable_hs vs. enable_hs.

Structuring a Simple YAML Configuration File

YAML is ideal for organizing complex data structures in a readable way, especially for managing on-device configurations in embedded systems. By defining device parameters in YAML, developers can manage settings that are adjustable via firmware updates, reducing the need for hardcoded changes.

Let’s return to our initial example, which shows how YAML can be used to structure a device configuration file:

device:
  name:           SensorNode         # Device name
  version:        1.2.3              # Firmware version
  manufacturer:   DojoFive           # Manufacturer details
  settings:
    led_blink_rate_hz: 5             # LED blink rate in hertz
    power_mode:      low             # Set to low for energy efficiency
    interfaces:
      usb:
        enabled:    true             # USB interface is enabled
        vid:        1234             # USB vendor ID
        pid:        5678             # USB product ID
      wifi:
        enabled:    true             # Wi-Fi interface is enabled
        ssid:       "SensorNet"      # Wi-Fi network SSID
        password:   "SecurePass123"  # Wi-Fi password

In this example, YAML helps manage key device settings like LED blink rates, power modes, and interface configurations, all in an easy-to-read format. These configurations can be modified without changing the core codebase, making it flexible for on-device management and updates.

Defining a CI/CD Pipeline Using YAML

YAML is also widely used in defining CI/CD pipelines, offering a simple syntax for automating the build, test, and deployment processes. Using YAML for CI/CD helps streamline tasks like testing, container orchestration, and deployment across environments.

Below is an example YAML file that defines a CircleCI pipeline focused on running tests:

steps:
  - attach_workspace:
      at: /opt/app                    # Attach workspace directory for build
  - run:
      name: Wait for DB               # Wait for the database to become available
      command: dockerize -wait tcp://localhost:5432 -timeout 1m
  - run:
      name: Run Tests                 # Execute test suite
      command: |
        if [ ${CIRCLE_PR_USERNAME} ]; then
          MIX_ENV=test mix test;
        else
          MIX_ENV=test mix coveralls.circle;
        fi
  - persist_to_workspace:
      root: /opt/app                  # Save test results and workspace for later stages
      paths:
        - project

This configuration outlines the key steps in running tests in a CI/CD pipeline. It attaches the workspace, waits for the database to be available, runs the test suite, and saves the workspace. YAML’s flexible structure makes it easy to modify and expand this pipeline as needed.

A Summary of YAML Best Practices

1. Use comments: Comments (`#`) help improve the readability of your YAML files.
2. Consistent indentation: Stick to spaces for indentation (avoid tabs).
3. Use YAML linters: Validation tools like yamllint can catch common errors early.
4. Leverage IDE plugins: Many editors support YAML with plugins that highlight syntax errors or provide auto-completion. A good example is Red Hat’s YAML plugin for the popular Microsoft Visual Studio Code (VS Code) IDE.

Conclusion

YAML is a versatile, human-readable format ideal for configuration and serialization in software development. Whether it’s defining hardware parameters in embedded projects or managing CI/CD pipelines, YAML’s simple syntax, hierarchical structure, and readability make it an essential tool.

If you’re ready to take the next step with YAML, try writing a Docker Compose file or defining a simple CI job to see its flexibility firsthand. For more complex workflows, especially in embedded development, Dojo Five is here to help you streamline your EmbedOps processes. We are always happy to help out. You can reach out at any time on LinkedIn or through email!