Glossary

YAML

YAML is a format for hand-written configuration and structured data. It is clear, but significant indentation, differences between parsers, and secrets management require discipline: a syntactically valid file may still be an invalid or unsafe configuration.

Short definition

Readable configuration structured by keys, lists, and spaces.

YAML represents key–value mappings, sequences of items, and scalar values such as strings, numbers, booleans, or null. Nesting is expressed through spaces, so a single indentation change can move a value into another part of the configuration. A comment starts with # and documents can be separated by ---, although most configuration files use a single document.

YAML is not a programming language and its purpose is not to decide how an application behaves. The parser converts text into a data structure, but the target tool determines whether keys are recognised, values have the correct types, and the configuration is safe. This distinction matters for a CI workflow, Docker Compose, or an OpenAPI document, for example.

The problem it solves

Writing human-editable configuration without a custom configuration language.

YAML is used where people need to read and change structured settings alongside code or operational documentation.

Docker Compose definitions of services, networks, volumes, and environment variables
CI/CD workflows with build, test, and deployment steps
OpenAPI specifications of paths, schemas, parameters, and HTTP API responses
framework, monitoring, or infrastructure configuration
portable configuration files that a tool validates against its own specification

Practical example

Service configuration without a production password.

The example contains an environment name, a database reference through an environment variable, and a list of enabled features. The DATABASE_URL value is only the variable name; the actual connection credentials belong in a securely managed environment or secrets mechanism, not in the repository.

The target application must verify that databaseUrl exists, that the list contains supported features, and that the environment complies with deployment rules. Valid YAML with a misspelled key is therefore not evidence of a correct configuration.

YAML

service: catalog-import
environment: production
databaseUrl: ${DATABASE_URL}
enabledFeatures:
  - stock-sync
  - price-validation

How it works

From indented text to a validated tool configuration.

The YAML parser handles syntax; the target tool handles meaning, permissions, and the safe use of values.

The author writes the structure Keys have values and sequences start with a hyphen. Nested blocks use consistent spaces, not tab characters for indentation.
The parser creates data The parser decides whether a value represents a string, number, boolean, or null according to its version and rules. Ambiguous values are safer when written explicitly as strings.
The tool validates its own schema Docker Compose, a CI system, or an OpenAPI validator checks supported keys, required fields, and other rules. Valid YAML with a typo in a key may not do what its author expects.
Values are passed securely The configuration references an environment variable or secrets manager; an actual production password, token, or private key does not belong in the repository.
The change is tested Validation, linting, and a safe run in the appropriate environment expose indentation mistakes and operational impact before production deployment.

Key concepts

Mappings, sequences, scalars, and the significance of indentation.

YAML’s readability rests on a simple structure. Complex use of anchors or automatic value interpretation quickly undermines it.

Mapping

A mapping assigns a value to a key, such as environment: production. A key can have a nested map whose scope is determined by spaces at the start of each line.

Sequence

A list of items starts with a hyphen. It can represent enabled features, pipeline steps, or named services, for example. Order may matter if the target tool interprets it that way.

Scalar value

A string, number, boolean, or null. To prevent a parser from converting an expected string to another type, use quotes for ambiguous values and check the rules of the selected parser.

Comments and multiple lines

A comment helps explain intent but should not replace documentation. YAML supports multiline text, which is suitable only when the target tool expects its exact form.

Anchors and aliases

Anchors can repeat part of a structure, but extensive use makes the resulting configuration harder to trace. Parser limits may also matter when handling untrusted input.

Benefits and limitations

A highly readable format that calls for restrained configuration.

Benefits

mappings and lists are easy to read during code review
comments can explain the operational intent of configuration
a single format is used by common infrastructure, CI/CD, and API documentation tools
configuration can remain versioned alongside source code and tests

Limitations and mistakes

indentation is part of the syntax, and one incorrect line can change the data tree
different parsers or versions may interpret values differently, especially ambiguous scalars
syntactic validity does not verify support for a specific key or deployment safety
unprotected secrets in YAML can easily end up in a repository, CI log, or commit history
complex anchors, aliases, and extensive nesting make configuration harder to read and diagnose

Practical use

Keep configuration small, validated, and separate from secret values.

In a project, YAML can name a service, environment, dependencies, and a list of enabled features. A connection password, however, does not belong in it as plain text. A reference to an environment variable or the deployment platform’s supported secrets mechanism is safer; the team then manages access to and rotation of secret values separately.

Untrusted YAML must not be deserialised into arbitrary objects. The choice of parser and its safe mode depends on the language, but the general rule is to accept only expected data types, set limits, and disable behaviour that creates executable objects from text or accesses external resources. Parsing is followed by validation against the specific tool’s schema.

What to consider

Simplify the notation, validate it with the tool, and handle secrets securely.

Good YAML configuration is short, unambiguous, and verifiable both during local development and in CI.

use consistent space-based indentation and check the file with the target tool’s formatter or validator
write ambiguous values as strings and verify how the selected implementation interprets their types
do not store production passwords, tokens, or private keys directly in version-controlled YAML
for input from another system, use a safe parser without automatic object construction and with resource limits
test configuration in a similar environment because a syntax error and an invalid configuration are different problems
replace complex anchors and aliases with clearly named shared configuration where doing so preserves the meaning

Common questions

YAML in practice

Is YAML a programming language?

No. YAML represents structured data. What a tool does with that data is determined by its own configuration and implementation.

Is YAML better than JSON?

Not in general. YAML is often more convenient for hand-written configuration and comments, while JSON has a simpler, stricter syntax and is common in APIs. The choice depends on the specific contract and tool.

Can I put a secret directly in YAML?

A production secret does not belong in a version-controlled file. Use an environment variable or a supported secrets mechanism, and restrict access to and logging of its value.

Is it enough for YAML to pass the parser?

No. The parser checks syntax. The target tool and application must validate supported keys, types, required values, and safe operational settings.

How I keep configuration operational

We version and validate configuration files, and keep them separate from secret values.

During development and deployment, I connect application configuration with tests, CI checks, and the secure transfer of values between environments.

How I approach testing and quality Discuss your project without obligation