Data and structured data
Check YAML that fails to load
Tools to use
After copying a configuration and adding a few lines, one service ignores a setting. Replacing tabs removes the error, but the behavior is still wrong. YAML problems are not limited to invalid syntax: valid text can describe a different hierarchy from the one you intended.
We will inspect fictional server and worker settings without applying them to a service. Use YAML formatting and validation for syntax, and JSON–YAML conversion when you want to inspect structure or types. The aim is to explain each field's parent, not to overwrite production configuration merely because formatting succeeded.
Reduce the example before repairing it
For an error in hundreds of lines, make your own working copy and isolate the affected parent and its children. Copying only a child can change the indentation context and hide the original problem. Keep its parent, make whitespace visible in your editor, and distinguish tabs from spaces. This makes cause and repair easier to verify than a global replacement.
Two spaces can change which setting you changed
server:
host: example.invalid
timeout: 30
worker:
enabled: true
server:
host: example.invalid
timeout: 30
worker:
enabled: true
Run each example separately through YAML formatting and validation. Both parse, but their structures differ. A puts timeout inside server; B puts it alongside server. After checking for errors, inspect which parent owns timeout. Leading whitespace is not merely decoration.
If the distinction is hard to see, convert both examples with JSON–YAML conversion and inspect the braces. A has server.timeout; B has timeout at the root. Conversion is an inspection aid, not a requirement to migrate the configuration to JSON. Consult the receiving service's specification to determine which location is correct.
A dash can start a new list item
services:
- name: api
port: 8080
- name: worker
port: 8081
There are two dashes and two list items. Each port belongs to the same item as the preceding name. Adding a dash before port can create a separate item containing only a port, producing four items that look superficially similar. Check both the item count and the grouping of each name with its port.
A formatter cannot know whether you intended two items or four; it formats the structure it can read. When moving a copied configuration into another level, identify all its children rather than moving one line in isolation. Recording the expected item count before comparing the formatted result helps expose accidental regrouping.
false and "false" are different values
enabled: false
label: "false"
count: 3
code: "003"
note: null
empty: ""
Convert this to JSON: enabled is boolean, label is a string, count is numeric, and code is a string retaining its leading zeros. note is null while empty is an empty string. Similar displays do not imply the consuming program treats them alike. Leading zeros lost by interpreting an identifier as a number cannot reliably be recovered by later formatting.
Quoting every value is not a solution: turning true or 30 into strings may violate the receiver's expected types. Use quotes to express an intended string, not to hide an error. YAML versions and readers can differ, so successful parsing in another tool does not replace validation by the actual receiver.
Does the second occurrence of a key win?
timeout: 30
timeout: 60
SheepDev rejects this as a duplicate key. Decide which value you intended instead of assuming the last one wins. Layering separate configuration files is different from repeating the same key in one mapping. Do not transfer a framework's file-merging rules to a duplicate inside a single document.
By contrast, server.timeout and worker.timeout are different fields because their parents differ. Finding the word timeout twice is not a reason to delete one occurrence. Inspect the hierarchy before repairing duplicates. A generic duplicate-line remover does not understand that hierarchy and may remove necessary settings.
Why two lines can become one
literal: |
first line
second line
folded: >
first line
second line
Converted to JSON, literal retains the interior newline while folded joins these two lines with a space. Both examples retain a final newline. Two values written over two lines need not decode to the same string. This matters for notifications, signed messages, and text passed to commands.
This experiment uses two ordinary lines at the same indentation. Do not generalize it into '> always makes everything one line' for text with blank lines or extra indentation. Isolate a representative excerpt and inspect its decoded newlines. Check the resulting message, not only the appearance of the formatted source.
Check where comments end and values begin
color: "#4F46E5"
message: "status: ready"
retries: 3 # calculation example
Quote text when symbols such as a color's # or a colon in a sentence should be literal content rather than syntax. The comment following retries is not part of the number 3. When copying from an article, distinguish actual input from annotations. Removing symbols just because they look suspicious can damage the color or message itself.
Comments do not become ordinary data when converted to JSON. Formatting YAML and converting it to another format preserve different information. If comments explain operational decisions, the converted result is not a replacement for the maintained source. Distinguish an inspection copy from the team's authoritative configuration.
From parseable configuration to intended configuration
Finally, check the application's field names, types, and required settings. YAML syntax cannot decide whether timeout means seconds or milliseconds or which ports the service accepts. SheepDev neither applies the configuration to a service nor performs its application-specific startup checks. A receiving application's validation command or safe test environment is the next step when available.
When explaining a repair, 'fixed indentation' may be too vague. 'Moved timeout from the root back under server and kept 30 unchanged' communicates both structure and value. Review three stages: does it parse, is the hierarchy intended, and does it satisfy the application's meaning? That turns an exercise in chasing whitespace into a focused configuration review.