LicenseApache License, Version 2.0
Platformsios 7.0, requires ARC



  • 1.1.0 3/28/2014
  • Provide a second MONGO_DB Scheme
  • new protocol method so the delegate can translate ‘new Date’ strings into some common format
  • CocoaPods support (Podspec now in CocoaPods)

  • 1.0.0 2/26/2014 First Release


Parse JSON arrays as they download, convert each object to native using NSJSONSerialization, and return it to a delegate.

As you probably know, iOS does not provide a streaming JSON parser—you normally need to save all the data, and keep the user waiting, while you store, then process, data. Wouldn’t it be so much nicer to start showing the user the data in say a table, while its being downloaded?

Not only does this class facilitate downloading and converting JSON data, but it works with MongoDB style-JSON, where you have objectID and new date() objects, that cause NSJSONSerialization fits (ie, it won’t parse). What the class does is to extract the ID, replace the text with a simple string containing the ID, and overwrites extra bytes with spaces.

Likewise, new date() objects can be processed, and an ISO formatted date string generated to replace them. Note that in this code, all dates where of a single format. If your MongoDB repository has multiple formats, you will need to enhance the date processing, or just return the enclosed date stings, and process them later.

The process works by mallocing and reallocing memory until it has enough to hold the first object, and subsequently reallocs just enough memory to hold the current in-process object (plus any residual bytes in the last received packet). As each object is detected, the bytes are passed to NSJSONSerialization and the output stored in a mutable array.

Everytime an object is detected, all trailing bytes in the temporary array are moved to the start, and the detection process repeated. When all data bytes are processed, if one or more objects were created, they get sent to the delegate.

The demo app (and unit test) reads data from the text file JSON.txt (the list ofmy github repository projects in JSON format), and feeds it to the parser in small chunks with some small delay between each chunk (to simulate a network download).


The sole unit test runs a million loops, where it creates an object and sends random chunks of data, from 1 to 256 bytes, to verify that some particular "break" in the data does not cause problems. The initial converted array is compared to the pre-computed one to insure not a single byte is different.


A second demo target that actually uses the network to download data.


Much of this code was derived from code I developed at Sailthru (, who allowed me to cherry pick some of it for open sourcing here.


This code is subject to the Apache License, included with this distribution.

Latest podspec

    "name": "SAX-JSON-Parser",
    "version": "1.1.0",
    "platforms": {
        "ios": "7.0"
    "license": {
        "type": "Apache License, Version 2.0",
        "file": "LICENSE"
    "summary": "SAX Style JSON Parser, really a helper for NSJSONSerialization.",
    "homepage": "",
    "authors": {
        "David Hoerl": "[email protected]"
    "source": {
        "git": "",
        "tag": "v1.1.0"
    "requires_arc": true,
    "default_subspec": "Core",
    "description": "The JSONObjectExtractor utility class can provide a SAX style parser for the special case of JSON arrays containing dictionaries. Itaccepts a stream of NSData objects from a NSURLConnection or NSURLSession, which comprise a JSON array. Then, it passes NSJSONSerialization decoded objects back to the delegate as they are detected. In addition, if the JSON stream is from a MongoDB service, it intercepts and rewrites 'ObjectID(...)' and 'new Date(...)' fields, so the JSON can be parsed by NSJSONSerialization. The overhead cost for this rewriting is trivial, and several orders of magnitude faster than using regular expressions on the raw text to do it. For proper usage, see the demo project on github.n",
    "subspecs": [
            "name": "Core",
            "source_files": "SAX-JSON-Parser-ForStreamingData/Extractor/*.{h,m}",
            "frameworks": "Foundation"
            "name": "Mongo",
            "source_files": "SAX-JSON-Parser-ForStreamingData/Extractor/*.{h,m}",
            "frameworks": "Foundation",
            "compiler_flags": "-DMONGO_DB"

Pin It on Pinterest

Share This