Introduction

JavaScript Object Notation, or JSON, has become the undisputed lingua franca for data interchange on the web. Its simplicity, human-readability (to an extent), and ease of parsing by machines have cemented its place in APIs, configuration files, and countless other applications.

However, as developers, we've all felt the occasional friction with JSON's strictness. Enter JSON5, a proposed extension to JSON that aims to make it more human-friendly and flexible, particularly for configuration files and development scenarios.

But what exactly are the differences? When should you stick with battle-tested JSON, and when can JSON5 offer a significant improvement? Let's dive deep.

What is JSON?

JSON, formally specified in RFC 8259, is a lightweight data-interchange format. It's easy for humans to read and write and easy for machines to parse and generate. Its design principles are derived from JavaScript object literal syntax, but it has become language-agnostic.

Key Characteristics of JSON:

• Human-Readable: Relatively simple text format.
• Language Independent: Parsers exist for virtually every programming language.
• Data Types: Supports a limited but effective set of data types:
• Strings: Sequences of Unicode characters, enclosed in double quotes only. ("Hello World")
• Numbers: Integers or floating-point numbers. (42, 3.14159, -100, 6.022e23)
• Booleans: true or false.
• Arrays: Ordered lists of values, enclosed in square brackets []. ([1, "two", true])
• Objects: Unordered collections of key/value pairs, enclosed in curly braces {}. Keys must be strings in double quotes. ({"name": "Alice", "age": 30})
• null: Represents an empty value.

The Strict Rules of JSON (The "Pain Points"):

• No Comments: This is a major one for configuration files.
• Keys Must Be Double-Quoted: "key": value is mandatory.
• Strings Must Be Double-Quoted: "string value" is the only way.
• No Trailing Commas: The last element in an array or object cannot have a comma after it.
• Numbers: No hexadecimal format, no leading/trailing decimal points (e.g., .5 or 5.), no explicit + sign. Infinity and NaN are not allowed.
• No Multi-line Strings: Strings must be on a single line, or you must use \n escapes.

Example of Valid JSON:

{
  "name": "JSON Demo",
  "version": "1.0.0",
  "active": true,
  "description": "A simple demonstration of JSON syntax.",
  "authors": [
    {"name": "Eva", "email": "eva@example.com"},
    {"name": "Adam", "email": "adam@example.com"}
  ],
  "settings": {
    "port": 8080,
    "retryAttempts": 3,
    "features": null
  }
}

This strictness, while ensuring unambiguous parsing, can make manual editing and configuration files less ergonomic.

What is JSON5? The Human-Friendly Superset

JSON5 (JSON for the ES5 Era) is a proposed extension to JSON that aims to be easier for humans to write and maintain. It's a superset of JSON, meaning any valid JSON is also valid JSON5. It incorporates features from ECMAScript 5 (hence the "5") that make life easier for developers.

The primary goal of JSON5 is not to replace JSON in machine-to-machine communication but to provide a more convenient format for human-authored files, like configurations.

Key Features and Enhancements in JSON5:

• Single-line comments: // This is a comment
• Multi-line comments: /* This is a\nmulti-line comment */
• Unquoted Object Keys: If keys are valid ECMAScript 5 identifiers (e.g., no spaces, not reserved words), they don't need quotes — { key: "value" } instead of { "key": "value" }
• Single-Quoted Strings: Strings can be enclosed in single quotes — 'This is a valid string'
• Trailing Commas: Allowed in arrays and objects, making reordering and adding items less error-prone — [1, 2, 3,] and { "a": 1, "b": 2, }
• Multi-line Strings: Strings can span multiple lines using a preceding backslash before the newline — "This is a \ multi-line string"
• Hexadecimal: 0xDEADBEEF
• Leading or trailing decimal points: .5, 5.
• Explicit plus sign: +100
• Infinity and NaN: Supported as values. -Infinity is also valid.

Example of Valid JSON5:

// This is a JSON5 configuration file
{
  appName: "My Awesome App", // Unquoted key
  version: '1.2.3-beta',     // Single-quoted string
  debugMode: true,           // Standard boolean
  /*
   * Server settings.
   * These are critical for deployment.
   */
  server: {
    host: "localhost",
    port: 0x1F90, // Hexadecimal for 8080
    retryAttempts: 3,
    timeout: .5, // Leading decimal point
    maxConnections: +100, // Explicit plus sign
  },
  featureFlags: [
    "newDashboard",
    "betaAnalytics",
    "experimentalApi", // Trailing comma is allowed
  ],
  description: 'This application demonstrates \
the power of JSON5 for more readable configurations.', // Multi-line string
  errorThreshold: Infinity,
  initialValue: NaN,
}

Notice how much more natural this feels for manual editing, especially with comments and less quoting noise.

JSON vs. JSON5: A Side-by-Side Feature Comparison

When to Use JSON

JSON's strictness and universal support make it the ideal choice for:

