In some cases, API modules need to return 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 directly, e.g. `$result->addValue( null, 'graph', $jsonData )`, the api's `format=json` will manipulate the result, sometimes causing complicated bugs (T120227). Even though sanitization could be partially solved with `formatversion=2`, for non-JSON formats like `format=xml`, the results are still 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.
```
{
"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 to a string. This will prevent 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>
```