Purpose

Suppose that your application has a complex configuration and:

• that configuration is represented as a set of JSON files
• the files are supposed to be edited by the end-users
• the application on its own provides/dumps only a "default" set of files somehow annotating the dumped JSON makes much more sense than maintaining a separate documentation for the allowed values and expected keys, which will get out of date on the nearest occasion.

As per the original JSON's RFC comments are not allowed in JSON. But, knowing that the world is not ideal, nlohmann's JSON library does support parsing JSON files with so-called "comments", encoded as follows:

{
  /* this is a comment */
  "property_1": 5
}

A specific overload of the parse method has to be called, as per this part of the reference:

json j = json::parse(s,
                     /* callback */ nullptr,
                     /* allow exceptions */ true,
                     /* ignore_comments */ true);

(so, more specifically, the library allows ignoring them)

However, the library does not allow for annotating (adding the comments) when serializing your custom classes or structures. Best you could possibly do is post-process the dumped string or file through raw string processing, which is error-prone and problematic.

This fork of the nlohmann's JSON library adds a possibility to add annotations (known at compile-time) to your classes and structures. I'll try to keep the fork up to date with the original repository, potentially "shadowing" the releases in the future as well¹.

How to use

Currently, the extension applies exclusively² to NLOHMANN_DEFINE_TYPE_INTRUSIVE macro:

class ExampleClass {
private:
    int property1{1};
    double property2{2.5};
    std::string property3{"test"};
    std::map<std::string, int> property4{{"x", 1}, {"y", 2}};
    std::vector<double> property5{1.5, 5.4, 3.2};
public:
    ExampleClass() = default;

    NLOHMANN_DEFINE_TYPE_INTRUSIVE_ANNOTATED(ExampleClass, property1, "comment两两", 
                                                           property2, "multiline\ncomment2", 
                                                           property3, "comment3",
                                                           property4, "comment4",
                                                           property5, "comment5");
};

Dumping is as simple as that:

int main() {
    ExampleClass ec;
    std::ofstream example_file;
    example_file.open("example_1.json");

    nlohmann::json j = ec;
    example_file << j.dump_annotated<ExampleClass>(4) << std::endl;
    // instead of the original:
    // example_file << j.dump(4) << std::endl;

    return 0;
}

---

1. Tried creating a pull request in the original repository, but I doubt it's ever going to be considered. ↩︎

2. If you look closely at the new macro, it's relatively easy to figure out how to actually avoid using the macro, but I need to document that to make it officially supported. ↩︎