<div class="post-toc-block float-default with-border"> 
						<div class="post-toc-header">Table of Contents</div>
						<nav id="md-post-toc" class="md-post-toc"></nav>
						</div><p>JSON (<strong>JavaScript Object</strong>) Notation is a popular data interchange format used by developers to store and exchange data. It&#8217;s lightweight, easy to read, and easy to parse, making it ideal for various applications. However, a key limitation is that <strong>JSON does not support comments</strong> natively. This can be a problem when you want to include explanations, notes, or any sort of annotation within your JSON files.</p>
<blockquote>
<p>⚠️ JSON does not officially support comments (per RFC 8259). The methods below are workarounds you can use depending on your use case.</p>
</blockquote>
<p>In this article, we&#8217;ll explore some practical workarounds to add comments to a JSON file without breaking its structure or causing issues during parsing.</p>
<h2>Understanding JSON and Its Limitations</h2>
<p>JSON is designed to be a minimal and straightforward way to represent structured data. Its simplicity is one of its strengths, but it also means there are some limitations. Unlike other data formats such as XML or YAML, JSON does not support comments. This is because JSON is primarily intended to be a data format, not a document format.</p>
<p>The official JSON specification (RFC 8259) makes it clear that comments are not part of the format. However, developers often find comments useful for documentation, debugging, or simply to make the data more understandable.</p>
<h2><strong>Why JSON Doesn’t Support Comments</strong></h2>
<ul>
<li>
<p>Short history: Douglas Crockford excluded comments to keep JSON minimal.</p>
</li>
<li>
<p>Strict parsers (<strong>Python json</strong>, <strong>Go</strong>, <strong>Java</strong>) will not work if you add comments.</p>
</li>
<li>
<p>Some of the derivative formats (<strong>JSON5</strong>, <strong>HJSON</strong>) support comments, but these are not standard.</p>
</li>
</ul>
<h2>Workarounds to Add Comments in JSON</h2>
<p>Although JSON doesn&#8217;t support comments, there are several ways you can include comments in your JSON files without breaking them. Here are some common techniques:</p>
<h3>1. Using a &quot;comments&quot; Key</h3>
<p>One straightforward method is to include comments as part of the JSON data by using a dedicated key, such as <code>_comment</code> or <code>__note</code>. This key will hold the comment string.</p>
<pre><code>bash
{
  &quot;name&quot;: &quot;John Doe&quot;,
  &quot;age&quot;: 30,
  &quot;_comment&quot;: &quot;This is a comment about the user object&quot;,
  &quot;email&quot;: &quot;john.doe@example.com&quot;
}</code></pre>
<p>This method is simple and keeps the comment close to the relevant data. However, be mindful that any JSON parser or application processing this file should be aware of and ignore these keys.</p>
<h2>2. Using Non-standard JSON Parsers</h2>
<p>Some JSON parsers and libraries extend the standard JSON format to support comments. For example, libraries like <code>JSON5</code> and <code>Hjson</code> allow comments and then convert the extended JSON to standard JSON.</p>
<ul>
<li>
<p><strong>JSON5</strong>: Allows comments similar to JavaScript (<code>//</code> and <code>/* */</code>).</p>
<pre><code>bash
// This is a comment
{
  "name": "John Doe", /* Inline comment */
  "age": 30,
  "email": "john.doe@example.com"
}</code></pre>
</li>
<li>
<p><strong>Hjson</strong>: A more human-readable version of JSON that supports comments.</p>
<pre><code class="language-bash">{
  # This is a comment
  name: "John Doe", # Inline comment
  age: 30,
  email: "john.doe@example.com"
}</code></pre>
</li>
</ul>
<p>Using these libraries can make your JSON files more readable and maintainable, but remember they are not universally supported and require specific parsers.</p>
<h3>3. Including Comments in External Documentation</h3>
<p>Another approach is to keep the JSON clean and free of comments by maintaining external documentation. This could be in the form of a README file, markdown documents, or even inline comments in the code that generates or processes the JSON.</p>
<p>For example, if you have a JSON configuration file, you could document its structure and each field&#8217;s purpose in a separate README.md file:</p>
<pre><code>bash
# Configuration File Documentation
## Fields

- `name`: The name of the user.
- `age`: The age of the user.
- `email`: The user&#039;s email address.</code></pre>
<p>This method ensures your JSON remains standard-compliant while still providing the necessary documentation.</p>
<h3>4. Embedding Comments in Strings</h3>
<p>In some cases, developers embed comments directly within string values. This is not a clean solution, but it can work for small notes.</p>
<pre><code>bash
{
  &quot;name&quot;: &quot;John Doe&quot;,
  &quot;age&quot;: 30,
  &quot;email&quot;: &quot;john.doe@example.com&quot;,
  &quot;metadata&quot;: &quot;This is a comment about the user object&quot;
}</code></pre>
<p>Be cautious with this approach, as it can make your data harder to use programmatically and may confuse other developers.</p>
<h2>Comparison of Methods</h2>
<table>
<thead>
<tr>
<th>Method</th>
<th>Compatibility</th>
<th>Pros</th>
<th>Cons</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>_comment</code> key</td>
<td>Universal</td>
<td>Simple, standard JSON</td>
<td>Pollutes data</td>
</tr>
<tr>
<td>Separate docs/schema</td>
<td>Universal</td>
<td>Clean JSON, scalable</td>
<td>Two files to maintain</td>
</tr>
<tr>
<td>JSON5 / CommentJSON</td>
<td>Limited</td>
<td>Real comments, readable</td>
<td>Not spec-compliant</td>
</tr>
<tr>
<td>Preprocess (strip)</td>
<td>Limited</td>
<td>Flexible, dev-friendly</td>
<td>Adds complexity</td>
</tr>
</tbody>
</table>
<h3>Common Mistakes and Recommendations</h3>
<ol>
<li>
<p><strong>Avoid adding comments directly by // or /* */ as they</strong> fail on strict parsers.</p>
</li>
<li>
<p><strong>Keep comments concise and relevant</strong> → extended explanations shouldn&#8217;t be in the codebase and can belong in documentation.</p>
</li>
<li>
<p><strong>If the project is API-facing</strong> → consider avoiding comments altogether and just keep pure JSON as the format.</p>
</li>
<li>
<p><strong>If you have config files in dev tools</strong> → prefer based on JSON5 or a preprocessing step.</p>
</li>
<li>
<p><strong>Security note:</strong> Preprocessing libraries should be trusted to prevent injection attacks.</p>
</li>
</ol>
<h2>Conclusion</h2>
<p>While JSON&#8217;s lack of native comment support can be a drawback, there are several strategies you can employ to include comments in your JSON files. Each method has its pros and cons, and the best choice depends on your specific use case and the tools you&#8217;re using. Whether you choose to use a dedicated key, non-standard parsers, external documentation, or embedded strings, it&#8217;s important to ensure that your comments do not interfere with the functionality of your JSON data.</p>
<p>By following these tips, you can keep your JSON files informative and maintainable, making them easier for yourself and others to understand and work with.</p>
<h2>FAQs</h2>
<h3><strong>1. Why doesn&#8217;t JSON support comments?</strong></h3>
<p>JSON was designed to be a lightweight data interchange format with simplicity in mind. Comments are not included in the JSON specification (RFC 8259) because the focus is purely on data representation rather than documentation or annotation. This decision ensures that JSON remains simple and efficient for parsing and processing.</p>
<h3><strong>2. Can using a &quot;comments&quot; key cause issues with JSON parsing?</strong></h3>
<p>Using a &quot;comments&quot; key like <code>_comment</code> does not break JSON parsing, as it is just another key-value pair. However, it&#8217;s important to ensure that any application or parser processing your JSON file is designed to ignore or handle these comment keys appropriately. Otherwise, they might be treated as regular data, potentially causing confusion or errors.</p>
<h3>3. Can I use <code>//</code> or <code>/* */</code> comments in JSON?</h3>
<p>No. Standard JSON parsers will raise an error to this syntax. Only extended formats like JSON5 or HJSON will allow this syntax.</p>
<h3>4.Are comments in JSON a good practice?</h3>
<p>In general, no, particularly in the case of APIs. For configurations, you can include limited comments to help developers, but if you are looking to include heavy comments, then documentation as an external document or using JSON alternatives may be the best format.</p>

         
        
                    

                    
                    <div class="pp-multiple-authors-boxes-wrapper pp-multiple-authors-wrapper pp-multiple-authors-layout-boxed multiple-authors-target-the-content box-post-id-16 box-instance-id-1 ppma_boxes_16"
                    data-post_id="16"
                    data-instance_id="1"
                    data-additional_class="pp-multiple-authors-layout-boxed.multiple-authors-target-the-content"
                    data-original_class="pp-multiple-authors-boxes-wrapper pp-multiple-authors-wrapper box-post-id-16 box-instance-id-1">
                                                                                    <h2 class="widget-title box-header-title">Author</h2>
                                                                            <span class="ppma-layout-prefix"></span>
                        <div class="ppma-author-category-wrap">
                                                                                                <span class="ppma-category-group ppma-category-group-">
                                                                                                                        <ul class="pp-multiple-authors-boxes-ul">
                                                                                                                                                                                                                                                                                                                                                                                                                    <li class="pp-multiple-authors-boxes-li author_index_0 author_animesh has-avatar">
                                                                                                                                                                                                                                            <div class="pp-author-boxes-avatar">
                                                                                                                                            <img alt='Keploy Team' src='https://wp.keploy.io/wp-content/uploads/2025/06/f5085c8a-4822-4df4-9354-51edebf1-e1749103444201.webp' srcset='https://wp.keploy.io/wp-content/uploads/2025/06/f5085c8a-4822-4df4-9354-51edebf1-e1749103444201.webp' class='multiple_authors_guest_author_avatar avatar' height='80' width='80'/>                                                                                                                                    </div>
                                                            
                                                            <div class="pp-author-boxes-avatar-details">
                                                                                                                                                                                                <div class="pp-author-boxes-name multiple-authors-name">
                                                                        <a href="https://wp.keploy.io/author/animesh/" rel="author" title="Keploy Team" class="author url fn">Keploy Team</a> 
                                                                    </div>
                                                                                                                                                                                                                                                                    <p class="pp-author-boxes-description multiple-authors-description">
                                                                        Keploy is developer-centric API testing tool that creates tests along with built-in-mocks, faster than unit tests.

Keploy not only records API calls, but also records database calls and replays them during testing, making it easy to use, powerful, and extensible.                                                                    </p>
                                                                                                                                
                                                                                                                                
                                                                                                                            </div>
                                                                                                                                                                                                                                                                                                                                                                                                             </li>
                                                                                                                                                                                                                                    </ul>
                                                                            </span>
                                                                                    </div>
                    <span class="ppma-layout-suffix"></span>
                    </div>
                    
                    
                
                                <style>
                .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-avatar img { width: 80px !important; height: 80px !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-avatar img { border-style: none !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-avatar img { border-radius: 50% !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-meta a { background-color: #655997 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-meta a { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-meta a:hover { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_email-profile-data { background-color: #655997 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_email-profile-data { border-radius: 100% !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_email-profile-data { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_url-profile-data { background-color: #655997 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_url-profile-data { border-radius: 100% !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .ppma-author-user_url-profile-data { color: #ffffff !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-author-boxes-recent-posts-title { border-bottom-style: dotted !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { border-style: solid !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { border-width: 1px !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { border-color: #999 !important; } .pp-multiple-authors-boxes-wrapper.box-post-id-16.pp-multiple-authors-layout-boxed.multiple-authors-target-the-content.box-instance-id-1 .pp-multiple-authors-boxes-li { color: #3c434a !important; }             </style>

Learn to add comments to JSON

Bug Bashing: How to Run a High-Impact Testing Blitz

API-First Development: The Complete Guide

Types of Regression Testing in Software Testing Explained

REST API Testing: Strategy, Automation & Best Practices

Agile vs Waterfall: Choosing the Right Approach for Your Project

4 Phases of Rapid Application Development: A Complete Guide

SOAP UI vs Postman for API Testing: Which Should You Use?

Building Keploy.io, an EBPF based open source framework to generate test cases and data stubs from API calls.

Neha Gupta

Cloud technology veteran and probably the youngest (globally) to have completed all 5 AWS certifications (including Solutions architect Professional and Dev­ops engineer professional)

Learn To Add Comments To Json

More Stories