YAML Ain't a Markup Language (YAML), and as configuration formats go, it's easy on the eyes. It has an intuitive visual structure, and its logic is pretty simple: indented bullet points inherit properties of parent bullet points.
But this apparent simplicity can be deceptive.
It's easy (and misleading) to think of YAML as just a list of related values, no more complex than a shopping list. There is a heading and some items beneath it. The items below the heading relate directly to it, right? Well, you can test this theory by writing a little bit of valid YAML.
Open a text editor and enter this text, retaining the dashes at the top of the file and the leading spaces for the last two items:
---
Store: Bakery
Sourdough loaf
Bagels
Save the file as example.yaml (or similar).
If you don't already have yamllint
installed, install it:
$ sudo dnf install -y yamllint
A linter is an application that verifies the syntax of a file. The yamllint
command is a great way to ensure your YAML is valid before you hand it over to whatever application you're writing YAML for (Ansible, for instance).
Use yamllint
to validate your YAML file:
$ yamllint --strict shop.yaml || echo “Fail”
$
But when converted to JSON with a simple converter script, the data structure of this simple YAML becomes clearer:
$ ~/bin/json2yaml.py shop.yaml
{“Store”: “Bakery Sourdough loaf Bagels”}
Parsed without the visual context of line breaks and indentation, the actual scope of your data looks a lot different. The data is mostly flat, almost devoid of hierarchy. There's no indication that the sourdough loaf and bagels are children of the name of the store.
[ Readers also liked: Ansible: IT automation for everybody ]
How data is stored in YAML
YAML can contain different kinds of data blocks:
- Sequence: values listed in a specific order. A sequence starts with a dash and a space (
-
). You can think of a sequence as a Python list or an array in Bash or Perl. - Mapping: key and value pairs. Each key must be unique, and the order doesn't matter. Think of a Python dictionary or a variable assignment in a Bash script.
There's a third type called scalar
, which is arbitrary data (encoded in Unicode) such as strings, integers, dates, and so on. In practice, these are the words and numbers you type when building mapping and sequence blocks, so you won't think about these any more than you ponder the words of your native tongue.
When constructing YAML, it might help to think of YAML as either a sequence of sequences or a map of maps, but not both.
YAML mapping blocks
When you start a YAML file with a mapping statement, YAML expects a series of mappings. A mapping block in YAML doesn't close until it's resolved, and a new mapping block is explicitly created. A new block can only be created either by increasing the indentation level (in which case, the new block exists inside the previous block) or by resolving the previous mapping and starting an adjacent mapping block.
The reason the original YAML example in this article fails to produce data with a hierarchy is that it's actually only one data block: the key Store
has a single value of Bakery Sourdough loaf Bagels
. YAML ignores the whitespace because no new mapping block has been started.
Is it possible to fix the example YAML by prepending each sequence item with a dash and space?
---
Store: Bakery
- Sourdough loaf
- Bagels
Again, this is valid YAML, but it's still pretty flat:
$ ~/bin/json2yaml.py shop.yaml
{“Store”: “Bakery - Sourdough loaf - Bagels”}
The problem is that this YAML file opens a mapping block and never closes it. To close the Store
block and open a new one, you must start a new mapping. The value of the mapping can be a sequence, but you need a key first.
Here's the correct (and expanded) resolution:
---
Store:
Bakery:
- ‘Sourdough loaf’
- ‘Bagels’
Cheesemonger:
- ‘Blue cheese’
- ‘Feta’
In JSON, this resolves to:
{“Store”: {“Bakery”: [“Sourdough loaf”, “Bagels”],
“Cheesemonger”: [“Blue cheese”, “Feta”]}}
As you can see, this YAML directive contains one mapping (Store
) to two child values (Bakery
and Cheesemonger
), each of which is mapped to a child sequence.
YAML sequence blocks
The same principles hold true should you start a YAML directive as a sequence. For instance, this YAML directive is valid:
Flour
Water
Salt
Each item is distinct when viewed as JSON:
[“Flour”, “Water”, “Salt”]
But this YAML file is not valid because it attempts to start a mapping block at an adjacent level to a sequence block:
---
- Flour
- Water
- Salt
Sugar: caster
It can be repaired by moving the mapping block into the sequence:
---
- Flour
- Water
- Salt
- Sugar: caster
You can, as always, embed a sequence into your mapping item:
---
- Flour
- Water
- Salt
- Sugar:
- caster
- granulated
- icing
Viewed through the lens of explicit JSON scoping, that YAML snippet reads like this:
[“Flour”, “Salt”, “Water”, {“Sugar”: [“caster”, “granulated”, “icing”]}]
[ A free guide from Red Hat: 5 steps to automate your business. ]
YAML syntax
If you want to comfortably write YAML, it's vital to be aware of its data structure. As you can tell, there's not much you have to remember. You know about mapping and sequence blocks, so you know everything you need have to work with. All that's left is to remember how they do and do not interact with one another. Happy coding!
Sobre el autor
Seth Kenlon is a Linux geek, open source enthusiast, free culture advocate, and tabletop gamer. Between gigs in the film industry and the tech industry (not necessarily exclusive of one another), he likes to design games and hack on code (also not necessarily exclusive of one another).
Navegar por canal
Automatización
Las últimas novedades en la automatización de la TI para los equipos, la tecnología y los entornos
Inteligencia artificial
Descubra las actualizaciones en las plataformas que permiten a los clientes ejecutar cargas de trabajo de inteligecia artificial en cualquier lugar
Nube híbrida abierta
Vea como construimos un futuro flexible con la nube híbrida
Seguridad
Vea las últimas novedades sobre cómo reducimos los riesgos en entornos y tecnologías
Edge computing
Conozca las actualizaciones en las plataformas que simplifican las operaciones en el edge
Infraestructura
Vea las últimas novedades sobre la plataforma Linux empresarial líder en el mundo
Aplicaciones
Conozca nuestras soluciones para abordar los desafíos más complejos de las aplicaciones
Programas originales
Vea historias divertidas de creadores y líderes en tecnología empresarial
Productos
- Red Hat Enterprise Linux
- Red Hat OpenShift
- Red Hat Ansible Automation Platform
- Servicios de nube
- Ver todos los productos
Herramientas
- Training y Certificación
- Mi cuenta
- Soporte al cliente
- Recursos para desarrolladores
- Busque un partner
- Red Hat Ecosystem Catalog
- Calculador de valor Red Hat
- Documentación
Realice pruebas, compras y ventas
Comunicarse
- Comuníquese con la oficina de ventas
- Comuníquese con el servicio al cliente
- Comuníquese con Red Hat Training
- Redes sociales
Acerca de Red Hat
Somos el proveedor líder a nivel mundial de soluciones empresariales de código abierto, incluyendo Linux, cloud, contenedores y Kubernetes. Ofrecemos soluciones reforzadas, las cuales permiten que las empresas trabajen en distintas plataformas y entornos con facilidad, desde el centro de datos principal hasta el extremo de la red.
Seleccionar idioma
Red Hat legal and privacy links
- Acerca de Red Hat
- Oportunidades de empleo
- Eventos
- Sedes
- Póngase en contacto con Red Hat
- Blog de Red Hat
- Diversidad, igualdad e inclusión
- Cool Stuff Store
- Red Hat Summit