Abstract

Provide a builder/slurper combination for handling data in JSON format in a similar fashion as it's already done for XML.

Rationale

JSON has become ubiquitous to the web. RESTful services exchange data in both POX (Plain Old XML) and JSON formats. Groovy has excellent support for producing/consuming XML with MarkupBuilder, XmlSlurper and XmlParser but lacks this kind support for JSON. This GEP strives to remedy the situation, by providing a compatible builder approach.

Producing JSON

The following builder syntax is proposed

Valid node values are: Number, String, GString, Boolean, Map, List. null is reserved for object references. Arrays can not be null but they can be empty. Anything else results in an IAE (or a more specialized exception) being thrown.

Special cases

There is a special case to be considered: when the top node results in an anonymous object or array. For objects a call() method on the builder is needed which takes a map as argument, for arrays call() takes a vararg of values. Here are some examples:

When a method is called on the builder without arguments, and empty JSON object is associated with the key:

You can also pass a map and a closure argument:

Calls like the following, with a map and a value, don't have any meaningful representation in JSON (unlike in XML), and triggers a JsonException:

In case of overlapping keys in the map and the closure, the closure wins – a visual clue for this rule is that the closure appears "after" the map key/value pairs.

Consuming JSON

The proposal is for the creation of a JsonSlurper class that can read JSON from a string (in a non-streaming fashion) and produce a hierarchy of maps and lists representing the JSON objects and arrays respectively.

JsonSlurper's API should mirror closely what XmlParser/XmlSlurper offers in terms of its parse* method variants.