How to add comments to JSON files: Methods, examples, and best practices

Informatec Digital » Programme » How to add comments to JSON files: Methods, examples, and best practices

Working with JSON files is a daily necessity for software developers, web application creators, and those managing modern configurations. However, something as commonplace as adding an explanatory comment within the file can become a real nightmare, since the JSON format, by its very nature, doesn't officially allow comments . Many wonder how it's possible to document the structure or clarify specific parts of the data without introducing an analysis error or engaging in bad practices.

Throughout this article, you'll learn why JSON doesn't allow comments , the best alternatives available today—because, of course, developers always find ways to circumvent limitations—and the implications of each method. You'll also discover how to avoid compatibility issues and the smartest solutions if you need to annotate JSON files for teamwork or to anticipate future changes.

Why doesn't JSON natively support comments?

Before we delve into the tricks and alternatives, it's important to understand the root of the problem. JSON (JavaScript Object Notation) was created as a simple and efficient format for exchanging data between systems. Its main strength is precisely that simplicity: it only supports data structures such as objects, arrays, strings, numbers, booleans, and null values. There's no space reserved for metadata or those explanatory comments so useful in other programming languages.

This limitation is not an oversight, but a deliberate design decision made by Douglas Crockford, the creator and main driving force behind the format. As he explained, he removed comments from the specification because many people were using them to introduce parsing directives that could ultimately lead to incompatibilities between different applications or hinder automatic processing. The idea was for JSON to be as universal and predictable as possible , sacrificing aspects such as internal documentation for the sake of interoperability.

If you've ever tried using typical comments // comentario, /* comentario */ or even # comentario in Python or Bash style in a JSON file, you may have encountered the error “Comments are not permitted in JSON”It's not even possible to bypass the restriction with some simple hack: standard parsers will refuse to read files with content that doesn't fully conform to the format.

What problems does the absence of comments in JSON cause?

The inability to add comments has practical consequences that can affect everything from personal projects to the development of large enterprise applications:

• The documentation within the JSON file itself is non-existentThis makes it difficult to understand the function of each key or the reason for certain values, especially as time passes or different people work with the same file.
• Modifications, extensions or revisions They must be made without being able to justify changes directly in the file, which can lead to confusion in collaborative projects.
• Errors due to forgetfulness or interpretation are more likely, since no one will be able to explain online what each part does or what the logic behind a complex structure is.

Since there is no official way to insert comments, the community has developed different strategies and tricks to document, albeit indirectly, the content of the JSON files.

Workarounds: How to include comments in JSON files

Although the specification prohibits comments in the traditional style , there are several ways to document JSON files. Each has its advantages, limitations, and risks, so it's important to understand them before deciding which one to use for your project.

1. Add special keys for comments (the most common solution)

Undoubtedly, The most widespread and simple technique is to add key-value pairs whose purpose is to act as a comment. Unlikely code names are often used, such as _comentario o __nota__, which do not collide with any of the keys of the “real” data.

Basic example:

{ "_comment": "This is a configuration file for application X", "user": "JohnDoe", "permissions": , "active": true }

The goal is for applications that consume the JSON to ignore these keys , or for developers to immediately recognize them as comments and not as information relevant to operation.

Advantages:

