DEV Community

Cover image for How to write a YAML configuration file? | A Step-by-Step Guide for Beginners
Shamim Ansari
Shamim Ansari

Posted on

How to write a YAML configuration file? | A Step-by-Step Guide for Beginners

Writing a YAML configuration file is relatively straightforward, and YAML (YAML Ain't Markup Language) is often used for configuration files due to its readability. YAML uses indentation to represent the structure of data hierarchies. Here's a basic guide on how to write a YAML configuration file:

Start with a Document Indicator: In YAML, each document starts with --- on a new line. This indicates the beginning of a new document or configuration.

---
Enter fullscreen mode Exit fullscreen mode

Define Key-Value Pairs: YAML uses a key-value pair structure. Use a colon : to separate the key from the value, and indent the value with spaces or tabs. Commonly, two spaces per level of indentation are used, but consistency is more important than the number of spaces.

key1: value1
key2: value2
Enter fullscreen mode Exit fullscreen mode

Use Indentation for Nested Data: If you have nested data structures like dictionaries or lists, use proper indentation to represent the hierarchy. YAML is whitespace-sensitive, so make sure to align items correctly.

parent_key:
  child_key1: child_value1
  child_key2: child_value2
Enter fullscreen mode Exit fullscreen mode

Lists and Arrays: To create a list or array, use a hyphen '-' followed by a space to indicate list items. Lists can contain strings, numbers, or other data types.

fruits:
  - apple
  - banana
  - cherry
Enter fullscreen mode Exit fullscreen mode

Comments: You can add comments in YAML using the # symbol. Comments are for human readability and are ignored by most parsers.

# This is a comment
key: value
Enter fullscreen mode Exit fullscreen mode

Quoted Strings: If a string contains special characters or starts with characters that might be misinterpreted as YAML syntax, you can enclose it in single or double quotes.

key: "This is a string with spaces and special characters: @!$"
Enter fullscreen mode Exit fullscreen mode

Multi-line Strings: For multi-line strings, you can use the | character followed by a newline. This preserves newlines and leading/trailing spaces in the string.

description: |
  This is a multi-line
  string with
  preserved formatting.
Enter fullscreen mode Exit fullscreen mode

Anchors and Aliases (Advanced): YAML allows you to use anchors ('&') and aliases ('*') to reference the same value in multiple places within your configuration. This is useful for reducing redundancy.

first_name: &name John
last_name: *name
Enter fullscreen mode Exit fullscreen mode

References to Environment Variables (Advanced): In some cases, you may want to reference environment variables in your YAML configuration. You can do this using a special syntax, such as '${ENV_VAR_NAME}'.

api_key: ${SECRET_API_KEY}
Enter fullscreen mode Exit fullscreen mode

Finalize the Document: End your YAML configuration with '...' or a new '---' to indicate the end of the document.

...
Enter fullscreen mode Exit fullscreen mode

Remember to validate your YAML file using a YAML parser or linter to ensure that it is correctly formatted. YAML can be sensitive to indentation errors, so maintaining proper spacing is crucial for accurate parsing.

Follow me on Linkedin, Twitter

Top comments (1)

Collapse
 
nikolai1312 profile image
Nicolas Evangelista

Was studying this today, thanks for sharing, helped a lot! Great content!