Developer tools · Docker run to Docker compose converter
YAML gotchas in Compose files: quoting, the Norway problem and 22:22
· Background
docker compose yaml
Compose files are YAML, and YAML has opinions about bare values. This post explains the parsing rules behind the most common surprises and how to check any generated or hand-written YAML for them.
COUNTRY=NO became false — a Compose file passed a boolean where the app wanted a two-letter code
COUNTRY=NO became false — a Compose file passed a boolean where the app wanted a two-letter code. Evidence: a bare NO-like value can be retyped by parsers. Reproduce yaml scalar safety with disposable literals. Pair each source occurrence with quoted values maps sequences; reserve parser typing for destination review.
The yaml incident also reveals that A separate yaml incident boundary is that octal-looking hexadecimal numeric and date-shaped strings are quoted. Evidence: octal-looking hexadecimal numeric and date-shaped strings are quoted. This yaml scalar safety constraint is a stopping point. Inspect quoted values maps sequences without manufacturing behavior, then document a host check for parser typing.
YAML 1.1 scalars — how unquoted yes, no, on, off and NO become booleans in many parsers
YAML 1.1 scalars — how unquoted yes, no, on, off and NO become booleans in many parsers. Evidence: reserved yes no on off boolean and null spellings are quoted. Trace yaml scalar safety tokens into quoted values maps sequences. Separate ordered values from last-value fields; parser typing is outside collection.
A related yaml mechanism boundary is that A separate yaml grammar boundary is that maps use two spaces and arrays use dash items. Evidence: maps use two spaces and arrays use dash items. Use this yaml scalar safety fact to predict one member or scalar in quoted values maps sequences. Check warnings before deciding anything about parser typing.
Sexagesimal ports — why an unquoted 22:22 can parse as the integer 1342 and why the Compose docs say to quote ports
Sexagesimal ports — why an unquoted 22:22 can parse as the integer 1342 and why the Compose docs say to quote ports. Evidence: numeric colon port strings receive single quotes. Judge yaml scalar safety serialization from its model. Quoting in quoted values maps sequences protects types but gives no operational proof for parser typing.
The second yaml serialization observation is A separate yaml output boundary is that direct quoteYamlString examples reveal the writer decision. Evidence: direct quoteYamlString examples reveal the writer decision. This yaml scalar safety output separates settings from unavailable context. Keep quoted values maps sequences reviewable and check parser typing independently.
Leading zeros and octal — values like 0755 and version strings that YAML reinterprets
Leading zeros and octal — values like 0755 and version strings that YAML reinterprets. Stop at the yaml scalar safety exception instead of guessing. Any addition near quoted values maps sequences needs a deployment-specific reason tied to parser typing.
Another yaml exception constraint is that A separate yaml exception boundary is that anchors extensions and general YAML parsing are outside this serializer. Evidence: anchors extensions and general YAML parsing are outside this serializer. Keep the original yaml scalar safety command beside warnings. The comparison shows what quoted values maps sequences contains and which parser typing decision remains manual.
Indentation and lists — the two-space convention, list items under a key, and the map-versus-list forms of environment:
Indentation and lists — the two-space convention, list items under a key, and the map-versus-list forms of environment:. Build the yaml scalar safety example from synthetic names. Make every quoted values maps sequences item traceable without exposing production parser typing details.
The same yaml example sample demonstrates that A separate yaml example boundary is that defensive quoting protects the emitted subset only. Evidence: defensive quoting protects the emitted subset only. The paired yaml scalar safety fact should be visible in quoted values maps sequences. Record that line and avoid assumptions about parser typing.
Worked example: hand-fixing a broken file — running docker compose config to see what the parser actually produced
Worked example: hand-fixing a broken file — running docker compose config to see what the parser actually produced. Translate the yaml scalar safety consequence into one observable quoted values maps sequences difference. Docker owns the later parser typing verdict.
The yaml consequence implementation also shows A separate yaml effect boundary is that a bare NO-like value can be retyped by parsers. Split yaml scalar safety responsibilities: conversion writes quoted values maps sequences, the repository removes secrets, and operators validate parser typing.
What this does not cover — YAML anchors, extension fields (x-*), and the full YAML 1.2 specification
What this does not cover — YAML anchors, extension fields (x-*), and the full YAML 1.2 specification. Limit yaml scalar safety scope to quoted values maps sequences branches shown here. Neighboring forms and defaults cannot answer parser typing questions.
One more yaml scope limit follows from A separate yaml limit boundary is that reserved yes no on off boolean and null spellings are quoted. Treat this yaml scalar safety boundary as an exclusion. Prefer accurate quoted values maps sequences over guesses about parser typing.
Takeaway: quote anything that is not obviously a string — and compare hand-written YAML against the converter's output to catch bare values
Takeaway: quote anything that is not obviously a string — and compare hand-written YAML against the converter's output to catch bare values. Audit yaml scalar safety as source option, model field, quoted values maps sequences line and warning. Remove secrets before checking parser typing.
Finally, the yaml takeaway source confirms A separate yaml decision boundary is that numeric colon port strings receive single quotes. Close yaml scalar safety narrowly: quoted values maps sequences is a candidate; parser typing and shell equivalence are not guarantees.