• Allows you to add explanations within the file itself, next to each field that requires it.
• Compatible with any tool that respects the JSON standard (as long as it ignores keys it doesn't recognize).

Disadvantages:

• These "comments" become part of the data. If the file is used in a public API or in production environments where size matters, this method can unnecessarily increase the weight of the load.
• Being an unofficial convention, There could be problems if in the future the JSON schema legitimately needs a key with the same name..
• Any parser that expects only certain keys may fail if these unexpected inputs appear.

2. Unofficial variants of JSON: JSONC

Another option that has gained popularity among developers is to use JSONC (JSON with comments), an unofficial format that does allow comments to be included using // y /*...*/. However, These JSONC files require a preprocessor: a tool that removes comments before passing the file to any standard parser.

JSONC example:

{ // App administrator user "user": "admin", /* Advanced permission settings */ "permissions": }

To work with JSONC, you can find online tools, Node.js packages, or editor extensions like Visual Studio Code that support this format during development. Once your file is ready to be deployed to production, the preprocessor removes comments and generates valid JSON.

Pros: Facilitates documentation during development, without contaminating the final data.

Cons: This method is only valid during the development phase. If you forget to process the file before using it, the analyzers will complain.

3. External documentation: the safest option

For projects where strict adherence to the JSON standard is essential, the safest approach is to keep the documentation separate from the JSON file itself . You can do this by creating a Markdown or plain text file that explains the structure, the purpose of each field, and any other relevant details. It's also common to use documentation in the project's wiki, or tools like Swagger/OpenAPI if you're defining APIs.

Advantages:

• There is no way to break parser compatibility or increase data size.
• Avoid name conflicts and keep your JSON file clean and focused on the data.

Disadvantages:

• The documentation is separated. If someone edits the JSON without updating the external document, this can lead to a lack of coordination.
• It is less practical for small projects or for those who prefer to find all the information in one place.

4. Preprocessors and build tools

Expanding on the JSONC strategy, large projects often use custom preprocessors that allow the inclusion of comments or special directives in configuration files. These tools, integrated into the application build process, handle cleaning up all comments before deploying the product to production.

This method combines the convenience of internal documentation with the security of compliance with the standard , but requires a more sophisticated workflow and attention to avoid accidentally uploading raw files.

Advanced Examples: Comments in Complex JSON Structures

The case studies show how conventions can be leveraged to document JSON files, even when nested objects or arrays are present.

Example with several different comments:

{ "_comment1": "Basic personal information", "name": "Ana", "age": 28, "city": "Madrid", "_comment2": "Job information", "company": "InnovaSoft", "position": "Developer", "experience": 5 }

If you need to add comments inside nested objects:

{ "name": "Luis", "_comment": "Additional information", "additionaldata": { "email": "[email protected]", "_comment": "This email must be verified by the user" } }

Remember: JSON does not allow repeated keys at the same object level, so if you need to put multiple comments, you'll have to give them unique names like _comentario1, _comentario2, etc.

Implications and considerations when documenting JSON files

Using any of the above methods has side effects that are important to consider before making a final decision:

• Comment keys take up space and travel to the backend, API, or whatever system consumes the JSON.If efficiency is critical, overloading is best avoided.
• Certain schemes, such as public API contracts, may reject files with unexpected keys.Always consult the official documentation for the service before adding comments of this type.
• If the project evolves and one day you need to use a key that you already used as a comment, incompatibilities may arise.. Try to choose unusual names to minimize risk.
• Some JSON parsers allow the existence of unknown keys, others do not. Portability may be affected depending on the language or library you use..

Differences with other data formats: YAML and XML

You might be wondering why widely used formats like YAML or XML allow comments, while JSON doesn't. The answer lies in the approach of each format.

YAML It stands out for its readability and for allowing comments preceded by # anywhere in the file. XML, on the other hand, makes use of tags to insert explanations that will be ignored by parsers.

JSON, as we have seen, prioritizes universality and minimal complexity, eliminating any element that is not part of the data; hence its popularity in APIs, configurations, and environments where efficiency, speed, and compatibility are crucial.

What risks are involved in using non-standard methods?

Implementing alternative solutions is not without risks . The most important ones are:

• Data loss- If a future release standardizes any of the comment keys, you could lose information or create a conflict in your application.
• Confusion and misunderstandings: Other developers may not be familiar with your convention and think that comment keys are real data.
• Errors in the analysis- If your JSON arrives at a system that expects a rigid schema, including unsupported fields may result in file rejection or a silent failure.

Key questions about JSON comments

• Is there an official way to add comments in JSON? No, the specification does not allow it.
• Why is there no official support? To keep JSON as simple, fast, and compatible as possible.
• What alternatives do I have? Add custom keys for comments, use preprocessors during development, or maintain documentation in external files.
• Are there risks in adding comments in a non-standard way? Yes, especially in terms of compatibility, data confusion, and potential information loss.
• Can I use JSONC in production? Not recommended. It should only be used in development environments in conjunction with a preprocessor that cleans up comments before deployment.
• What happens if my commented JSON file reaches an external API? You will most likely receive an error and the file will be rejected.

Recommendations and best practices for documenting JSON files

Depending on the environment and requirements of your project, you can choose the alternative that best suits your needs . Some helpful guidelines:

• In development, use comment keys or JSONC if it helps you. But don't forget to clean up your files before releasing them to production.
• For long-term or collaborative projects, opt for external documentation.: It is the most secure, scalable and universal option.
• If you must include comments in the file, use clear conventions and key names that cannot be collided.as the __nota_privada_dev__ or similar.
• Always check compatibility with the tools, APIs or external systems that will consume your JSON files..

Essentially, working with JSON means accepting its rules: no official comments, but there's always room for creativity . If you need to leave notes for yourself or your colleagues, choose the least intrusive option, document your conventions well, and always keep an eye on future compatibility. While it's annoying not being able to leave clarifications within the file itself, that's precisely where the challenge and value of JSON's minimalist design lie.