YAML Formatting Guide
YAML is popular because it is readable, but that readability depends on indentation discipline. A single misplaced space can change whether a value belongs to a service, a list item or the root configuration.
Indentation Is The Structure
Unlike JSON, YAML does not use braces to show every object boundary. Spaces carry structural meaning. Teams should agree on a simple convention such as two spaces per level and avoid tabs entirely. This makes diffs easier to review and reduces accidental configuration drift.
services:
api:
image: formalint/api
ports:
- "8080:8080"Lists And Maps
Most YAML mistakes happen where lists and maps meet. If a list item owns several fields, keep those fields aligned under the item. If the next list item starts, return to the dash indentation. A formatter can make this easier to scan, but the reviewer still needs to understand the intended shape.
Comments And Configuration Review
Useful comments explain why a setting exists, not what the key already says. Before committing YAML, remove outdated comments, check duplicated keys and confirm that environment-specific values are not accidentally copied from production.
Never paste live deployment secrets, tokens, private registry passwords or customer environment values into a public tool.
Use Formalint
Use the Formalint YAML Formatter to clean spacing and run common structure checks. For adjacent work, try the JSON guide or the tools directory.