Getting Started with JSON5

Learn JSON5 in 10 minutes. From zero to your first config file.

What you'll learn: What JSON5 is, how to install and use it, and how to create your first JSON5 configuration file with comments and trailing commas.

What is JSON5? Installation First File Parsing Next Steps

What is JSON5?

JSON5 is an extension to JSON that makes it easier for humans to write and maintain. It adds features from JavaScript that JSON lacks:

Comments

Add documentation with // and /* */

Trailing Commas

Cleaner diffs when adding/removing items

Unquoted Keys

Less visual noise: name vs "name"

Single Quotes

Choose between 'text' or "text"

Good news: Every JSON file is already valid JSON5! You can adopt JSON5 features gradually without breaking existing files.

Step 1: Install JSON5

Install the official JSON5 library for your programming language.

JavaScript / Node.js

npm install json5

Python

pip install json5

See all language guides: JavaScript, Python, Go, Rust, Java, C#

Step 2: Create Your First JSON5 File

Create a file called config.json5 with the following content:

{ // Application Configuration // This file uses JSON5 for better readability name: 'my-awesome-app', version: '1.0.0', // Server settings server: { host: 'localhost', port: 3000, debug: true, // Enable for development }, // Feature flags features: [ 'authentication', 'notifications', 'dark-mode', // Trailing comma is OK! ], }

What makes this different from JSON?

  • Comments document what each section does
  • Unquoted keys like name instead of "name"
  • Single quotes for strings
  • Trailing commas after the last items

Step 3: Parse Your JSON5 File

Read and parse your config file in your application:

JavaScript / Node.js

import JSON5 from 'json5'; import { readFileSync } from 'fs'; // Read the file const configText = readFileSync('config.json5', 'utf8'); // Parse JSON5 const config = JSON5.parse(configText); // Use the config console.log(`Starting ${config.name} on port ${config.server.port}`); // Output: "Starting my-awesome-app on port 3000"

Python

import json5 # Read and parse the file with open('config.json5', 'r') as f: config = json5.load(f) # Use the config print(f"Starting {config['name']} on port {config['server']['port']}") # Output: "Starting my-awesome-app on port 3000"

That's it! You've just created and parsed your first JSON5 file. The comments are stripped during parsing - they exist only for human readers.

Quick Syntax Reference

Here's what JSON5 allows that JSON doesn't:

Feature JSON JSON5
Comments Not allowed // comment and /* comment */
Trailing commas Syntax error [1, 2, 3,]
Unquoted keys Must quote { name: 'value' }
Single quotes Double only 'single' or "double"
Hex numbers Not allowed 0xFF
Infinity / NaN Not allowed Infinity, NaN

Next Steps

Now that you know the basics, here's where to go next:

Set Up Your Editor

Get syntax highlighting and validation in VS Code.

Language-Specific Guide

Learn the full API for JavaScript, Python, or your language.

Config File Guides

Learn how popular tools use JSON5 features.

More Examples

See real-world JSON5 code examples.

Ready for More?

Explore examples or dive into the complete specification.

See Examples Full Specification