After a lot of work, we're ready to provide a more sensible data layout for format=json results (and also format=php). You can enable this in your requests by adding "&formatversion=2", but do note that the output formatting isn't entirely stable yet and might change without warning.
Without specifying formatversion=2, things should be backwards-compatible. But there are some caveats:
- Modules that were previously outputting raw booleans in JSON may now have those properties being output using the standard convention: empty-string for true and absent for false. Instances of this should be reported in Phabricator https://phabricator.wikimedia.org/ to be fixed, please tag with #MediaWiki-API https://phabricator.wikimedia.org/project/profile/200/ and the tag for the relevant extension. - format=xml will now reversibly mangle tag and attribute names that are not valid XML, instead of just outputting invalid XML. - Previously-announced breaking changes to log entry parameter formatting, that are not actually part of this general result formatting change but were made at about the same time.
With formatversion=2, we can make some useful changes:
- Return booleans as boolean true instead of empty-string. Where appropriate,[1] return boolean false instead of omitting the property. - Return empty objects in JSON as {}, rather than []. - Have action=query's "pages" be an array, instead of an object with page ids as keys that can be difficult to iterate. - Provide useful property names instead of '*'. - Eliminate useless indirection, e.g. {"text":"..."} instead of {"text":{"*":"..."}} and {"key1":"value1","key2":"value2"} instead of [{"name":"key1","*":"value1"},{"name":"key2","*":"value2"}].
If you see missed opportunities to make the above changes in existing formatversion=2 output, or if there are other changes that would make API output easier to use in JSON, please let me know! Phabricator https://phabricator.wikimedia.org/ would be ideal (tag with #MediaWiki-API https://phabricator.wikimedia.org/project/profile/200/, and the appropriate extension's tag if applicable), or reply on the mediawiki-api mailing list https://lists.wikimedia.org/mailman/listinfo/mediawiki-api.
Thanks.
[1]: Where the property is usually false, it's sometimes just bloat to include it.
On Fri, May 1, 2015 at 7:53 AM, Brad Jorsch (Anomie) bjorsch@wikimedia.org wrote:
With formatversion=2, we can make some useful changes:
- Return booleans as boolean true instead of empty-string. Where
appropriate,[1] return boolean false instead of omitting the property.
- Return empty objects in JSON as {}, rather than [].
- Have action=query's "pages" be an array, instead of an object with
page ids as keys that can be difficult to iterate.
- Provide useful property names instead of '*'.
- Eliminate useless indirection, e.g. {"text":"..."} instead of
{"text":{"*":"..."}} and {"key1":"value1","key2":"value2"} instead of [{"name":"key1","*":"value1"},{"name":"key2","*":"value2"}].
formatversion=2 looks great, Brad. Thanks for the improvements.
-Frances
mediawiki-api@lists.wikimedia.org