JSON Keys Must Be Double-Quoted: Why the Spec Requires It and How to Fix SyntaxErrors

RFC 8259, the JSON specification, defines an object as an unordered collection of zero or more name-value pairs where each name is a string. The specification then defines a string as a sequence of Unicode characters enclosed in quotation marks, and specifies the quotation mark as the character U+0022, which is the double-quote character. This means the JSON specification does not merely prefer quoted keys — it requires them as part of the formal grammar. An object key without double quotes is not JSON.

The reason this requirement exists is unambiguous parsing. Douglas Crockford, who formalized JSON from JavaScript's object literal syntax, made the deliberate decision to require quoted keys to prevent a class of parsing ambiguity. In a JavaScript object literal, {name: value} is valid because the JavaScript parser knows that any bare identifier in the key position is a property name. But a generic parser reading text without a JavaScript grammar has no reliable way to distinguish a bare word being used as a key from a bare word that is an identifier reference, a keyword, or a value. By requiring quotation marks, JSON eliminates this ambiguity entirely — the parser always knows that a quoted string before a colon is a property name.

JavaScript object literal syntax is specifically designed for embedding data directly in JavaScript source code, where the surrounding JavaScript grammar provides context. JSON is designed for language-neutral data interchange, where the text must be parseable without any language-specific context. The requirement for quoted keys is what makes JSON parseable in Python, Ruby, Go, Java, Rust, and every other language using identical grammar rules.

A historical footnote: early implementations of JSON parsers sometimes accepted unquoted keys as a permissive extension. This behavior was never part of the specification and was removed from compliant parsers. Today, compliant JSON parsers in all major languages strictly require double-quoted keys, and the error messages they produce clearly identify the position of the first unquoted character.

The key to diagnosing unquoted key errors quickly is reading the error position number included in the message. Node.js v18 and later prints 'SyntaxError: Expected double-quoted property name in JSON at position N' where N is the character offset from the start of the string at which the parser encountered the unexpected token. If the position is 1, the parser got past the opening brace and immediately found an unquoted character. If the position is larger, count N characters into the JSON string to find the offending key.

For Python, the json.JSONDecodeError message format is 'Expecting property name enclosed in double quotes: line L column C (char N)'. Python gives you both the line and column numbers, which is more helpful for multi-line JSON. Line 1 column 2 means the very first key is unquoted. Use the line and column to jump directly to the offending location in the text.

For jq, the error message is less specific: 'parse error (Invalid numeric literal at line L, column C)'. This message appears because jq tries to interpret the unquoted key as a number before failing. Despite the message mentioning 'numeric literal', the cause is almost always an unquoted string key, not an actual number. The line and column from jq's message still point to the correct location.

The fastest diagnosis tool is to paste the text into ToolDock JSON Validator. It parses the text and highlights the exact character position of the error with a visual indicator. For large JSON bodies, this is significantly faster than counting character offsets manually. Once you find the first unquoted key, search the rest of the text for the same pattern — there are typically multiple unquoted keys in a JavaScript object literal that was mistakenly treated as JSON.

The most reliable fix for the source of unquoted keys is to produce JSON using JSON.stringify rather than constructing JSON text manually or by copying JavaScript object syntax. JSON.stringify takes any serializable JavaScript value and returns a valid JSON string with all keys double-quoted and all string values double-quoted. It handles nested objects, arrays, null, numbers, and booleans correctly without any manual quoting.

For a one-time fix when you have a JavaScript object literal string that you need to parse, the cleanest solution is to move the data into a proper JavaScript object literal in your code and then call JSON.stringify if you need to send it as JSON text, or simply use the JavaScript object directly without JSON round-tripping it at all. Many developers reach for JSON.parse when they have data that is already available as a JavaScript object, which is unnecessary — the extra parse step adds both a performance cost and a correctness risk.

If you receive JSON text from an external source — an API, a file, a database — and it contains unquoted keys, the text is not valid JSON and the source must be fixed. You cannot reliably convert unquoted keys to quoted keys with a regular expression because the regex would also match identifiers inside string values, potentially corrupting the data. The correct fix is at the source: update the code that produces the text to use JSON.stringify or a proper JSON serialization library.

For JavaScript configuration files that are read with fs.readFileSync and then parsed, the correct solution is to either change the file extension to .json and convert the content to valid JSON format, or to use require() for .js files which executes the module correctly. Node.js's built-in import() for ESM also handles .json files natively without requiring manual readFileSync and JSON.parse. For environments that support it, the JSON import syntax (import config from './config.json' assert {type: 'json'}) is the cleanest approach.

The error messages from different JSON parsers for the same unquoted key input are notably different in wording but consistent in pointing to the same location in the source text. Understanding these differences speeds up cross-language debugging.

