JSON and API these two terms are really popular nowadays and a vast range of developers are dealing with it daily. JSON seems to be an ideal way to describe data in form of object. However, the last time I was working with a large JSON file I wanted to add some comments to it. I have tried several ways to accomplish the task and in this article we will add comments in JSON with NodeJS, JavaScript, Python and Go.

JSON does not support comments and everything we write inside a JSON is considered as data only. In the early days it had supported comments but later it was removed due to interoperability. However we can always find alternates when we are the one who will format the data and parse it in our application.

Add comments in JSON

The very basic thing that we can do to add comment is to use a designated data element like "__comment" as JSON attribute. When we will parse it in our application we can filter it or structure our application in such a way.

Suppose we have the following JSON file caller user.json

{
    "name": "John",
    "age": 24,
    "profession": "Software Developer"
}

Then we can add comments in JSON as follows

{
    "__comment": "Comment here",
    "name": "John",
    "age": 24,
    "profession": "Software Developer"
}

Now the user.json object has 4 attributes and it will not differentiate between the comment and other attributes. We need to filter it manually depending on our use case.

Add comments in JSON with JavaScript or NodeJS

NodeJS is based on JavaScript so we can do the task in similar way. Suppose you are creating a fruit object and want to convert it to JSON and parse it later.

const fruit = {
   "_comment": "Comment here...",
   "name": "Mango",
   "price": 10
}
const jsonData = JSON.stringify(fruit)
console.log(jsonData) // {"_comment":"Comment here...","name":"Mango","price":10}

You can see from the above data that the JSON data cant differentiate between our designated data element and regular ones. Lets try to parse teh data and check the output.

console.log(JSON.parse(jsonData)) // { _comment: 'Comment here...', name: 'Mango', price: 10 }

So we can parse the JSON data as usual and can access the comment as var['__comment'].

Add comments in JSON with 3rd party libraries

Hjson, a user interface for JSON

Hjson is a pretty amazing tool to not only add comments to a JSON file but also to use JSON without worrying about commas and quotes.

It supports single line as well as multi line comments in JSON.

{
    // use #, // or /**/ comments,
    // omit quotes for keys
    key: 1
    // omit quotes for strings
    contains: everything on this line
    // omit commas at the end of a line
    cool: {
        foo: 1
        bar: 2
    }
    // allow trailing commas
    list: [
        1,
        2,
    ]
    // and use multiline strings
    realist:
        '''
        My half empty glass,
        I will fill your empty half.
        Now you are half full.
        '''
}

JSON5 JSON for humans

JSON5 is another promising tool that lets you add comments to JSON file. Here is a quick example below. Follow their documentation to dive deep into the ocean of JSON5.

{
    // comments
    unquoted: 'and you can quote me on that',
    singleQuotes: 'I can use "double quotes" here',
    lineBreaks: "Look, Mom! \
No \\n's!",
    hexadecimal: 0xdecaf,
    leadingDecimalPoint: .8675309, andTrailing: 8675309.,
    positiveSign: +1,
    trailingComma: 'in objects', andIn: ['arrays',],
    "backwardsCompatible": "with JSON",
}

Add comments in JSON with Python

Python has an inbuilt data type called Dictionary that is similar to JSON. So we can use JSON seamlessly in Python. Lets create a car dictionary.

car = {
    "brand": "Audi",
    "name": "Q8",
    "price": 68500
}

Now lets add comment to it with help of a designated key value pair and access it as follows.

car = {
    "__comment": "Comment here",
    "brand": "Audi",
    "name": "Q8",
    "price": 68500
}

print(car['__comment'])

Add comments in JSON with Go

Lets create a JSON for car with Go lang. Unlike Python or JS the Go version will be a little longer as we have to define struct and convert byte array to string. However Go does not support underscore at the beginning of a struct field so we need to use Comment instead of __comemnt.

package main 
   
import ( 
    "fmt"
    "encoding/json"
) 
   
// declaring a struct 
type Car struct{ 
    Name string 
    Brand string
    Price int 
    Comment string
} 

func main() { 
    car := Car{"320D", "BMW", 45000, "Comment here"} 
       
    // encoding the struct into json format 
    car_enc, err := json.Marshal(car) 
       
    if err != nil { 
        // if error is not nil print error 
        fmt.Println(err) 
    } 
       
    // convert byte array to string
    fmt.Println(string(car_enc)) // {"Name":"320D","Brand":"BMW","Price":45000,"Comment":"Comment here"}
}

Go support HJSON and JSON5 both.

So thats is all about JSON comments implementation with various programming languages. Hope it has helped you to understand the process of comments in JSON.