As we use more and more JSON data, in some cases API modules need to return that JSON data **as is**, without any modifications. For example, `action=graph` could return the graph data in Vega format, or another module could get the template parameters exactly as written in a template's JSON parameters block.
If api module adds JSON data to the result directly, e.g. `$result->addValue( null, 'graph', $jsonData )`, the api's `format=json` will manipulate the result, deleting boolean values, and sometimes causing complicated bugs (T120227). Even though boolean sanitization could be partially solved with `formatversion=2`, there might still other unexpected result manipulations, causing obscure bugs. Also, for the non-JSON formats like `format=xml`, the result is mostly useless.
==== Current workaround
One option is to convert JSON to a string, but this will cause substantial increase in result size (all `"` need to be escaped as `\"`), and require additional JSON decoding on the client, complicating client code:
```
{
"graph": "{ \"some\":\"data\", \"in\":\"json\", \"bool\": false }"
}
```
==== Proposal
I propose that we introduce a new "JSON" value type:
```
$result->addValue( null, 'graph', $jsonData, ApiResult::FLAG_JSON );
```
Values added with this flag will be outputted **as-is** by the JSON formatter.
```
{
"graph": { "some":"data", "in":"json", "bool": false }
}
```
For XML and other formats, the value will be automatically converted into a string. This will make JSON usage much easier on the JSON-aware clients, while still allowing other formats to function correctly.
```
<api>
<graph>
{ "some":"data", "in":"json", "bool": false }
</graph>
</api>
```