Step-by-Step Learning Path
A guided order through the specification, the language guides, the tools and the tutorials. Start at step 1, or jump to the path that matches your job.
How to use this page: The steps are ordered from "what is this" to "I can ship it". If you only need one answer, use the role-based paths further down. Everything on this site was checked against the json-6 package, version 1.1.7.
The Seven Steps
JSON6 is a small format with a small ecosystem. The reference implementation is the json-6 package by d3x0r, and that package is the main thing to learn. These seven steps take you from the idea to a working use in your own project. Each step lists the pages to read, in order.
Step 1Understand what JSON6 is
JSON6 extends JSON with the syntax people want when they write data by hand, and adds no new data types. It is not an official successor to JSON, and it has its own file extension, .json6. Start with the reasons and the comparison.
- Why JSON6 - what problem it solves and when not to use it
- Compare formats - JSON, JSON5, JSON6, YAML and others side by side
- JSON6 vs JSON5 - exactly which features JSON6 adds
Step 2Learn the syntax
The specification pages are short and each one has runnable examples. Read them in this order; strings and numbers hold most of the JSON6 additions.
- Specification overview - the map of the grammar
- Syntax - comments, whitespace, keywords,
undefined - Strings - quote styles, multi-line strings, escapes
- Numbers - hex, binary, octal, separators, leading zeros
- Objects and arrays - unquoted keys, trailing commas, empty members
Step 3Keep a reference nearby
A one-page summary and a set of copyable samples save a lot of lookups while you write your first files.
- Cheat sheet - every feature on one page
- Examples - complete documents for common cases
Step 4Try it without installing anything
The browser tools run the real parser, so you can paste a file and see what it becomes. Use them to test every syntax feature from step 2.
- Validator - check a document and see the error position
- Converter - JSON to JSON6 and back
- Formatter - normalize indentation
- Minifier - compact output
- Getting started tutorial - your first file, step by step
Step 5Use it in code
The language guides document the package API and the quirks of each environment: the global-name issue in the browser build, the executable name, the ESM default export and the plain Error type.
- JavaScript - the full API: parse, stringify, options, errors
- Node.js - require hook, ESM register, CLI, config loading
- TypeScript - bundled declarations, narrowing, zod
- Browser - script tag, ES module and bundlers
- Streaming - JSON6.begin, many values per stream
Step 6Apply it to real work
Pick the tutorial that matches where your data comes from today.
- Config files - organize and load configuration
- Migrate from JSON - what changes and what does not
- Migrate from JSON5 - what you gain and what to check
- Command line tools - convert files in a build step
- Editor support - what exists and the practical workarounds
Step 7Debug and go deeper
When something does not parse, the error pages explain the messages. The FAQ and resources cover the rest.
- Troubleshooting - common problems and fixes
- Parse errors - reading messages and positions
- Error reference - each message, its meaning and cure
- FAQ - short answers
- Resources - repository, package and related projects
Paths by Role
You do not need all seven steps. Use the shortest route that gets you to a working result.
| If you are... | Read, in this order | Why |
|---|---|---|
| Writing config files by hand | Syntax, Cheat sheet, Config files | You need the comfortable subset and a loading pattern, not the corner cases. |
| A Node.js developer | JavaScript, Node.js | The API, then how to load .json6 files and why the CLI is called json-6. |
| A TypeScript developer | TypeScript, Config files | parse returns unknown; learn the validation patterns first. |
| A front-end developer | Browser, Validator | The minified UMD build registers JSON5, which you want to know before you debug it. |
| Processing logs or event feeds | Streaming, Errors | Many values per stream, chunk boundaries and error recovery. |
| Moving from JSON5 | JSON6 vs JSON5, Migrate from JSON5 | JSON6 includes JSON5, so the question is only what you can now use and what other tools will reject. |
| Evaluating whether to adopt it | Why, Compare, Editors | The ecosystem is small; decide with the tooling facts in front of you. |
Adoption note: JSON6 has one reference implementation, the json-6 package, and a small ecosystem around it. There is no official MIME type (the README lists it as a to-do), and ordinary tools that read JSON will reject a file that uses any JSON6 extension. Plan to read .json6 with the package and to convert to JSON where another tool needs the data.
Check Yourself
Before moving on, test your understanding of the syntax. Look at each input in the program below and decide what JSON6.parse returns, or whether it throws. Then run the program and compare. The cases cover the points people most often get wrong: leading-zero numbers, repeated signs, empty array members, multi-line strings, duplicate keys and the lack of commas between members. An array hole and an explicit undefined are different things, and the display tells them apart.
learn-quiz.mjs
import JSON6 from 'json-6'; const cases = [ '0123', // 1 '0o17', // 2 '0b1010_1010', // 3 '---5', // 4 '[1,,3]', // 5 "'line one\nline two'", // 6 (a real newline inside the quotes) '`tick ${notASubstitution}`', // 7 '{ a: 1, a: 2 }', // 8 '{ a: 1 b: 2 }', // 9 '+.5', // 10 '[undefined]', // 11 ]; cases.forEach((text, index) => { let result; try { const value = JSON6.parse(text); result = value === undefined ? 'undefined' : JSON.stringify(value); if (Array.isArray(value)) result = '[' + Array.from({ length: value.length }, (_, i) => (i in value ? (value[i] === undefined ? 'undefined' : JSON.stringify(value[i])) : '<hole>')).join(', ') + ']'; } catch (err) { result = 'throws ' + err.constructor.name; } console.log(String(index + 1).padStart(2), JSON.stringify(text).padEnd(34), result); });Run it:
node learn-quiz.mjsOutput:
1 "0123" 123 2 "0o17" 15 3 "0b1010_1010" 170 4 "---5" -5 5 "[1,,3]" [1, <hole>, 3] 6 "'line one\nline two'" "line one\nline two" 7 "`tick ${notASubstitution}`" "tick ${notASubstitution}" 8 "{ a: 1, a: 2 }" {"a":2} 9 "{ a: 1 b: 2 }" throws Error 10 "+.5" 0.5 11 "[undefined]" [undefined] Three of those results deserve a second look. Number 1 is decimal, not octal, so 0123 is 123, which is the biggest surprise for anyone who knows C, Java or sloppy-mode JavaScript; the package README spends a section on why. Number 8 shows that a duplicate key is not an error: the last value wins, as with a JavaScript object literal. Number 9 shows that a missing comma between members is an error. If you get any of these wrong, reread numbers and objects and arrays.
FAQ
Where should a complete beginner start?
Read Why JSON6, then the Getting Started tutorial, then paste something into the validator. That sequence takes you from idea to a parsed file quickly.
Do I need to know JSON5 first?
No. JSON6 includes everything in JSON5, so learning JSON6 teaches you JSON5. Knowing JSON5 only means the first half of the syntax will look familiar.
Is JSON6 a standard?
No. The package README states that JSON6 is not an official successor to JSON and that JSON6 content may not work with existing JSON parsers. It is a proposal with one reference implementation.
How do I know my information is current?
Every behavior on the language pages was run against json-6 1.1.7, published on 16 October 2026. The pages say so where it matters. If a newer release changes behavior, the package changelog is the first place to look.
What is the quickest way to try JSON6 in code?
Run npm install json-6 and then node -e "console.log(require('json-6').parse('{a:1,}'))". For a browser-only try, use the online validator.