This post starts a series of articles that give insight to the new
features of Jansson 2.0.

First up is
the json_unpack()
API. I think it's the most powerful new feature, allowing the user
to perform two things on a JSON value: data extraction, and
validation against a simple schema. The idea has been stolen from
Python's C API.

The format string passed to json_unpack()
describes the structure of the object. The s format
denotes an object key, and the f format means a real
number value. Whitespace, : and , are
ignored, so {sfsfsf} would be an equivalent format
string to the one above.

After the format string, there's one argument for each
format character. For object keys, a string specifies what key is
accessed, and for real numbers, a pointer to double gives an address
where to store the value.

The equivalent code without json_unpack() would be
something like this:

This time, the format string has two nested objects and a nested
array. There's no limit on the nesting levels. The variable
arguments are used in the "flat" order in which they appear in the
format string.

The same API can also be used in a validation-only mode, i.e.
without extracting any values. Error messages are also available:

/* Assume the same JSON object as in the previous example */json_t*nested;json_error_terror;if(json_unpack_ex(nested,&error,JSON_VALIDATE_ONLY,"{s:{s:[iii]}}","foo","bar")){fprintf(stderr,"Error: %d:%d: %s\n",error.line,error.column,error.text);return-1;}

The json_unpack_ex() function is the extended version
of json_unpack(). It takes an error parameter, similar
to decoding functions, and optional flags to control the behaviour.
The JSON_VALIDATE_ONLY flags tells it to only validate
and not to extract anything. Extra arguments after the format sting
are only required for object keys. The available validation is quite
simple, only the object/array structure and value types can be
checked, but usually this saves a lot of code.

I strongly believe that this feature, along with
the json_pack() API described in the next part, will
make it an order of magnitude more pleasant to manipulate JSON data
in C. Many thanks to Graeme Smecher for suggesting
this and providing the initial implementation.

This article only gave a few examples. For full details, all
available format characters and flags, see
the documentation.