> ## Documentation Index > Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt > Use this file to discover all available pages before exploring further. # YAML > Introduction to YAML covering syntax, key concepts like mappings and lists, indentation and nesting rules, examples comparing XML and JSON, and configuration use cases such as Docker and Kubernetes Hello and welcome to this lesson. In this article we'll cover what YAML files are and how to use them. If you already know YAML, you can skim this material — later lessons build on these concepts. If you're new to structured data formats (or only know XML/JSON), these examples and exercises will help you get productive quickly. YAML is a human-friendly format for representing structured data, most commonly used for configuration. Below are three equivalent representations of the same data (a list of servers) shown in XML, JSON, and YAML. Compare them to see how YAML is typically more concise and readable. XML: ```xml theme={null} Server1 John 12232012 active ``` JSON: ```json theme={null} { "Servers": [ { "name": "Server1", "owner": "John", "created": "12232012", "status": "active" } ] } ``` YAML: ```yaml theme={null} Servers: - name: Server1 owner: John created: 12232012 status: active ``` Take a minute to compare these three formats. Next, we’ll examine the YAML syntax and key concepts you'll use in configuration files and manifests. *** ## Basic key-value pair A YAML mapping (dictionary) stores key-value pairs. Keys and values are separated by a colon followed by a space. Example: ```yaml theme={null} Fruit: Apple Vegetable: Carrot Liquid: Water Meat: Chicken ``` *** ## Arrays / lists A YAML sequence (array/list) uses a dash and a space for each element. Example: ```yaml theme={null} Fruits: - Orange - Apple - Banana ``` *** ## Dictionaries (mappings) A mapping groups named properties under a key. Here are nutrition details for two fruits represented as mappings: ```yaml theme={null} Banana: Calories: 105 Fat: 0.4 g Carbs: 27 g Grapes: Calories: 62 Fat: 0.3 g Carbs: 16 g ``` *** ## Indentation matters YAML uses indentation (spaces) to represent structure. Indentation must be consistent: items at the same level use the same number of spaces. Mixing tabs and spaces or using inconsistent indentation can change structure or cause parser errors. For example, these properties belong to `Banana` because they share the same indentation level: ```yaml theme={null} Banana: Calories: 105 Fat: 0.4 g Carbs: 27 g ``` If you accidentally indent `Fat` and `Carbs` more than `Calories`, YAML will treat those values as nested under `Calories`, which is usually invalid and causes parser errors. Always use consistent spaces for indentation (do not mix tabs and spaces). Two spaces per level is common, but the important part is consistent indentation across the file. *** ## Nested structures: lists of mappings and mappings in lists YAML supports arbitrarily nested structures. You can combine sequences and mappings to represent complex objects. For example, a list of fruits where each element is a mapping containing nutrition properties: ```yaml theme={null} Fruits: - Banana: Calories: 105 Fat: 0.4 g Carbs: 27 g - Grapes: Calories: 62 Fat: 0.3 g Carbs: 16 g ``` This pattern (a sequence of mappings) is extremely common in configuration files, where each item in a list contains several named properties. *** ## When to use a mapping vs a list Use mappings (dictionaries) to represent a single object with named properties. Use sequences (lists) when representing multiple items of the same type. Example — a single car as a mapping: ```yaml theme={null} Color: Blue Model: Name: Corvette Year: 1995 Transmission: Manual Price: "$20,000" ``` Example — multiple cars as a list of mappings: ```yaml theme={null} Cars: - Color: Blue Model: Name: Corvette Year: 1995 Transmission: Manual Price: "$20,000" - Color: Grey Model: Name: Corvette Year: 1995 Transmission: Manual Price: "$22,000" - Color: Red Model: Name: Corvette Year: 1995 Transmission: Automatic Price: "$20,000" ``` The table below summarizes the conceptual differences. | Feature | Mappings (dictionaries) | Sequences (lists/arrays) | | - | - | - | | Order | Unordered (key order not important) | Ordered (element order matters) | | Use case | Represent single objects with named fields | Represent collections of items of the same type | | Example | `Model: { Name: Corvette, Year: 1995 }` | `- Blue` (list of colors) | *** ## List of dictionaries (full example) A longer sequence of object records (list of mappings): ```yaml theme={null} - Color: Blue Model: Name: Corvette Year: 1995 Transmission: Manual Price: "$20,000" - Color: Grey Model: Name: Corvette Year: 1995 Transmission: Manual Price: "$22,000" - Color: Red Model: Name: Corvette Year: 1995 Transmission: Automatic Price: "$20,000" - Color: Green Model: Name: Corvette Year: 1995 Transmission: Manual Price: "$23,000" - Color: Black Model: Name: Corvette Year: 1995 Transmission: Automatic Price: "$25,000" ``` *** ## Key notes: mappings vs sequences * Mappings are unordered collections of key-value pairs; key order is not significant for equivalence. Example (same data, different order): ```yaml theme={null} Banana: Calories: 105 Fat: 0.4 g Carbs: 27 g Banana: Calories: 105 Carbs: 27 g Fat: 0.4 g ``` * Sequences are ordered; changing the order changes the sequence: ```yaml theme={null} Fruits: - Orange - Apple - Banana Fruits: - Orange - Banana - Apple ``` These two sequences are not identical because the ordering differs. *** ## Comments Any text after a hash (`#`) on a line is treated as a comment and ignored by YAML parsers. Example: ```yaml theme={null} # This is a comment Fruit: Apple # inline comment ``` Incorrect indentation or trying to use the same key for both a scalar value and a mapping will produce parser errors. Keep scalars and mappings separate, and maintain consistent indentation to avoid "mapping values are not allowed here" and similar errors. *** That covers the YAML basics you need for the upcoming lessons. Try practicing these concepts with hands-on exercises and real configuration files (for example: Docker Compose, Kubernetes manifests, CI config files). Practicing will help you avoid common pitfalls like indentation mistakes and improper mixing of lists and mappings. ## Links and References * YAML official site and specification: [https://yaml.org/](https://yaml.org/) * YAML Tutorial (learn practical syntax): [https://www.yaml.org/start.html](https://www.yaml.org/start.html) * Kubernetes YAML basics: [https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/](https://kubernetes.io/docs/concepts/overview/working-with-objects/kubernetes-objects/) * Examples of YAML in popular tools: * Docker Compose: [https://docs.docker.com/compose/compose-file/](https://docs.docker.com/compose/compose-file/) * GitHub Actions workflow syntax: [https://docs.github.com/actions/learn-github-actions/workflow-syntax-for-github-actions](https://docs.github.com/actions/learn-github-actions/workflow-syntax-for-github-actions) Happy learning — practice small examples and build up to real-world manifests. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.