Home

Awesome

JSONKit

JSONKit is dual licensed under either the terms of the BSD License, or alternatively under the terms of the Apache License, Version 2.0.<br /> Copyright © 2011, John Engelhart.

A Very High Performance Objective-C JSON Library

UPDATE: (2011/12/18) The benchmarks below were performed before Apples NSJSONSerialization was available (as of Mac OS X 10.7 and iOS 5). The obvious question is: Which is faster, NSJSONSerialization or JSONKit? According to this site, JSONKit is faster than NSJSONSerialization. Some quick "back of the envelope" calculations using the numbers reported, JSONKit appears to be approximately 25% to 40% faster than NSJSONSerialization, which is pretty significant.

ParsingSerializing
<img src="http://chart.googleapis.com/chart?chf=a,s,000000%7Cb0,lg,0,6589C760,0,6589C7B4,1%7Cbg,lg,90,EFEFEF,0,F8F8F8,1&chxl=0:%7CTouchJSON%7CXML+.plist%7Cjson-framework%7CYAJL-ObjC%7Cgzip+JSONKit%7CBinary+.plist%7CJSONKit%7C2:%7CTime+to+Deserialize+in+%C2%B5sec&chxp=2,40&chxr=0,0,5%7C1,0,3250&chxs=0,676767,11.5,1,lt,676767&chxt=y,x,x&chbh=a,5,4&chs=350x185&cht=bhs&chco=6589C783&chds=0,3250&chd=t:410.517,510.262,539.614,1351.257,1683.346,1747.953,2955.881&chg=-1,0,1,3&chm=N+*s*+%C2%B5s,676767,0,0:5,10.5%7CN+*s*+%C2%B5s,3d3d3d,0,6,10.5,,r:-5:1&chem=y;s=text_outline;d=666,10.5,l,fff,_,Decompress+%2b+Parse+is+just;ds=0;dp=2;py=0;of=58,7%7Cy;s=text_outline;d=666,10.5,l,fff,_,5.6%25+slower+than+Binary+.plist%21;ds=0;dp=2;py=0;of=53,-5" width="350" height="185" alt="Deserialize from JSON" /><img src="http://chart.googleapis.com/chart?chf=a,s,000000%7Cb0,lg,0,699E7260,0,699E72B4,1%7Cbg,lg,90,EFEFEF,0,F8F8F8,1&chxl=0:%7CTouchJSON%7CYAJL-ObjC%7CXML+.plist%7Cjson-framework%7CBinary+.plist%7Cgzip+JSONKit%7CJSONKit%7C2:%7CTime+to+Serialize+in+%C2%B5sec&chxp=2,40&chxr=0,0,5%7C1,0,3250&chxs=0,676767,11.5,1,lt,676767&chxt=y,x,x&chbh=a,5,4&chs=350x175&cht=bhs&chco=699E7284&chds=0,3250&chd=t:96.387,466.947,626.153,1028.432,1945.511,2156.978,3051.976&chg=-1,0,1,3&chm=N+*s*+%C2%B5s,676767,0,0:5,10.5%7CN+*s*+%C2%B5s,4d4d4d,0,6,10.5,,r:-5:1&chem=y;s=text_outline;d=666,10.5,l,fff,_,Serialize+%2b+Compress+is+34%25;ds=0;dp=1;py=0;of=51,7%7Cy;s=text_outline;d=666,10.5,l,fff,_,faster+than+Binary+.plist%21;ds=0;dp=1;py=0;of=62,-5" width="350" height="185" alt="Serialize to JSON" />
23% Faster than Binary <code><em>.plist</em></code> !549% Faster than Binary <code><em>.plist</em></code> !

JSON versus PLIST, the Ultimate Showdown benchmarks the common JSON libraries and compares them to Apples .plist format.


JavaScript Object Notation, or JSON, is a lightweight, text-based, serialization format for structured data that is used by many web-based services and API's. It is defined by RFC 4627.

JSON provides the following primitive types:

These primitive types are mapped to the following Objective-C Foundation classes:

JSONObjective-C
nullNSNull
true and falseNSNumber
NumberNSNumber
StringNSString
ArrayNSArray
ObjectNSDictionary

JSONKit uses Core Foundation internally, and it is assumed that Core Foundation ≡ Foundation for every equivalent base type, i.e. CFStringNSString.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

JSON To Objective-C Primitive Mapping Details