Python's json module produces json.JSONDecodeError with the message 'Expecting property name enclosed in double quotes'. This message is the clearest of all major JSON parsers — it directly states what is missing. The exception carries .lineno and .colno attributes alongside .doc and .pos for the full context. Python also inherits from ValueError, so catching ValueError catches JSONDecodeError for code that does not need to distinguish the specific error type.

Node.js has changed its JSON error messages across versions. In Node.js v16 and earlier, the message was the less descriptive 'Unexpected token n in JSON at position 1' where 'n' was the first character of the unquoted key — the letter 'n' in {name: value}. This message was confusing because 'unexpected token n' suggests something related to 'n', not a missing quote. In Node.js v18 and later with V8 version 10.1+, the message changed to the more helpful 'Expected double-quoted property name in JSON at position 1', directly mirroring Python's clarity.

Firefox's JSON parser (SpiderMonkey) produces 'JSON.parse: expected property name or \'}\' at line 1 column 2 of the JSON data'. Safari and Chrome both use V8 so they produce the V8 message. This matters when debugging JSON errors reported from browsers — error messages in user-submitted bug reports or telemetry vary by browser.

For Go, the encoding/json package produces 'invalid character \"k\" looking for beginning of object key string' where 'k' is the first character of the unquoted key. Go's message is similar in clarity to Python's updated V8 message. In Rust with serde_json, the error is 'key must be a string' with a line and column reference. All of these parsers implement RFC 8259 correctly — the grammar is the same and the only variation is how each parser words its diagnostic message.

The most common real-world occurrence of the unquoted key error involves configuration files. JavaScript projects accumulate configuration in files like webpack.config.js, babel.config.js, jest.config.js, .eslintrc.js, and many others. These files use JavaScript module syntax and object literal notation, which allows unquoted keys. They are perfectly valid as JavaScript modules loaded with require() or import().

The error occurs when code treats these files as JSON. A script that reads a config file with fs.readFileSync and calls JSON.parse on the text will fail immediately if the file uses JavaScript syntax. The script might have been written for a .json config file and later pointed at a .js config file without updating the parsing code. It might also be a generic configuration loader that attempts to detect the format but falls back to JSON.parse incorrectly.

Another common scenario involves JSON5 format. JSON5 is a community extension of JSON that explicitly allows unquoted keys, single-quoted strings, trailing commas, and comments. Some projects use JSON5 for their configuration because it is friendlier for human-written files. JSON5 files often use the .json5 extension, but sometimes they use .json or no extension, leading downstream code to pass them to a standard JSON.parse that does not understand JSON5 syntax. The fix is to use the json5 npm package for JSON5 parsing rather than the native JSON.parse.

A third scenario involves database-stored JSON that was entered manually by an operator or exported from a tool that produces JavaScript-like output rather than strict JSON. MongoDB's shell, for example, accepts JavaScript syntax in queries. Export tools that read MongoDB shell scripts and then feed the output to a JSON parser encounter unquoted keys. The solution is to use the mongodump/mongoexport tools which produce valid JSON output, or to apply JSON.stringify to the JavaScript objects in the shell before exporting.

Preventing unquoted key errors before they reach a parser is significantly easier than debugging them after the fact. Modern code editors offer JSON validation as a built-in feature that highlights syntax errors including unquoted keys in real time as you type.

In VS Code, files with the .json extension receive automatic JSON syntax validation. The editor underlines any syntax error with a red squiggly line and shows the error in the Problems panel. Hovering over the underlined text displays the error message. This catches unquoted keys immediately when editing JSON files. However, files with .jsonc extension allow comments (JSON with Comments), and files with no extension that contain JSON-like content do not receive automatic validation — you must add 'json' to the language mode selector in the status bar.

For VS Code specifically, the editor also supports enabling JSON validation for files that are not .json by adding language associations to your settings.json: 'files.associations': {'*.config': 'json'} forces JSON validation on .config files. For project-specific settings, this configuration can go in .vscode/settings.json and is committed to the repository so all team members benefit from the same editor validation.

JetBrains IDEs (IntelliJ IDEA, WebStorm, PyCharm) provide JSON inspection that highlights structural errors including unquoted keys. The inspection runs on any file identified as JSON through its extension or through the file type association settings. Both editors also provide a JSON reformatter that adds missing quotes to keys when reformatting, though relying on the formatter to fix invalid JSON is less reliable than producing valid JSON from the start.

For automated enforcement in CI, running jsonlint or ajv on all .json files in the repository as part of the lint step catches any unquoted key before it is merged. A simple check like find . -name '*.json' -exec jsonlint {} + in a CI step prevents invalid JSON from entering the codebase. For projects that also use JSON Schema, validating all JSON files against their schemas in CI catches both syntax errors and semantic contract violations simultaneously.