& ECMAScript

Understanding the relationship between JSON5 and ECMAScript 5.1, and why these features were chosen.

TL;DR: JSON5 extends JSON with a carefully selected subset of ECMAScript 5.1 features. Every JSON5 feature comes directly from ES5.1, ensuring familiarity for JavaScript developers and compatibility with JavaScript tools.

Relationship Feature Mapping Rationale Excluded Features Security

The JSON5-ECMAScript Relationship

JSON5 is named after ECMAScript 5.1 because all of its extended features come directly from that specification. This relationship is intentional and provides several benefits.

Familiarity

JavaScript developers already know the syntax

Well-Defined

Every feature has a precise specification

Compatibility

Works with JavaScript tools and editors

The Superset Chain

JSON5 exists in a hierarchy of data formats, each extending the previous:

ECMAScript 5.1 Object Literals | +-- JSON5 (subset of ES5.1) | +-- JSON (subset of JSON5)

JSON is a subset of JSON5: Every valid JSON document is valid JSON5
JSON5 is a subset of ES5.1: Every valid JSON5 document is valid JavaScript syntax

Feature Mapping to ES5.1

Each JSON5 feature maps directly to a corresponding ECMAScript 5.1 syntax feature.

JSON5 Feature	ES5.1 Reference	Section
Single-line comments	SingleLineComment	7.4
Multi-line comments	MultiLineComment	7.4
Unquoted property names	IdentifierName	7.6, 11.1.5
Single-quoted strings	StringLiteral	7.8.4
Multi-line strings	LineContinuation	7.8.4
Hexadecimal escape	HexEscapeSequence	7.8.4
Trailing commas	Elision	11.1.4, 11.1.5
Hexadecimal numbers	HexIntegerLiteral	7.8.3
Leading decimal point	DecimalLiteral	7.8.3
Trailing decimal point	DecimalLiteral	7.8.3
Positive sign on numbers	UnaryExpression	11.4.6
Infinity	Infinity global property	15.1.1.2
NaN	NaN global property	15.1.1.1

Reference: ECMAScript 5.1 specification is available at ECMA-262 5.1 Edition

Feature Selection Rationale

Each feature in JSON5 was selected based on specific criteria. Here's why each feature was included.

Comments

Why included: Configuration files need documentation. Without comments, developers resort to workarounds like "_comment" keys that pollute the data structure.

Without comments (workaround)

{ "_comment": "Set to prod for production", "env": "dev" }

With JSON5 comments

{ // Set to 'prod' for production env: 'dev', }

Trailing Commas

Why included: Trailing commas make version control diffs cleaner. Adding or removing the last item only shows one line changed instead of two.

JSON diff (2 lines)

"b": 2 -} + "c": 3 +}

JSON5 diff (1 line)

b: 2, + c: 3, }

Unquoted Keys

Why included: Most object keys are valid identifiers. Requiring quotes around simple keys like "name" adds visual noise without benefit.

JSON (verbose)

{ "name": "app", "version": "1.0" }

JSON5 (clean)

{ name: 'app', version: '1.0', }

Single Quotes

Why included: Single quotes reduce the need to escape double quotes, which are common in HTML, SQL, and other embedded content.

JSON (escaping)

{ "html": "<div class=\"box\">" }

JSON5 (no escaping)

{ html: '<div class="box">', }

Hexadecimal Numbers

Why included: Hex notation is natural for colors, bit flags, and memory addresses. Converting to decimal loses meaning.

JSON (decimal)

{ "color": 16711680 }

JSON5 (meaningful)

{ color: 0xFF0000, // Red }

Infinity and NaN

Why included: These IEEE 754 values are part of JavaScript's number system. JSON forces them to become null, losing information.

JSON (lossy)

{ "max": null }

JSON5 (accurate)

{ max: Infinity, }

Excluded ES5.1 Features

Not all ECMAScript 5.1 features made it into JSON5. Some were intentionally excluded to keep the format safe, simple, and unambiguous.

Function Expressions

Why excluded: JSON5 is a data format, not a programming language. Allowing functions would introduce code execution and security vulnerabilities.

Regular Expressions

Why excluded: Regular expressions are executable code and have complex parsing rules that would complicate JSON5 parsers.

Undefined

Why excluded: undefined represents "no value" in JavaScript but doesn't translate well to data interchange. Use null instead.

Computed Property Names

Why excluded: Features like { [expression]: value } require evaluating code, which conflicts with JSON5's data-only nature.

Template Literals

Why excluded: Template literals (`strings`) with interpolation (${expr}) are an ES6 feature and involve code execution.

Octal Number Literals

Why excluded: Octal literals (0777) are deprecated in ES5.1 strict mode and can cause confusion. Use hexadecimal instead.

Security Considerations

While JSON5 is valid JavaScript syntax, you should never use eval() to parse JSON5 from untrusted sources.

Security Warning: Using eval() to parse JSON5 is dangerous. A malicious input could execute arbitrary code in your application.

Safe vs Unsafe Parsing

UNSAFE - Never Do This

// DANGEROUS - DO NOT USE! const data = eval('(' + input + ')'); // Malicious input could be: // (function(){hackSystem()})()

SAFE - Always Use This

import JSON5 from 'json5'; // Safe - uses a proper parser const data = JSON5.parse(input); // Cannot execute code

Why eval() is Dangerous

Even though valid JSON5 is valid JavaScript, an attacker could craft input that:

Executes arbitrary functions in your application context
Accesses and exfiltrates sensitive data
Modifies application state or data
Makes network requests to malicious servers

Safe Parsing Guarantees

The official JSON5 parser provides security guarantees:

No code execution - only data structures are produced
Throws errors on invalid syntax - no undefined behavior
Output contains only: objects, arrays, strings, numbers, booleans, null
No prototype pollution or object injection

Why ECMAScript 5.1?

JSON5 was created in 2012, when ECMAScript 5.1 was the current standard. Here's why it remains based on ES5.1:

Stability

ES5.1 is a stable, well-understood specification. Newer ES features (ES6+) add complexity without clear benefits for a data format.

Universal Support

ES5.1 syntax works in all JavaScript environments, including older browsers and Node.js versions.

Minimal Features

JSON5 already includes all the human-friendly features needed for configuration files. ES6+ features like template literals and symbols don't fit the data interchange use case.

Future Compatibility: The JSON5 specification is stable and complete. There are no plans to add ES6+ features, ensuring long-term compatibility for existing JSON5 files.

Ready to Start Using JSON5?

Check out our tutorials or explore the JavaScript implementation.

Learn JSON5 JavaScript Guide