Objective-C To JSON Primitive Mapping Details

Reporting Bugs

Please use the github.com JSONKit Issue Tracker to report bugs.

The author requests that you do not file a bug report with JSONKit regarding problems reported by the clang static analyzer unless you first manually verify that it is an actual, bona-fide problem with JSONKit and, if appropriate, is not "legal" C code as defined by the C99 language specification. If the clang static analyzer is reporting a problem with JSONKit that is not an actual, bona-fide problem and is perfectly legal code as defined by the C99 language specification, then the appropriate place to file a bug report or complaint is with the developers of the clang static analyzer.

Important Details

Tips for speed

Parsing Interface

JSONDecoder Interface

The <code>objectWith…</code> methods return immutable collection objects and their respective <code>mutableObjectWith…</code> methods return mutable collection objects.

Note: The bytes contained in a NSData object MUST be UTF8 encoded.

Important: Methods will raise NSInvalidArgumentException if parseOptionFlags is not valid.
Important: objectWithUTF8String: and mutableObjectWithUTF8String: will raise NSInvalidArgumentException if string is NULL.
Important: objectWithData: and mutableObjectWithData: will raise NSInvalidArgumentException if jsonData is NULL.

+ (id)decoder;
+ (id)decoderWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)initWithParseOptions:(JKParseOptionFlags)parseOptionFlags;

- (void)clearCache;

- (id)objectWithUTF8String:(const unsigned char *)string length:(size_t)length;
- (id)objectWithUTF8String:(const unsigned char *)string length:(size_t)length error:(NSError **)error;
- (id)mutableObjectWithUTF8String:(const unsigned char *)string length:(size_t)length;
- (id)mutableObjectWithUTF8String:(const unsigned char *)string length:(size_t)length error:(NSError **)error;

- (id)objectWithData:(NSData *)jsonData;
- (id)objectWithData:(NSData *)jsonData error:(NSError **)error;
- (id)mutableObjectWithData:(NSData *)jsonData;
- (id)mutableObjectWithData:(NSData *)jsonData error:(NSError **)error;

NSString Interface

- (id)objectFromJSONString;
- (id)objectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)objectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;
- (id)mutableObjectFromJSONString;
- (id)mutableObjectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)mutableObjectFromJSONStringWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;

NSData Interface

- (id)objectFromJSONData;
- (id)objectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)objectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;
- (id)mutableObjectFromJSONData;
- (id)mutableObjectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags;
- (id)mutableObjectFromJSONDataWithParseOptions:(JKParseOptionFlags)parseOptionFlags error:(NSError **)error;

JKParseOptionFlags

<table> <tr><th>Parsing Option</th><th>Description</th></tr> <tr><td valign="top"><code>JKParseOptionNone</code></td><td>This is the default if no other other parse option flags are specified, and the option used when a convenience method does not provide an argument for explicitly specifying the parse options to use. Synonymous with <code>JKParseOptionStrict</code>.</td></tr> <tr><td valign="top"><code>JKParseOptionStrict</code></td><td>The JSON will be parsed in strict accordance with the <a href="http://tools.ietf.org/html/rfc4627">RFC 4627</a> specification.</td></tr> <tr><td valign="top"><code>JKParseOptionComments</code></td><td>Allow C style <code>//</code> and <code>/* &hellip; */</code> comments in JSON. This is a fairly common extension to JSON, but JSON that contains C style comments is not strictly conforming JSON.</td></tr> <tr><td valign="top"><code>JKParseOptionUnicodeNewlines</code></td><td>Allow Unicode recommended <code>(?:\r\n|[\n\v\f\r\x85\p{Zl}\p{Zp}])</code> newlines in JSON. The <a href="http://tools.ietf.org/html/rfc4627">JSON specification</a> only allows the newline characters <code>\r</code> and <code>\n</code>, but this option allows JSON that contains the <a href="http://en.wikipedia.org/wiki/Newline#Unicode">Unicode recommended newline characters</a> to be parsed. JSON that contains these additional newline characters is not strictly conforming JSON.</td></tr> <tr><td valign="top"><code>JKParseOptionLooseUnicode</code></td><td>Normally the decoder will stop with an error at any malformed Unicode. This option allows JSON with malformed Unicode to be parsed without reporting an error. Any malformed Unicode is replaced with <code>\uFFFD</code>, or <code>REPLACEMENT CHARACTER</code>, as specified in <a href="http://www.unicode.org/versions/Unicode6.0.0/ch03.pdf">The Unicode 6.0 standard, Chapter 3</a>, section 3.9 <em>Unicode Encoding Forms</em>.</td></tr> <tr><td valign="top"><code>JKParseOptionPermitTextAfterValidJSON</code></td><td>Normally, <code>non-white-space</code> that follows the JSON is interpreted as a parsing failure. This option allows for any trailing <code>non-white-space</code> to be ignored and not cause a parsing error.</td></tr> </table>

