Formatador YAML

YAML Formatter: Consistent Indentation and Readable Structure

YAML (YAML Ain't Markup Language) relies on whitespace indentation to define document structure, making formatting far more than a cosmetic concern — incorrect indentation changes the meaning of a YAML document entirely. A misaligned key can shift a property from one mapping to another, a stray tab character can break parsing altogether, and inconsistent spacing makes configuration files difficult to review in pull requests. This tool reformats YAML documents with consistent indentation, proper alignment of nested structures, and clean separation between block elements, producing output that is both machine-parseable and easy for humans to scan and modify.

YAML Indentation Rules and Their Structural Significance

Unlike JSON or XML where braces and tags define hierarchy, YAML uses indentation as its sole mechanism for expressing nesting depth. The YAML 1.2.2 specification mandates that indentation consists of one or more spaces — tab characters are explicitly forbidden in indentation context. Each child node must be indented further than its parent, and sibling nodes at the same level must share identical indentation:

• Spaces only: YAML forbids tabs for indentation. Mixing tabs and spaces produces a parsing error in all compliant parsers. Most editors should be configured to insert spaces when Tab is pressed.
• Consistent indent width: While the spec allows any number of spaces per level (1, 2, 3, 4, etc.), the chosen width must remain consistent within a given nesting context. The community convention is 2 spaces per level for configuration files (Kubernetes, Docker Compose, GitHub Actions).
• Relative indentation: What matters is the difference between a parent and its children, not absolute column position. A child must be indented at least one space more than its parent mapping key.
• Sequence indicators: The dash (-) in block sequences counts as indentation. An item like - name: app places name at dash-indent + 2 columns relative to the sequence start.
• Multiline values: Block scalars (| and >) require their content to be indented at least one space beyond the indicator line.

A YAML formatter enforces these rules automatically: it normalizes indent width across the entire document, removes tab characters, aligns sibling nodes to the same column, and corrects the indentation of block scalar content — preventing structural errors that would cause parsing failures in tools like kubectl, docker compose, or ansible-playbook.

Block Style vs Flow Style: When to Use Each

YAML supports two representation styles for collections (mappings and sequences): block style and flow style. Each has distinct readability characteristics, and a good formatter knows when to preserve or convert between them:

• Block style uses indentation to denote structure. Mappings use key: value on separate lines, and sequences use - item notation. This is the default for configuration files because it maximizes readability for deeply nested structures.
• Flow style uses JSON-like inline syntax: {key: value} for mappings and [item1, item2] for sequences. Flow style is appropriate for short, simple collections that fit on a single line.

Best practices for choosing between styles:

• Use block style for mappings with more than 2 keys or values longer than 40 characters.
• Use flow style for short label sets like {app: web, tier: frontend} where the entire mapping fits within 80 columns.
• Use block sequences when items are complex (nested mappings) or contain long strings.
• Use flow sequences for simple lists of scalar values: [80, 443, 8080].
• Never nest flow style deeper than one level — {a: {b: {c: d}}} defeats readability.

A formatter typically converts deeply nested flow-style collections into block style for clarity while preserving short flow-style expressions that are already readable. This produces output that balances compactness with the vertical structure developers expect in configuration files.

Formatting Best Practices for Readability

Beyond basic indentation correctness, well-formatted YAML follows conventions that improve readability across teams and tooling:

• 2-space indent: The overwhelming community standard. Kubernetes, Helm, GitHub Actions, Docker Compose, and Ansible all use 2-space indentation in their documentation and examples.
• No trailing whitespace: Trailing spaces are invisible yet can cause diff noise in version control. A formatter strips them automatically.
• Consistent quoting: Avoid unnecessary quotes around scalar values. Quote only when required — strings starting with special characters (*, &, {, [, #), strings that look like booleans (yes, no, true, false), or strings containing colons followed by spaces.
• Blank lines between top-level blocks: Separate top-level mappings or document sections with a blank line to create visual grouping.
• Key ordering: For Kubernetes manifests, place apiVersion, kind, and metadata before spec. Consistent key ordering reduces cognitive load during reviews.
• Line length: Keep lines under 120 characters. Long strings should use block scalars (| or >) rather than wrapping in flow style.

Applying these conventions consistently across a project ensures that YAML diffs in pull requests show only meaningful changes, not formatting noise — making code review faster and reducing merge conflicts caused by inconsistent editor settings across team members.

Common Formatting Issues and How Proper Formatting Prevents Them

Many YAML-related production incidents trace back to formatting problems that are invisible to casual inspection but fatal to parsers:

• Tab contamination: A single tab character mixed with spaces breaks the entire document. Formatters convert all indentation to spaces unconditionally.
• Incorrect nesting level: A key indented one space too few moves it to a parent mapping, changing the document structure silently. Formatters normalize levels to consistent multiples.
• Unquoted special values: Writing version: 1.0 parses as float 1 (trailing zero dropped), not string "1.0". Writing country: NO parses as boolean false. Formatters can flag or quote these ambiguous values.
• Trailing whitespace in multiline: Block scalars with trailing spaces on content lines may produce unexpected results when the YAML is consumed by templating engines.
• Inconsistent sequence indentation: Some files indent the dash, others don't. This works but produces confusing diffs. A formatter normalizes to a single convention.
• Missing document separators: Multi-document YAML streams require --- between documents. Formatters ensure proper separation exists.

Running YAML through a formatter before committing acts as a safety net — catching these issues before they reach CI pipelines, deployment scripts, or production infrastructure where a parsing failure could cause service disruption.

Code Examples

Before and After: Formatting a Kubernetes Service Definition

# Before formatting (inconsistent indentation, mixed styles)
apiVersion: v1
kind: Service
metadata:
    name: web-service
    labels: {app: web, tier: frontend}
spec:
  type: ClusterIP
  ports:
      - port: 80
        targetPort: 8080
        protocol: TCP
  selector:
      app: web

# After formatting (consistent 2-space indent, clean structure)
apiVersion: v1
kind: Service
metadata:
  name: web-service
  labels:
    app: web
    tier: frontend
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: 8080
      protocol: TCP
  selector:
    app: web

Standards & Specifications

• YAML 1.2.2 Specification — The current YAML specification defining indentation rules, block/flow styles, and scalar formatting conventions used by this formatter