The Windows Runtime provides types in the Windows.Data.Json namespace for dealing with JSON. You can parse a JSON string into a JSON object model, and you can conversely build a JSON object model and then convert it back to a string.

Here are some of my opinionated notes on these classes.

In order to be language-independent, the objects in the Windows.Data.Json namespace are COM objects, rather than native objects in C++, C#, or whatever your language is. This means that calls to the methods go through vtable dispatch, which the compiler cannot optimize. This is a fundamental limitation of using a language-independent object model: You cannot take advantage of language-specific optimizations.

There are a lot of interfaces, and calling a method on an interface different from the one you have in your hand requires you do perform a QueryInterface to switch to the interface that has the method.

// C++/WinRT
JsonObject jsonObject = ...;
jsonObject.Insert(key, value);

Insert is a method on IMap<String, IJsonValue>, so under the covers, there is an interface query.

IMap<hstring, IJsonValue> map;
jsonObject.QueryInterface(IID_PPV_ARGS(map.put()));
map.Insert(key, value);
// map calls Release() on destruction

The above code could have avoided two COM calls (the Query­Interface and the Release) by using the bespoke Set­Named­Value method.

// C++/WinRT
JsonObject jsonObject = ...;
jsonObject.SetNamedValue(key, value);

The SetNamedValue method is a method on IJsonObject, so you can call it without having to change interfaces.

The JsonObject is awkward to use in an exception-free manner. In order to read a value if it is present, most people write something like

if (jsonObject.HasKey(L"name")) {
    auto value = jsonObject.GetNamedValue(L"name");
    if (value.ValueType() == JsonValueType::String) {
        auto name = value.GetString();
    }
}

This is a double-query, which is made even more expensive when you realize that HasKey is a method on IMap, so you also have an interface query/release hiding in there.

There’s a little-known overload of GetNamedValue that lets you specify what to return if the value isn’t found:

auto value = jsonObject.GetNamedValue(L"name", nullptr);
if (value && value.ValueType() == JsonValueType::String) {
    auto name = value.GetString();
}

Since a present named value never has a nullptr value, we can be confident that if nullptr is returned, then it means that the value was not present. (If the associated value is a JSON null, it is returned as a non-null object whose value type is JsonValueType::Null.)

There’s a corresponding little-known overload of GetNamedString that returns the string, or a fallback value if the string is not present.

auto name = jsonObject.GetNamedString(L"name", L"untitled");

Choosing a fallback value for a missing string is trickier because there is no out-of-band value that unmistakably indicates that the fallback was returned. (Recall that a nullptr HSTRING represents the empty string.) The Get­Named­Boolean function suffers from the same problem. For Get­Named­Value and Get­Named­Array, you can use nullptr, and for Get­Named­Number you can use NaN or one of the Infinity values, since those are not legal in JSON.

There’s still a hidden trap in the Get­Named­... functions with fallback: If the value is present but is not the type you expect, then instead of returning the fallback, you get an E_ILLEGAL_METHOD_CALL error, which usually projects as an exception. This is a problem if you’re trying to be exception-free yet resilient to JSON that doesn’t match your schema. I think the best you can do is Get­Named­Value and then check the Value­Type before converting.

The JSON parsing and serialization methods are not configurable. Although there is a JSON specification, there is wide disagreement over what is legal JSON when you get to the edges of the specification. I’ve put a conformance report at the end of this article.

One thing that stands out from the conformance report is that the TryParse method can throw an exception if the JSON string is legal but not representable as a JsonValue object, or if an implementation limit is reached before the string can be fully validated. So even though you think you’re avoiding exceptions by using JsonValue::TryParse, you aren’t actually exception-free.

Anyway, back to lack of configurability: Since you cannot configure the input, you cannot specify which variant of JSON you want to accept. And since you cannot configure the output, you cannot ask for pretty-printing. This makes the Windows.Data.Json objects unsuitable for generating JSON configuration files which are intended to be human-edited.

Note also that the Windows.Data.Json interconversion functions consume and produce UTF-16LE strings. Most of the time, the original JSON data in UTF-8 format, and the final output is also in UTF-8 format, so you have extra conversion steps on either side. Of course, this isn’t a problem if your I/O functions already do that conversion for you. For example, if you ask HttpClient for the string content, it returns the string in UTF16-LE format, ready to be handed to JsonValue::TryParse.

With all of these caveats, it sure sounds like the Windows.Data.Json namespace is terrible. Why would you ever want to use it?

Well, it’s already there.

If you already require Windows 8 or higher, then these classes are already present, and you can consume them without having to add another dependency to your project. This is important if you are concerned about disk footprint or download size, or just want to minimize your dependencies. For example, I have a few internal tools in which the program itself is 60KB, but the dependencies to do the Web authentication are 300KB.

Also, if parsing JSON is not a performance-critical operation in your program, you may figure that the inefficiencies of a language-independent library (compared to a native-language library) aren’t really a big deal. For example, if your program is parsing moderate-sized JSON received from a Web server, any time savings by switching to a highly-optimized JSON parser is almost certainly going to be overwhelmed by the network I/O.¹

Bonus chatter: The classes in the Windows.Data.Json namespace are provided by the Windows Runtime as a convenience. No other parts of the API surface require it.² Any methods that accept JSON do so in the form of a string, so you are welcome to use whatever JSON library you like.

Appendix: Here’s the JSON conformance report, generated from Nicolas Seriot’s JSON test suite.

For all of the “invalid codepoint” tests, the EFBFBD sequence is an encoded � U+FFFD REPLACEMENT CHARACTER.

The “raw invalid codepoint” tests are marked N/A because the failure is in the conversion from UTF-8 to UTF-16LE, which is something the caller does before calling JsonValue::TryParse.

¹ Though not always.

² The Windows.System.Diagnostics.Diagnostic­Invoker.Run­Diagnostic­Action­Async method does require that you use a Windows.Data.Json.JsonObject, but this was a mistake, which was corrected by the addition of the Windows.System.Diagnostics.Diagnostic­Invoker.Run­Diagnostic­Action­From­String­Async method, which accepts a plain string. You can generate that string using whatever JSON library you choose.