Serializing Interface

The serializing interface includes NSString convenience methods for those that need to serialize a single NSString. For those that need this functionality, the NSString additions are much more convenient than having to wrap a single NSString in a NSArray, which then requires stripping the unneeded [] characters from the serialized JSON result. When serializing a single NSString, you can control whether or not the serialized JSON result is surrounded by quotation marks using the includeQuotes: argument:

ExampleResultArgument
a "test"..."a \"test\"..."includeQuotes:YES
a "test"...a \"test\"...includeQuotes:NO

Note: The NSString methods that do not include a includeQuotes: argument behave as if invoked with includeQuotes:YES.
Note: The bytes contained in the returned NSData object are UTF8 encoded.

NSArray and NSDictionary Interface

- (NSData *)JSONData;
- (NSData *)JSONDataWithOptions:(JKSerializeOptionFlags)serializeOptions error:(NSError **)error;
- (NSString *)JSONString;
- (NSString *)JSONStringWithOptions:(JKSerializeOptionFlags)serializeOptions error:(NSError **)error;

NSString Interface

- (NSData *)JSONData;
- (NSData *)JSONDataWithOptions:(JKSerializeOptionFlags)serializeOptions includeQuotes:(BOOL)includeQuotes error:(NSError **)error;
- (NSString *)JSONString;
- (NSString *)JSONStringWithOptions:(JKSerializeOptionFlags)serializeOptions includeQuotes:(BOOL)includeQuotes error:(NSError **)error;

JKSerializeOptionFlags

<table> <tr><th>Serializing Option</th><th>Description</th></tr> <tr><td valign="top"><code>JKSerializeOptionNone</code></td><td>This is the default if no other other serialize option flags are specified, and the option used when a convenience method does not provide an argument for explicitly specifying the serialize options to use.</td></tr> <tr><td valign="top"><code>JKSerializeOptionPretty</code></td><td>Normally the serialized JSON does not include any unnecessary <code>white-space</code>. While this form is the most compact, the lack of any <code>white-space</code> means that it's something only another JSON parser could love. Enabling this option causes JSONKit to add additional <code>white-space</code> that makes it easier for people to read. Other than the extra <code>white-space</code>, the serialized JSON is identical to the JSON that would have been produced had this option not been enabled.</td></tr> <tr><td valign="top"><code>JKSerializeOptionEscapeUnicode</code></td><td>When JSONKit encounters Unicode characters in <a href="http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSString_Class/index.html"><code>NSString</code></a> objects, the default behavior is to encode those Unicode characters as <code>UTF8</code>. This option causes JSONKit to encode those characters as <code>\u<i>XXXX</i></code>. For example,<br/><code>["w&isin;L&#10234;y(&#8739;y&#8739;&le;&#8739;w&#8739;)"]</code><br/>becomes:<br/><code>["w\u2208L\u27fa\u2203y(\u2223y\u2223\u2264\u2223w\u2223)"]</code></td></tr> <tr><td valign="top"><code>JKSerializeOptionEscapeForwardSlashes</code></td><td>According to the <a href="http://tools.ietf.org/html/rfc4627">JSON specification</a>, the <code>/</code> (<code>U+002F</code>) character may be backslash escaped (i.e., <code>\/</code>), but it is not required. The default behavior of JSONKit is to <b><i>not</i></b> backslash escape the <code>/</code> character. Unfortunately, it was found some real world implementations of the <a href="http://weblogs.asp.net/bleroy/archive/2008/01/18/dates-and-json.aspx">ASP.NET Date Format</a> require the date to be <i>strictly</i> encoded as <code>\/Date(...)\/</code>, and the only way to achieve this is through the use of <code>JKSerializeOptionEscapeForwardSlashes</code>. See <a href="https://github.com/johnezang/JSONKit/issues/21">github issue #21</a> for more information.</td></tr> </table>