Fix invalid YAML before converting to JSON

Indentation and tabs

Use spaces consistently. Tabs are not valid indentation in YAML and can look aligned while producing a parser error.

Child keys must be indented farther than their parent, and sibling keys must return to the same column.

Colons, list markers, and quoting

Mapping colons need a following space. Sequence markers also need a space before the item value. Quote strings containing ambiguous punctuation when the parser could treat them as syntax.

# valid
service:
  name: "catalog:api"
  ports:
    - 8080
    - 8443

A reliable debugging sequence

Start at the first reported error because later messages can be consequences of an earlier indentation problem. Reduce the document to the smallest failing block, then add surrounding sections back.

• Replace tabs with spaces.
• Compare indentation columns for siblings.
• Check unmatched quotes and flow brackets.
• Verify every document separator is on its own line.

A reliable step-by-step workflow

Treat invalid YAML as a data transformation with an explicit input, expected structure, and destination. Work on a copy, validate before changing representation, and isolate the smallest useful sample. This separates syntax failures from data-model or application failures.

Run one change at a time and repeat the same validation after each change. For automated pipelines, fail the job on a parser error instead of publishing a partial or guessed result. Keep the original input beside the generated artifact when traceability matters.

• Fix the first reported error before later ones; one missing quote can create many secondary messages.
• Reduce a large document to the smallest failing fragment while preserving the nesting around the error.
• After syntax succeeds, verify required keys, value types, ranges, and application-specific rules.

Worked example and verification

The compact sample below is intentionally small enough to inspect by eye. Use the same pattern with a real document: confirm every key, scalar type, list order, and nested boundary before accepting the output.

A successful conversion or minification only proves that the source could be parsed. Compare the parsed value before and after the operation, then load the result with the same library or platform that will consume it in production.

service:
  name: api
  retries: 3
  enabled: true

Limits and edge cases

The difficult cases in invalid YAML usually come from differences between syntax validity and application validity. A parser can accept data that is still incomplete, ambiguous, too large, or incompatible with a destination schema.

Never repair or normalize an unfamiliar document blindly. Duplicate keys, implicit types, aliases, precision limits, Unicode, line endings, and very large inputs deserve an explicit policy. When the destination has stricter rules, those rules win.

Production checklist

Before release, test a normal document, an empty value, deeply nested data, non-ASCII text, and a deliberately malformed example. Record the tool or library version if another system must reproduce the exact output.

Make validation part of continuous integration when the data affects builds, deployments, APIs, or configuration. Review diffs, keep a rollback copy, and monitor the first consumer after deployment rather than assuming a syntactically valid file is operationally correct.

• Fix the first reported error before later ones; one missing quote can create many secondary messages.
• Reduce a large document to the smallest failing fragment while preserving the nesting around the error.
• After syntax succeeds, verify required keys, value types, ranges, and application-specific rules.