• APIs (Data Interchange): When your application communicates with external services or exposes an API, JSON is the de facto standard. Its ubiquity ensures maximum compatibility.
• Strict Data Validation: If you need to ensure data adheres to a very specific, machine-enforced schema, JSON's limitations can be a benefit.
• Maximum Performance: JSON parsers are highly optimized and generally faster than JSON5 parsers due to the simpler syntax. For performance-critical paths, JSON might be preferred.
• Broad Tooling Ecosystem: Virtually every language, framework, and tool has built-in JSON support. You rarely need to add extra dependencies.

Example: API Response (JSON is King)

// GET /api/users/123
{
  "id": 123,
  "username": "json_lover",
  "email": "user@example.com",
  "isActive": true,
  "lastLogin": "2023-10-26T10:30:00Z"
}

When to Use JSON5

JSON5 shines where human interaction and maintainability are paramount.

• Configuration Files: This is the sweet spot for JSON5. tsconfig.json, babel.config.json (though often .js), .eslintrc.json (can be .js or YAML too), and custom application configs benefit immensely from comments, unquoted keys, and trailing commas.

Example: app.config.json5

// Application settings
{
  // Database connection details
  database: {
    type: 'postgres',
    host: 'db.example.com',
    port: 5432,
    user: 'app_user',
    // IMPORTANT: Use environment variables for passwords in production!
    password: 'dev_password_only', // For local dev
  },
  logging: {
    level: 'debug', // Can be 'info', 'warn', 'error'
    filePath: '/var/log/app.log',
  },
  featureToggles: [
    'newReportingModule',
    'darkModeSupport', // Love this feature!
  ],
}

• Development Environments: For internal tools, scripts, or manifests that developers frequently edit.
• Storing Human-Editable Data: If you have data that needs to be occasionally tweaked by non-programmers (with some guidance), JSON5's leniency can reduce errors.
• When You Control Both Ends: If you're building a system where you control both the data producer and consumer, and human-readability is a plus, JSON5 is a safe choice.

Working with JSON5: Libraries and Tooling

Since JSON5 isn't natively supported by most environments like standard JSON is, you'll need to use a library.

JavaScript/Node.js

The most common library is json5. Install it with:

npm install json5
# or
yarn add json5

Create config.json5 and add this:

{
  myAppName: 'My App',
  server: {
    port: 8080
  }
}

Create main.js and add this:

const JSON5 = require('json5');
const fs = require('fs');

// Reading a JSON5 config file
try {
    const configFileContent = fs.readFileSync('config.json5', 'utf8');
    const config = JSON5.parse(configFileContent);
    console.log('App Name:', config.myAppName);
    console.log('Port:', config.server.port);
} catch (err) {
    console.error('Failed to parse JSON5 config:', err);
}

// Stringifying an object to JSON5
const myObject = {
    name: "Data to stringify",
    values: [1, 2, /* a little comment */ 3, ], // comments won't appear in stringify by default
    nested: {
        isCool: true,
    }
};

const json5String = JSON5.stringify(myObject, null, 2); // null for replacer, 2 for space
console.log('\nStringified JSON5:\n', json5String);

This code will output:

Note: JSON5.stringify will produce valid JSON5, which might not be valid JSON (e.g., unquoted keys, single quotes). If you need to output strict JSON, use JSON.stringify.

Other Languages:

Libraries for JSON5 exist in many other languages:

• Python: pyjson5 (pip install pyjson5)
• Java: json5.java
• C++: json5cpp
• See the full list HERE

Editor support for JSON5 syntax highlighting is also becoming increasingly common in popular IDEs like VS Code.

Potential Downsides of JSON5

• Not a Web Standard: Unlike JSON, JSON5 is not an IETF standard. It's a community-driven specification.
• Library Dependency: You introduce an external dependency to parse/stringify JSON5.
• Interoperability: If you send JSON5 to a system expecting standard JSON, it will fail. Always convert to standard JSON (JSON.stringify()) before transmitting to external systems that don't explicitly support JSON5.
• Slightly Slower Parsing: The added flexibility means parsing can be marginally slower than highly optimized JSON parsers, though often negligible for typical use cases like config files.

Conclusion: Choose the Right Tool for the Job

JSON remains the king for data interchange, APIs, and scenarios requiring strict, universal compatibility. Its simplicity and widespread support are undeniable strengths.

JSON5 emerges as a powerful ally for human-authored and human-maintained files, especially configurations. Its enhancements significantly improve the developer experience by allowing comments, more flexible syntax for keys and strings, and forgiving trailing commas.

The choice isn't about one being "better" than the other; it's about context:

• Machine-to-Machine Communication? Stick with JSON.
• Human-Editable Configuration Files? JSON5 is an excellent choice.
• Need Comments in your JSON-like data? JSON5.
• Concerned about adding a library or strict interoperability? Lean towards JSON.

By understanding the strengths and ideal use cases for both JSON and JSON5, you can make more informed decisions, leading to cleaner code, more maintainable configurations, and a smoother development workflow.

More 'How Tech Works' Articles

In the following list, you can find all 'How Tech Works' articles I've ever written. Those explain how different technologies work under the hood.

If you enjoyed reading this article or found it helpful, you can:

• Leave a comment
• Follow me for more Python, PHP, JavaScript, and AI articles

Find me on LinkedIn.

Find us at GenericSoft.eu! We can provide a solution to your problem.