What is JSON5? Features, Syntax, and When to Use It

What is JSON5?

JSON5 is a superset of JSON (JavaScript Object Notation) that aims to make the format more human-friendly while maintaining compatibility with JavaScript's object literal syntax. Created by Andrew Eisenberg in 2012, JSON5 extends JSON with features from ECMAScript 5 (ES5) that many developers wished were in JSON.

The key philosophy: JSON5 is to JSON what ES5 is to ES3 — it adds syntactic sugar that makes the format easier to write and read, especially for configuration files and human-maintained data.

While JSON is strictly specified and intentionally limited (no comments, no trailing commas, all keys must be quoted), JSON5 relaxes these restrictions to match what JavaScript developers expect.

JSON5 vs JSON: Quick Comparison

Feature 1: Comments

The most requested feature for JSON is comments, and JSON5 delivers.

JSON (invalid):

{
  "name": "config",
  // This is a comment - INVALID IN JSON
  "version": 1
}

JSON5 (valid):

{
  "name": "config",
  // This is a single-line comment
  "version": 1,
  /* This is a
     multi-line comment */
  "debug": true
}

Comments are invaluable for configuration files where you need to explain why certain values are set.

Feature 2: Trailing Commas

Trailing commas make it easier to add, remove, and reorder items without worrying about removing the comma from the previous line.

JSON (no trailing comma):

{
  "items": [
    "apple",
    "banana",
    "orange"
  ],
  "settings": {
    "theme": "dark",
    "lang": "en"
  }
}

JSON5 (trailing commas allowed):

{
  "items": [
    "apple",
    "banana",
    "orange",  // Trailing comma - no problem!
  ],
  "settings": {
    "theme": "dark",
    "lang": "en",  // Trailing comma here too
  },
}

This is especially helpful when using version control — diffs are cleaner when adding new items.

Feature 3: Unquoted Object Keys

In JSON5, object keys that are valid identifiers don't need quotes.

JSON:

{
  "first-name": "John",
  "last_name": "Doe",
  "age": 30
}

JSON5:

{
  firstName: "John",
  last_name: "Doe",  // Underscore is valid in identifiers
  age: 30  // No quotes needed for simple keys
}

Rules for unquoted keys:

• Must start with a letter, underscore, or $
• Can contain letters, digits, underscores, or $
• Cannot contain spaces or special characters (use quotes for those)

{
  // Valid unquoted keys:
  name: "test",
  _private: true,
  $element: "div",
  key123: "value",

  // Must be quoted:
  "first-name": "John",    // Hyphen
  "user age": 30,          // Space
  "123key": "value"        // Starts with digit
}

Feature 4: Single-Quoted Strings

JSON5 allows both single and double quotes for strings.

JSON:

{
  "message": "Hello \"World\"",
  "path": "C:\\Users\\Name"
}

JSON5:

{
  message: 'Hello "World"',  // Single quotes avoid escaping
  path: 'C:\\Users\\Name',
  template: "Use 'single' inside double",
}

Single quotes are especially useful when your string contains double quotes.

Feature 5: Multiline Strings

JSON5 supports multiline strings using backticks (template literals) or escaped newlines.

JSON5 with backticks:

{
  description: `This is a
multiline string
that spans multiple lines.`
}

JSON5 with escaped newlines (also valid in JSON with \n, but more readable here):

{
  poem: "Roses are red,\nViolets are blue,\nJSON5 is better,\nFor me and you."
}

Feature 6: Enhanced Number Formats

JSON5 supports number formats that are valid in JavaScript but not in JSON.

{
  // Hexadecimal
  hexValue: 0xFF,       // 255
  hexValue2: 0x1A3,    // 419

  // Leading or trailing decimal points
  float1: .5,          // Same as 0.5
  float2: 5.,          // Same as 5.0

  // Positive/negative signs
  positive: +10,
  negative: -10,

  // Infinity and NaN (in some implementations)
  // max: Infinity,
  // invalid: NaN
}

Note: While JSON only allows 123, JSON5 also allows +123, 0x1F, .5, and 5..

Real-World Example: Configuration File

Here's how JSON5 shines for configuration files:

JSON (strict, no comments):

{
  "server": {
    "port": 3000,
    "host": "localhost"
  },
  "database": {
    "url": "mongodb://localhost:27017/myapp",
    "options": {
      "useNewUrlParser": true,
      "useUnifiedTopology": true
    }
  },
  "logging": {
    "level": "info",
    "format": "combined"
  }
}

JSON5 (readable, with comments):

{
  // Server configuration
  server: {
    port: 3000,        // Development port
    host: 'localhost',
  },

  // Database settings
  database: {
    url: 'mongodb://localhost:27017/myapp',
    options: {
      useNewUrlParser: true,
      useUnifiedTopology: true,
      // Enable debug mode in development
      debug: false,
    },
  },

  // Logging configuration
  logging: {
    level: 'info',
    format: 'combined',
    // outputs: ['console', 'file'],  // Commented out for now
  },
}

When to Use JSON5

✅ Good Use Cases

1. Configuration Files — .eslintrc.json5, .babelrc.json5, tsconfig.json5
2. Human-Edited Data — When non-programmers need to edit the file
3. Development Tools — Build configs, linter rules, task definitions
4. Documentation Examples — Code samples with explanatory comments
5. Prototyping — Quick data structures during development

❌ When NOT to Use JSON5

1. API Requests/Responses — Stick to standard JSON for interoperability
2. Data Exchange — Third-party integrations expect standard JSON
3. Database Storage — Most databases expect standard JSON
4. Public-Facing Formats — If external systems consume your data
5. Strict Validation Environments — When schema validation expects JSON

Using JSON5 in Your Project

JavaScript/Node.js

npm install json5

const JSON5 = require('json5');

// Parsing JSON5
const config = JSON5.parse(`
  // Configuration
  server: {
    port: 3000,
  }
`);

// Stringifying to JSON5
const output = JSON5.stringify({ x: 1, y: 2 }, null, 2);

Build Tools Integration

Many tools support JSON5 natively or via plugins:

• ESLint: .eslintrc.json5 (with --config flag)
• PostCSS: postcss.config.json5
• Babel: via json5 package in config files

Browser Support

JSON5 is not natively supported in browsers — you need to parse it with a library:

<script src="https://unpkg.com/json5@2/dist/index.min.js"></script>
<script>
  const data = JSON5.parse('{ key: "value" }');
  console.log(data);
</script>

Migration from JSON to JSON5

Converting is straightforward — JSON is valid JSON5:

1. Rename your file from .json to .json5
2. Add comments where helpful
3. Remove unnecessary quotes from keys
4. Add trailing commas for easier editing
5. Use single quotes where convenient

Summary

JSON5 brings developer-friendly features to the JSON format:

Bottom line: Use JSON5 for human-maintained files (configs, settings), but stick to standard JSON for data interchange (APIs, databases, third-party integrations).

Related Tools

• JSON Formatter — Format and validate standard JSON