> ## 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 Part 2
> Explains when to use YAML mappings versus sequences, how to nest them, and how to represent single objects, lists, and sequences of mappings.
Many people learning YAML ask: when should I use a dictionary (mapping) versus a list (sequence), and how do I combine them? This article clarifies those choices and shows how to represent nested data and multiple objects in YAML.
All common data representation formats — XML, JSON, YAML — are used to describe structured information such as:
* an organization and its employees,
* a school and its students and grades,
* a manufacturer and its products and specifications.
For clarity, we'll use a car example throughout.
## Single object: use a mapping (dictionary)
A car is a single object with named properties: color, model, transmission, price. To represent one object and its attributes, use a YAML mapping:
```yaml theme={null}
Color: Blue
Model:
Name: Corvette
Year: 1995
Transmission: Manual
Price: "$20,000"
```
Notes:
* `Model` is a nested mapping containing `Name` and `Year`. Use nested mappings when a property itself has sub-properties.
* Keys in mappings are names (strings) that map to scalars or other collections (mappings or sequences).
## Multiple values of the same kind: use a sequence (list)
When you need several values of the same type (for example, a list of car names), use a YAML sequence:
```yaml theme={null}
- Ford
- BMW
- Fiat
- Corvette
- Tesla
- Toyota
```
A sequence is an ordered collection. The order of items matters.
## Multiple objects: use a sequence of mappings
To store a collection of cars where each entry has full properties, use a sequence of mappings. Each list item is a mapping that describes one car:
```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: Blue
Model:
Name: Corvette
Year: 1995
Transmission: Manual
Price: "$20,000"
- Color: Black
Model:
Name: Corvette
Year: 1995
Transmission: Manual
Price: "$21,000"
```
This pattern — a sequence of mappings — is the standard way to represent multiple objects of the same type, each with its own properties.
## Quick rules of thumb
* Use a mapping (dictionary) to represent a single object with named properties.
* Use a sequence (list) to represent multiple values/items of the same kind.
* Use a sequence of mappings when you need to represent several objects and each object has its own set of properties.
| Concept | When to use | Example |
| - | - | - |
| Mapping (dictionary) | Single object with named properties | `Color: Blue` |
| Sequence (list) | Multiple values of the same type | `- Ford` |
| Sequence of mappings | Multiple objects each with properties | `- Color: Blue\n Model:\n Name: Corvette` |
## Ordering and comments
* Mappings (dictionaries) are unordered by the YAML specification. Your program should not rely on key order for correctness. Some YAML parsers preserve insertion order, but it's an implementation detail, not guaranteed by the spec.
```yaml theme={null}
# Dictionary A
Banana:
Calories: 89
Fat: 0.3
Carbs: 22.8
# Dictionary B (same content, different key order)
Banana:
Carbs: 22.8
Fat: 0.3
Calories: 89
```
* Sequences (lists) are ordered. Different item order means different meaning:
```yaml theme={null}
# List A
- Apple
- Banana
# List B
- Banana
- Apple
```
* Comments start with `#` when used outside quoted scalars; anything after `#` on that line is ignored by the parser:
```yaml theme={null}
# This is a comment and will be ignored
Color: Red # This inline comment is also ignored
```
Remember: mappings are unordered by specification (key order doesn't affect meaning), sequences are ordered (item order matters), and `#` begins a comment when used outside a quoted string.
## Next steps
Try converting datasets between:
* a single mapping (one object),
* a sequence of scalars (list of names),
* and a sequence of mappings (list of full objects).
This will reinforce when to choose mappings vs sequences and how to nest them effectively.
## Links and references
* YAML specification: [https://yaml.org/spec/](https://yaml.org/spec/)
* YAML tutorial and examples: [https://yaml.org/start.html](https://yaml.org/start.html)
* Related: [JSON vs YAML overview](https://www.json.org/json-en.html)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.