SyntaxDock guide

How to Validate YAML Syntax: Common Errors and Fixes

Learn how to validate YAML syntax, fix indentation and quoting errors, and distinguish parsing from schema checks with practical examples.

Check YAML syntax before checking configuration

Use the YAML Validator to parse YAML locally in your browser. Paste a document, select Validate YAML, and follow any diagnostic to its source line and column. A successful check means the input parses; it does not establish whether an application understands the settings.

Start with mappings, sequences and values

A mapping associates keys with values using a colon followed by a space. A sequence uses a dash followed by a space for each item. Indentation places the items inside their parent. This example is valid YAML:

name: sample
enabled: true
items:
  - first
  - second

Spaces define nesting. Two spaces per level is a useful convention, not a universal YAML requirement. Keep sibling entries aligned and indent children further than their parent.

Fix indentation and whitespace mistakes

The following example is invalid because image does not align with a valid level in this mapping:

settings:
  web:
 image: sample

Indent the value under web to express the intended structure:

settings:
  web:
    image: sample

Use spaces for indentation, not tabs. Tabs are not forbidden everywhere in YAML, but they cannot supply indentation. Also inspect valid-looking files for accidental nesting: some indentation changes produce valid YAML with the wrong meaning. The parser cannot infer your intended configuration.

Choose quoted and unquoted scalars deliberately

Unquoted values may resolve to numbers, booleans or null. Quoting a value can preserve it as text. Both 42 and "42" parse, but they have different types. Quote text containing a colon followed by a space or a space followed by a hash when those characters should be literal:

count: 42
text_count: "42"
label: "status: ready # literal"
markup: "<example> & text"

Double-quoted strings support YAML escape sequences; single-quoted strings represent a literal single quote by doubling it. Shell and JSON escaping rules are not interchangeable with YAML quoting.

Write multiline strings with block scalars

The literal style | retains line breaks. The folded style > folds ordinary adjacent text lines into spaces; blank lines and more-indented lines have additional rules. In these simple examples, the - chomping indicator removes the final line break:

literal: |-
  first
  second
folded: >-
  first
  second

The literal value is first\nsecond, where \n denotes a newline. The folded value is first second. Indent block content consistently beneath its key. See the YAML specification for folding and chomping details.

Correct duplicate keys and unfinished sequences

SyntaxDock rejects duplicate mapping keys. This input produces a duplicate-key error on the second entry:

service: web
service: worker

If both values belong together, use a sequence instead of repeating the key:

services:
  - web
  - worker

An unfinished flow sequence is also invalid:

items: [first, second

Close the bracket to make it valid:

items: [first, second]

Fix the first reported error and validate again; later diagnostics can be consequences of an earlier mistake. Empty or whitespace-only input prompts you to enter YAML.

Understand streams, anchors and aliases

The validator accepts multiple YAML documents separated by ---. Anchors name nodes and aliases reuse them within the same document. This valid stream contains two documents; the first reuses its defaults:

defaults: &base
  enabled: true
copy: *base
---
name: second

Select Format YAML for valid input to produce two-space indentation while preserving comments, document boundaries, anchors, aliases and multiline values. Formatting cannot repair a parse error or decide whether the settings are useful.

Separate parsing, schemas and application behavior

SyntaxDock uses a strict parser configured with YAML 1.2 as its default and duplicate-key checks. It reports parser errors and warnings; it does not check arbitrary application fields or validate against a schema you supply. For example, this is valid YAML but fails the Docker Compose schema because services must be a mapping:

services: invalid

Schema validation checks allowed fields, required fields and value types for a particular configuration format. Application validation can additionally depend on resolved variables, referenced files and the actual environment. Neither successful parsing nor schema acceptance proves runtime behavior.

SyntaxDock's YAML Validator does not load referenced files or contact services. Validation and formatting process your input in your browser without uploading or storing the document. Use the YAML Validator to check syntax, then choose the appropriate configuration workflow: