The first slash is where the file falls apart. Someone puts // switch this off in production above a configuration object, the editor colors it green, and the same file crashes when a test runner calls JSON.parse().
So, can you make comments outside the brackets in JSON? No. Standard JSON does not support comments before an opening { or [, after the closing bracket, or anywhere inside the value. Developers still want notes for documentation, TODOs, and examples. A future teammate should know why a timeout is 17 seconds or where an endpoint came from.
There are cleaner ways to keep those notes without breaking the data.
- Why the JSON grammar leaves comments out
- Failure modes. What a strict parser sees when it reaches
//or/* */. - Workarounds for APIs, repositories, and internal configuration files.
- JSONC and comment-friendly formats, because some files that look like JSON belong to another format entirely.
Quick answer
The official JSON specification, RFC 8259 defines a JSON text as one serialized value with optional JSON whitespace around it. Its grammar includes objects, arrays, strings, numbers, true, false, and null. Comment tokens never appear in that grammar.
That rule covers every tempting location.
- Before the outer
{}or[] - Inside an object, even between two otherwise valid properties. Same problem inside an array.
- After a key, value, or final closing bracket
A parser may accept extra syntax as an extension. RFC 8259 explicitly permits parsers to accept non-JSON forms, which explains why a relaxed tool can appear happy. The resulting document still falls outside standard JSON.
If an API, validator, or library asks for strict JSON, comments cannot go anywhere.
Does JSON Support Comments? RFC 8259
RFC 8259 leaves no opening for a comment token. Its top-level grammar is remarkably short.
JSON-text = ws value ws
Here, value can be an object, array, string, number, boolean, or null. The ws parts allow only a space, horizontal tab, line feed, or carriage return. Neither // nor /* */ qualifies as whitespace, so a comment fails before the value, after it, and between members inside it.
JSON was designed as a small, portable data-interchange format. It moves structured values between systems that may share no programming language, editor, or deployment process. Keeping the grammar narrow makes that job easier.
Its syntax came from JavaScript object literals, although the JSON grammar deliberately kept only a limited set of tokens. JavaScript accepts comments because source code needs notes for people. A JSON document carries serialized data.
That simplicity pays off. Parsers are available almost everywhere, and generators produce predictable output. The missing commentary layer is the cost. A value such as "retries": 4 says nothing about who chose four or what happens on the fifth failure.
RFC 8259 lists the allowed structural characters, literal names, strings, and numbers. A slash is valid inside a quoted string. Outside a string, it begins no legal JSON token. A parser may deliberately accept extensions, as the RFC permits, but that relaxed input is outside the standard grammar. Position cannot rescue it, including the quiet-looking space above the first bracket.
What happens when you try
This leading note makes the entire document invalid.
// Used by the staging worker only
{
"endpoint": "https://staging.example.com",
"retries": 4
}
Moving the note to the bottom changes nothing.
{
"endpoint": "https://staging.example.com",
"retries": 4
}
// Keep this in sync with the worker
A strict parser reaches / where it expects a value, whitespace, or the end of the input. JavaScript runtimes commonly report a message such as Unexpected token / in JSON, though wording varies. One bad comment can stop a build, reject an API request, or keep a service from loading its startup configuration..
Block comments fail as well. Put /* TODO: rotate this URL */ between two properties and the parser stops at the same first slash.
The confusing part is the editor. VS Code can recognize certain files as JSON with Comments and make the syntax look healthy. Then a container starts with a strict parser, and yesterday's green comment becomes a production error at 6:07 a.m. Extensions travel poorly unless every step knows about them.
Does outside the brackets help?
Brackets are only part of the story. RFC 8259 describes a JSON text as optional whitespace, followed by one value, followed by optional whitespace. That value may be an object or array, but a string, number, boolean, or null can also be a complete JSON document.
Spaces, tabs, line feeds, and carriage returns are the four permitted whitespace characters. A comment is more than whitespace. So this is valid:
{ "enabled": true }
Add // config to either blank line and validity disappears. Extra prose such as Configuration starts here fails for the same reason.
A byte order mark is a related edge case. RFC 8259 says networked JSON generators must not add one, while parsers may ignore a leading BOM. Comments receive no similar allowance. A parser that tolerates a BOM may still reject every comment.
Safe alternatives to comments in JSON
Keep notes in a separate file
Leave config.json as pure data and put the reasoning beside it. A README.md works for most repositories. A longer setup may deserve CONFIG_NOTES.md.
External documentation can hold links, examples, and a short history of decisions. Keep it close to the data. Notes hidden three directories away age surprisinly fast.
Useful places include:
README.md- A schema plus a short guide.
- Next to the data. Link the documentation from the same pull request that changes the configuration.
Add deliberate metadata fields
A property named _comment is ordinary, valid JSON.
{
"_comment": "The reporting job needs this endpoint until migration TX-184 is complete.",
"endpoint": "https://reports.example.com",
"_meta": {
"owner": "data-platform",
"reviewAfter": "2026-10-15"
}
}
Your application must define what those fields mean. Prefixing them with _ reduces accidental collisions, but creates no special behavior. An external API may reject or store unknown properties. Strip metadata before transmission when the contract does not allow it.
I could be wrong here, but _comment fields become clutter sooner than teams expect. They work well for one compact note. A README or schema handles longer explanations better.
Describe the data with JSON Schema
JSON Schema can define types and required properties while attaching human-readable descriptions.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"retries": {
"type": "integer",
"description": "Maximum attempts before the worker sends the job to the dead-letter queue."
}
},
"required": ["retries"]
}
Editors can show description text on hover, and validators can catch the wrong type before deployment. For schema maintainers, JSON Schema also defines $comment. Implementations may strip it, so do not place end-user instructions there.
Put the explanation in code
When an application owns the configuration loader, document defaults beside that code. A TypeScript module can explain why it applies a 17-second timeout and rejects negative values. Developers then see the reasoning near the behavior (at least during a decent code review).
When commented JSON belongs to another format
VS Code has a documented JSON with Comments mode, usually called JSONC. It accepts // and /* */ comments. It also accepts trailing commas, although the editor warns about them. Files such as settings.json, tasks.json, and launch.json use this mode even though their names end in .json.
JSONC works when the entire toolchain promises to parse it. Name a custom file with .jsonc when possible. A strict API or generic JSON validator will reject it unless comments are removed first.
Other formats were built with human-edited configuration in mind.
| Format | Comment syntax | Sensible use |
|---|---|---|
| YAML | # comment | Nested configuration where the team already understands YAML's whitespace rules |
| TOML | # comment | Application settings with clear sections and simple values |
| Hjson | #, //, and /* */ | A relaxed, human-edited JSON-like file under a controlled parser |
| HOCON | # and // | Layered application configuration, especially in ecosystems that already use it |
Call the format by its real name. A network payload remains strict JSON unless its contract says otherwise.
Practical patterns for real projects
Pure JSON with a README
Keep config.json limited to values. In README.md, explain the configuration shape and example values. Link it from deployment instructions before someone has to guess what mode: 2 means.
Reserved metadata fields
Use one top-level _comment for the file's purpose. Section notes can live in _meta when your loader removes them before transmission. Test that removal, or a refactor may quietly drop it.
Schema beside the data
Store config.schema.json next to config.json. Define types, allowed values, and descriptions, then associate both files in the editor. The team gets tooltips while typing and validation in CI.
Comment-friendly source with JSON output
Write human-managed configuration in YAML or TOML, then convert it during the build. Textavia's JSON to YAML converter can move an existing file, and the YAML to JSON converter brings it back. Pick one authoritative source. Unchecked copies drift.
Recommendations and best practices
APIs and shared data exports should use strict JSON. Remove every comment before transmission, then validate the exact bytes you plan to send.
For internal configuration, JSONC is reasonable when each build step and runtime uses a compatible parser. Document that decision. A .json suffix can mislead the next tool.
Before settling on a pattern, check these details:
- Who parses the file?
- Unknown fields. Will
_commentbe ignored, rejected, stored, or exposed? - Does the note belong to maintainers or to end users? JSON Schema uses
$commentfor the former anddescriptionfor the latter. - Portability. Can another language or vendor read it without cleanup?
- Add validation to CI. One command that parses every JSON fixture catches an accidental comment before the deploy does.
Use one convention across the repository. Mixed rules, where comments work in two files and quietly fail in a third, create the expensive sort of confusion.
Conclusion
Standard JSON does not allow comments anywhere, including outside the opening and closing brackets. Whitespace can surround the single serialized value. Human notes need another home.
Use a nearby README, deliberate metadata properties, or JSON Schema when strict JSON must survive. Choose JSONC, YAML, or TOML when the whole pipeline supports that format. Before shipping a file, paste it into the JSON Formatter. An accidental slash will be easier to find there than in a failed release log.