JSONHelper

Lightning quick JSON deserialization for iOS & OS X written in Swift. Expanded upon the ideas found in this blog post.

Table of Contents

1. Purpose
2. Installation
3. Operator List
4. Simple Tutorial
5. Assigning Default Values
6. NSDate and NSURL Deserialization
7. JSON String Deserialization

Purpose

There are wonderful third party libraries out there that let you get data from an API end-point easily in just a couple lines. Wouldn't it be cool if deserializing that data was always just as easy, or perhaps even easier? Well, it is with JSONHelper! The sole purpose of JSONHelper is to make deserializing super easy even when working with data that contains lots of optional parameters and nested objects.

Requires iOS 7 or later and Xcode 6.1+.

Installation

I plan to support CocoaPods when it starts working with Swift libraries. Until then, as a quick and easy (yet a birt dirty) method, I recommend directly adding JSONHelper.swift into your project.

Operator List

Operator	Functionality
<<<	For deserializing data into primitive types, NSDate or NSURL.
<<<*	For deserializing data into an array of primitive types, NSDate or NSURL.
<<<<	For deserializing data into an instance of a class. Supports JSON strings
<<<<*	For deserializing data into an array that contains instances of a certain class. Supports JSON strings

Simple Tutorial

Let's assume you have two models like the ones given below, and an api end-point where you can submit a search query to search among your friends.

class User {
    var name: String?
    var age: Int?
}

class FriendSearchResult {
    var currentPage: Int?
    var pageCount: Int?
    var suggestedFriend: User?
    var friends: [User]?
}

Let's say you send the request using your favorite networking library and get back a response like this (of type [String: AnyObject]):

let dummyAPIResponse = [
    "current_page": 1,
    "page_count": 10,
    "suggested_friend": [
        "name": "Mark",
        "age": 30
    ],
    "friends": [
        [
            "name": "Hannibal",
            "age": 76
        ], [
            "name": "Sabrina",
            "age": 18
        ]
    ]
]

Deserializing this data is one line after you set your models up to use JSONHelper.

var searchResult = FriendSearchResult(data: dummyAPIResponse)

Or if your JSON response object is of type AnyObject and you don't want to bother casting it to a [String: AnyObject], you can do the following:

var searchResult: FriendSearchResult?

...

searchResult <<<< dummyAPIResponse

The good thing is your models will only look like this after you set them up:

class User: Deserializable {
    var name: String?
    var age: Int?

    required init(data: [String: AnyObject]) {
        name <<< data["name"]
        age <<< data["age"]
    }
}

class FriendSearchResult: Deserializable {
    var currentPage: Int?
    var pageCount: Int?
    var suggestedFriend: User?
    var friends: [User]?

    required init(data: [String : AnyObject]) {
        currentPage <<< data["current_page"]
        pageCount <<< data["page_count"]
        suggestedFriend <<<< data["suggested_friend"]
        friends <<<<* data["friends"]
    }
}

Assigning Default Values

JSONHelper also supports non-optional deserialization, which lets you easily assign default values in case deserialization fails.

class User: Deserializable {
    var name = "Guest"

    ...

    required init(data: [String: AnyObject]) {
        name <<< data["name"]

        ...

    }
}

NSDate and NSURL Deserialization

The <<< and <<<* operators also support deserializing data into NSDate and NSURL variables.

let website: NSURL?
let imageURLs: [NSURL]?

website <<< "http://mywebsite.com"
imageURLs <<<* ["http://mywebsite.com/image.png", "http://mywebsite.com/anotherImage.png"]

let meetingDate: NSDate?
let partyDates: [NSDate]?

meetingDate <<< (value: "2014-09-18", format: "yyyy-MM-dd")
partyDates <<<* (value: ["2014-09-19", "2014-09-20"], format: "yyyy-MM-dd")

let myDayOff: NSDate?
myDayOff <<< 1414172803 // You can also use unix timestamps.

JSON String Deserialization

You can swiftly deserialize instances and arrays of instances directly from a JSON string with JSONHelper as well. Here is a quick and Groot-y example.

class Person: Deserializable {
    var name = ""

    required init(data: [String: AnyObject]) {
        name <<< data["name"]
    }
}

var jsonString = "[{\"name\": \"I am \"},{\"name\": \"Groot!\"}]"
var people = [Person]()

people <<<<* jsonString

for person in people {
    println("\(person.name)")
}