YAML Formatter & Validator
The example is valid YAML: a mapping with 19 keys nested 3 levels deep, in 1 document. Formatted with 2 spaces it goes from 23 to 23 lines and all 2 comments stay; as JSON it is 34 lines. Paste your own YAML and it is checked as you type: valid text is re-indented with 2 or 4 spaces (keys sorted A to Z if you like) or converted to JSON, and a mistake shows its line and column with a caret under the spot. Comments on their own line or at the end of a line are kept; comments inside a multi-line [ ] or { } cannot be, and the page tells you when that happens.
Updated Runs in your browser: nothing you enter is uploadedHow this tool works
Replace the example: paste or type YAML. It is checked as you type, and comments are kept (see the notes under the result).
Your YAML is processed on this device and never uploaded. It is not saved either: reload the page and it is gone.
Result
Valid YAML: a mapping
19 keys, 3 levels deep, 1 document
- 2 comments kept. A comment on its own line stays with the entry below it; a comment at the end of a line stays with its entry.
Size and structure
- Before (UTF-8)
- 396 bytes
- After (UTF-8)
- 377 bytes
- Change
- −19 bytes (−4.8%)
- Documents
- 1
- Keys
- 19
- Depth
- 3
- Comments kept
- 2
What each option does to the same file
| Option | Result | Effect |
|---|---|---|
| 2 spaces (default) | b: [2, 1] ⏎ a: ⏎ - x # note ⏎ - y | One nesting level per two spaces; a list sits under its key; spacing and comment gaps are made single. |
| 4 spaces | b: [2, 1] ⏎ a: ⏎ - x # note ⏎ - y | One nesting level per four spaces. A list entry’s own content stays two columns past its dash. |
| Sort keys A to Z | a: ⏎ - x # note ⏎ - y ⏎ b: [2, 1] | Every mapping’s keys sorted by Unicode code unit order; comments move with their entry; list order is never changed. |
| Convert to JSON | {"b":[2,1],"a":["x","y"]} | The same data as JSON; comments are not part of JSON, so they are dropped and counted in a note. |
YAML formatter worked examples
| Case | YAML | Result |
|---|---|---|
| Anchor and merge key to JSON | base: &b {retries: 3, timeout: 30} ⏎ prod: ⏎ <<: *b ⏎ timeout: 60 | {"base":{"retries":3,"timeout":30},"prod":{"timeout":60,"retries":3}} |
| Literal block (|) keeps its line breaks | motd: | ⏎ Hello ⏎ there | {"motd":"Hello\nthere\n"} |
| Folded block (>-) joins lines with spaces | about: >- ⏎ a long ⏎ sentence | {"about":"a long sentence"} |
| Several documents become a JSON array | a: 1 ⏎ --- ⏎ b: 2 | [{"a":1},{"b":2}] |
| Comments survive re-indenting | server: ⏎ port: 80 # http ⏎ # tls next ⏎ tls: false | server: ⏎ port: 80 # http ⏎ # tls next ⏎ tls: false |
| Flow style is tidied, not expanded | ports: [ 80,443 ,8080 ] ⏎ labels: {a: 1,b: 2} | ports: [80, 443, 8080] ⏎ labels: { a: 1, b: 2 } |
| A list under a key is indented | steps: ⏎ - run: build ⏎ - run: test | steps: ⏎ - run: build ⏎ - run: test |
| Keys sorted, nested ones too | z: 1 ⏎ m: ⏎ y: 1 ⏎ x: 2 ⏎ a: 3 | a: 3 ⏎ m: ⏎ x: 2 ⏎ y: 1 ⏎ z: 1 |
Common YAML errors and the message you get
| YAML | Message | Position | Fix |
|---|---|---|---|
| a: 1 ⏎ b: 2 | Tabs cannot be used for indentation in YAML. Use spaces. | line 2, column 1 | Replace the tab with spaces: YAML does not allow tabs in indentation. |
| a: 1 ⏎ a: 2 | Duplicate key “a”. Keys in a mapping must be unique. | line 2, column 1 | Delete or rename one of the repeated keys. |
| a: ⏎ b: 1 ⏎ c: 2 | Bad indentation: this line has 1 space, but the keys above it have 0. A value cannot continue on the next line unless it is in quotes or a | or > block. | line 3, column 2 | Indent c to match b, or outdent it to match a. |
| url: http://x.io ⏎ note: a: b | A “key: value” pair is not allowed here. If the colon is part of the text, put the whole value in quotes. | line 2, column 8 | Quote the value: note: "a: b". |
| a: [1, 2 | The [ starting here is never closed. | line 1, column 4 | Close the bracket: [1, 2]. |
| a: "unclosed | The quoted text starting here is never closed. | line 1, column 4 | Close the quote, or use single quotes if the text contains a double quote. |
| a: *base | Unknown alias *base: no anchor &base is defined above it. An anchor must come before its aliases. | line 1, column 4 | Add the anchor (&base) on an earlier value, or write the value out. |
| a: 1 ⏎ - b | Unexpected content after the end of the value (“-”). | line 2, column 1 | A list and a mapping cannot share one level: indent the list under a key. |
How a plain value becomes JSON
| You write | JSON | Why |
|---|---|---|
| true | true | A boolean under the core schema (True and TRUE work too). |
| yes | "yes" | Text. YAML 1.1 readers make it true; YAML 1.2 does not. |
| null | null | Null (so are Null, NULL, ~ and an empty value). |
| 007 | 7 | The integer 7 in YAML 1.2; octal in YAML 1.1. |
| 0x1F | 31 | A hexadecimal integer, written as decimal in JSON. |
| 0o17 | 15 | An octal integer, written as decimal in JSON. |
| 1e3 | 1e3 | A float: JSON keeps the exponent form. |
| 12345678901234567890 | 12345678901234567890 | An integer beyond 2^53: every digit is kept. |
| 2024-01-15 | "2024-01-15" | Text: the core schema has no date type. |
| 1_000 | "1_000" | Text in YAML 1.2 (YAML 1.1 allows underscores in numbers). |
| "12" | "12" | Quoted, so text. |
The YAML this tool reads
| Feature | Supported | Notes |
|---|---|---|
| Block mappings and lists | Yes | Including a list at the same indent as its key, `- key: value` entries and `- - nested` lists. |
| Scalars | Yes | Plain (also continued over several lines), single-quoted and double-quoted with all YAML escapes. |
| Block scalars | Yes | | and > with chomping (-, +) and indentation (1 to 9) indicators; their lines are kept as written. |
| Flow style | Yes | [a, b] and {a: b}, nested and over several lines; written back on one line. |
| Anchors and aliases | Yes | Kept in YAML output; replaced by copies in JSON. An unknown alias is an error at its position. |
| Merge keys (<<) | Yes | Applied in the JSON (YAML 1.1 merge type); kept as written in YAML output. |
| Tags | Yes | Kept as written in YAML output (!Ref, !!str). In JSON, !!str, !!int, !!float, !!bool and !!null set the type and other tags are dropped. |
| Several documents | Yes | --- and ... markers, % directive lines; the JSON is an array when there is more than one. |
| Comments | Mostly | Own-line and end-of-line comments are kept. Comments inside a multi-line [ ] or { } are dropped, and the page says so. |
| Complex keys (? ) | No | Reported as an error at its position. So are an alias used as a key and a key: value pair directly inside [ ]. |
| Tabs for indentation | No | YAML forbids them; the error names the line and column of the tab. |
| Limits | n/a | Up to 2,000,000 characters, 200 levels of nesting, and 2,000,000 values after aliases are expanded into JSON. |
How to format and validate YAML online
- Paste your YAML. Replace the example with your own text. It is checked as you type; for very large input, press Format instead.
- Read the verdict. A valid file shows its type, key count, depth and document count. An invalid one shows the message, the line and column, and the offending line with a caret.
- Choose the layout. Pick 2 or 4 spaces and turn on “Sort keys” to order every mapping A to Z. Lists keep their order.
- Check the notes. The notes list what the result does not keep (comments inside brackets), and flag values such as yes or 0755 that older YAML readers treat differently.
- Copy, download or convert. Copy the result or download it. Switch “Output” to JSON to get the same data as JSON instead.
Frequently asked questions
- How do I validate YAML?
- Paste it into the box. The text is read against the YAML 1.2 grammar for the subset listed on this page, and the first problem is reported with its line, column and a caret under the character. Only the first error is shown, because one slip often causes several confusing follow-ups; fix it and the next one, if any, appears. A file that reads without error is valid for this tool, but a program may still reject it for its own reasons, such as a missing required key.
- Why does YAML reject tabs?
- The YAML specification forbids tab characters in indentation, because a tab has no fixed width and two people could read the same file differently. A tab is fine inside a line, such as between a key and its value, or inside a quoted string. The error points at the exact tab, so replace it (and the tabs on neighbouring lines) with spaces; most editors can convert them.
- Does the formatter keep my comments?
- Yes, with one exception. A comment on its own line stays above the entry that follows it and is re-indented with it, and a comment at the end of a line stays on that line, separated by one space. Blank lines between entries are kept, but never more than one in a row. A comment inside a [ ] or { } that spans several lines cannot be placed in the rewritten bracket, so it is dropped, and a note says how many. Converting to JSON drops all comments, because JSON has none.
- Which parts of YAML does it understand?
- Mappings, lists, plain, single-quoted and double-quoted scalars, | and > block scalars, flow style, anchors, aliases, merge keys, tags, comments and multiple documents. It does not read complex keys (a line starting with “? ”), an alias used as a key, or a key: value pair written directly inside [ ]; each gives an error with a position rather than a wrong result. The table above lists every feature.
- What happens to anchors and aliases?
- Formatting keeps them exactly: &name stays on its value and *name where it was used. Converting to JSON replaces each alias with a copy of the anchored value, and applies <<: *name merge keys so that keys written next to the merge win. An alias that names an anchor defined later, or never, is an error, because an anchor must come first. Sorting keys is skipped, with a note, if it would move an alias above its anchor.
- Does sorting keys change the meaning?
- Not for ordinary data: a mapping has no order. Every mapping, at every depth, is sorted by the code units of its keys (so uppercase letters come before lowercase ones), and its comments move with it. Lists are never reordered, because their order is part of the data. If a program reads the file in order, such as a pipeline whose steps are keys, leave sorting off.
- Why did yes, no or on become text in the JSON?
- This tool follows YAML 1.2, where only true and false are booleans, so yes, no, on and off stay text. YAML 1.1 readers, still common in older tools, treat them as booleans, which is why a country code such as no (Norway) or a key named on can surprise you. A leading-zero number such as 0755 is decimal 755 in YAML 1.2 and octal in 1.1. The page adds a note whenever it sees one, and quoting the value removes the doubt.
- How do I convert YAML to JSON?
- Set Output to JSON. Mappings become objects, lists become arrays, and plain values are typed with the YAML 1.2 core schema (see the table above). Numbers keep every digit, so 12345678901234567890 is not rounded. A file with several documents becomes an array with one item per document. Values that JSON cannot hold, such as .inf and .nan, are reported as errors rather than silently changed.
- Should I indent with 2 or 4 spaces?
- YAML only requires that every level use more spaces than its parent and that siblings line up; the width is a matter of convention. Two spaces is a very common convention in configuration files and keeps deeply nested files narrow; four spaces can read more clearly in shallow files. The formatter applies whichever you choose to the whole document, and a list entry’s own content always sits two columns past its dash.
- Where does the checking happen?
- In the page itself, as JavaScript running on your device, so there is no upload step to wait for and the text is not saved when you leave. It also works for private configuration, although you should still keep secrets out of anything you paste anywhere. Analytics, if you allow them, only count that a button was used.
How it works
The text is read by a recursive-descent reader written for this tool, following the structure rules of YAML 1.2.2: block mappings and lists are told apart by indentation, scalars by their first character, and flow collections by their brackets. Instead of a plain value it builds a tree that keeps comments, anchors, aliases, tags and the exact text of quoted scalars, so the formatter changes layout (indentation, spacing, blank lines, key order if asked) and never rewrites a scalar; only a scalar that spans several lines is joined onto one line. Plain scalars are typed only when converting to JSON, using the core schema: null, true and false in their three spellings, decimal, 0o octal and 0x hexadecimal integers, floats, and everything else as text. Numbers are rewritten as text, never through a double. Merge keys follow the YAML 1.1 merge type, since YAML 1.2 does not define them. Positions are 1-based, counted in Unicode characters, with LF, CRLF and a lone CR each ending a line. Safety limits: 2,000,000 characters, 200 nesting levels, and 2,000,000 values after expanding aliases for JSON. Automatic formatting stops above 200,000 characters and waits for the Format button. The example formats to 23 lines with 2 spaces and 23 with 4, because only the width of the indentation changes, not the number of lines.
Sources
- YAML Ain’t Markup Language (YAML) revision 1.2.2
- YAML 1.2.2, section 10.3: Core Schema
- YAML 1.2.2, section 8.1: Block Scalar Styles
- YAML 1.2.2, section 6.1: Indentation Spaces (tabs are not indentation)
- YAML 1.2.2, section 6.9: Node Properties (anchors and tags)
- Language-Independent Types for YAML 1.1: Merge Key (<<)
- RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
More free tools
- JSON DiffCompare two JSON documents by structure, not text: added, removed and changed values by JSON Pointer path, plus an RFC 6902 JSON Patch you can copy.
- CSV to JSON ConverterConvert CSV to JSON in your browser: quoted fields, line breaks, any delimiter, and the exact line and column of an error. Converts JSON to CSV too.
- JSON to YAML ConverterConvert JSON to YAML or YAML to JSON in your browser. Quotes strings YAML would misread, writes | blocks, and shows the line and column of any error.
- JSON Formatter & ValidatorValidate JSON with the exact line and column of any error, then pretty-print, minify or sort keys. Big numbers keep every digit. Runs in your browser.
- Markdown Table GeneratorBuild a GitHub Markdown table from an editable grid or pasted CSV, TSV or spreadsheet cells. Set column alignment, pad columns, and parse a table back.
- JSON to CSV ConverterConvert JSON, an object of arrays or JSON Lines to CSV or TSV in your browser. Flattens nested keys to address.city, quotes per RFC 4180, guards formulas.
More: Formatters and data convertersAll developer toolsAll toolsHome & DIY calculators