Latest 1.7.0
License MIT
Platforms ios 6.0, requires ARC
Frameworks Foundation

Wrapper around NSJSONSerialization

Tiny wrapper around NSJSONSerialization to parse JSON. Its major features are:

  • Detailed error reporting.
  • Error handling is based on throwing exceptions instead of "if hell".
  • Type checking.
  • Fluent API.


@interface Menu : NSObject
@property (nonatomic) NSString *header;
@property (nonatomic) NSNumber *height;
@property (nonatomic) NSNumber *width;

@implementation Menu

+ (POSJSONMap *)exampleJSON {
    return [[POSJSONMap alloc] initWithData:[
        @"{"menu": {"
        "    "header": "SVG Viewer","
        "    "height": 500,"
        "    "items": ["
        "        {"id": "Open"},"
        "        {"id": "OpenNew", "label": "Open New"},"
        "        null,"
        "        {"id": "ZoomIn", "label": "Zoom In"},"
        "    ]"

+ (Menu *)parseMenu:(NSError **)error {
    @try {
        POSJSONMap *JSON = [[[self exampleJSON] extract:@"menu"] asMap];
        Menu *menu = [Menu new];
        // mandatory parameters
        menu.header = [[JSON extract:@"header"] asString];
        menu.height = [[JSON extract:@"height"] asNumber];
        // optional parameters
        menu.width = [[JSON tryExtract:@"width"] asNumber];
        return menu;
    @catch (NSException *exception) {
        if (error) {
            *error = [NSError errorWithDomain:@"com.example"
                                     userInfo:@{ NSLocalizedDescriptionKey: [exception reason] }];
        return nil;


If to replace in the example above [[JSON tryExtract:@"width"] asNumber] with
[[JSON extract:@"width"] asNumber] then exception will be thrown with the following reason:

'' doesn't contain object with key 'width' in JSON:
    "menu": {
        "header": "SVG Viewer",
        "height": 500,
        "items": [
            {"id": "Open"},
            {"id": "OpenNew", "label": "Open New"},
            {"id": "ZoomIn", "label": "Zoom In"},


As we know NSException and ARC are not best friends. At the same time usually JSON is a contract
between your app and some remote service. If everithing is OK then will be no exceptions at all,
in other case there is some kind of contract violation and you have more serious problems than
some leaked objects during malformed JSON parsing. For example NSKeyedArchiever notifies clients
about errors in the same manner during archive unpacking.


Latest podspec

    "name": "POSJSONParsing",
    "version": "1.7.0",
    "license": "MIT",
    "summary": "Tiny wrapper around NSJSONSerialization to parse JSON with fluent API and detailed error reporting.",
    "homepage": "",
    "authors": {
        "Pavel Osipov": "[email protected]"
    "source": {
        "git": "",
        "tag": "1.7.0"
    "platforms": {
        "ios": "6.0"
    "requires_arc": true,
    "source_files": "POSJSONParsing/*.{h,m}",
    "frameworks": "Foundation"

Pin It on Pinterest

Share This