Debug a YAML indentation mistake by converting it to JSON

The step that never ran — a workflow file that parsed fine and a key that ended up one level too high

A workflow can parse successfully while placing `with` beside a step rather than inside it. The runner then ignores or rejects the shape later, and visual inspection misses the shift because the source remains tidy. Converting to JSON exposes the actual parent through braces and array boundaries.

ToolAcre reports malformed YAML with line and column, but valid wrong structure produces no syntax error. The converted tree is therefore a diagnostic view: it tells you what this parser accepted, not what the workflow schema intended.

Why indentation mistakes are often not errors — YAML's structure is whitespace, so a shifted line usually creates a valid but different document

Whitespace carries YAML hierarchy. Moving a line left can turn a child into a sibling; moving a dash can place an item in another sequence. Both documents may satisfy the YAML grammar. Syntax validation cannot decide which nesting matches the application.

Tabs in indentation are rejected by the parser and receive a position. Spaces that produce the wrong valid hierarchy require structural comparison instead. That difference explains why some indentation mistakes fail immediately while others survive until application behaviour.

What JSON makes explicit — braces and brackets that show precisely which object a key belongs to

JSON writes object boundaries with braces and array members with brackets. A misplaced YAML key appears outside the object where you expected it, and a dash becomes an array boundary that is difficult to overlook. Indentation in pretty JSON is presentation; punctuation defines the structure.

The view also reveals resolved types. An unquoted scalar may be null, number or Boolean under the selected schema. Fixing hierarchy without checking values can leave a second bug, so compare both property path and JSON type.

Common shapes of the mistake — a list item under the wrong parent, a key that became a sibling instead of a child, and tabs mixed with spaces

Common mistakes include a sequence item aligned with the wrong list, a mapping key outdented into a sibling, and tab characters mixed with spaces. Duplicate keys are another trap: ToolAcre keeps the last value and warns with a position, so the JSON contains only the surviving property.

Anchors can make the result look larger because aliases expand into repeated data. That is expected for this conversion and should not be confused with accidental indentation. Read warnings before attributing every structural difference to whitespace.

Worked example: a CI workflow with one mis-indented 'with' block — converting to JSON, spotting the misplaced key, fixing and reconverting

Create a redacted job with `steps`, one `uses` entry and a `with` mapping. Outdent `with` so it becomes a sibling of `steps`, then convert. The JSON braces show that `with` belongs to the job rather than the step object. Move it under the list item and reconvert to see the intended nesting.

This example avoids claiming how a specific CI service responds, because the converter does not load that schema. The proof is the parsed hierarchy. Schema validation should follow and can then report whether `with` is accepted at the corrected path.

Using the reverse conversion — JSON to YAML to produce a correctly indented version you can paste back

Once the JSON structure is correct, converting it back to YAML produces consistent indentation from the serializer. Ambiguous strings may gain quotes, and comments are not restored. Treat the output as a clean data serialization, not a source-preserving formatter.

If the original comments explain operational choices, copy the corrected structure into the maintained file rather than replacing it blindly. A generated file can be structurally right and editorially incomplete.

What this does not cover — semantic validation against the workflow or manifest schema, which catches unknown keys rather than misplaced ones

No workflow, Compose, Kubernetes or application schema is involved. A key can sit under the intended parent and still be misspelled or unsupported. Syntax converters proves only that the YAML is accepted and shows the resulting JSON-shaped value.

Use the owning platform’s validator for unknown keys, required fields and semantic constraints. Keeping syntax and schema checks separate produces clearer failures and avoids crediting a generic converter with domain knowledge it does not have.

Takeaway: when YAML looks right and behaves wrong, look at it as JSON — and how the Syntax converters panel does that instantly

When YAML looks right but behaves wrong, inspect the parsed tree. JSON braces and brackets make parentage explicit, while ToolAcre’s warnings expose duplicates, streams and value changes that can complicate the picture.

Fix one hierarchy error, reconvert and then run schema validation. This sequence turns an invisible whitespace suspicion into observable structure without claiming that a successful conversion makes the configuration valid for its destination.

When comparing before and after, focus on property paths rather than line numbers because serialization can reorder presentation or add quotes. A useful review lists the expected path, its JSON type and whether it sits inside an object or array. That small checklist catches a second misplaced key even when the first visual symptom is fixed, and it avoids turning the generated YAML formatting into the test oracle.