A flexible collection of Swift protocols and helpers to organize and manage translating between JSON and native Swift objects.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.



Powered by Dockwa

Version License Platform

A flexible collection of Swift protocols and helpers to organize and manage translating between JSON and native Swift objects.

Designed to give your model objects a consistent JSON conversion / mapping / caching / offline strategy without getting in your way.

  • Designed to be flexible enough to let you implement your models as your requirements dictate while giving you a general framework to organize your JSON parsing and caching strategy.

  • A collection of composable but distinct features, so you can use the protocols and helpers that work for the use case at hand.

  • Simple, straightforward, and lightweight; Derulo sits right between "I'll just implement it myself without a third party library" and "I don't really want to reinvent the wheel and implement a JSON strategy from scratch"


start with JSON

var jasonJSON = [String : Any]()
jasonJSON["id"] = 93
jasonJSON["name"] = "Jason Derulo"
jasonJSON["fav_song"] = "wiggle"


parse into model object

let jasonPerson = Person(json: jasonJSON)


convert to JSON

let jasonPersonJSON = jasonPerson.asJSON


make another json

var jaySeanJSON = JSON()
jaySeanJSON["id"] = 57
jaySeanJSON["name"] = "Jay Sean"

start with array of json

let jsonArray: [JSON] = [jasonJSON, jaySeanJSON]

parse into model object

let people: [Person] = JSONMapper<Person>().mapArray(json: jsonArray)

convert to JSON

let peopleJSON: [JSON] = JSONConverter<Person>().jsonArray(fromArray: people)


let persistenceKey = "people"

store to disk

JSONPersistenceManager<Person>().store(array: people, withKey: persistenceKey)

restore from disk

let restoredPeople: [Person] = JSONPersistenceManager<Person>().restoreArray(withKey: persistenceKey)

delete from disk

JSONPersistenceManager<Person>().removeObject(withKey: persistenceKey)

From Data

start with Data

guard let data = try? JSONSerialization.data(withJSONObject: jasonJSON, options: []) else { return }

map to object

let jasonPersonFromData = JSONMapper<Person>().map(data: data)
print(jasonPersonFromData ?? "")

Example Implementation

struct Person: Identifiable {
    let identifier: Identifier
    let name: String
    let favoriteSong: Song?

extension Person: JSONMappable {
    init?(json: JSON?) {
        guard let json = json else { return nil }
        guard let id = IntToStringTransform().transform(fromJSON: json["id"]) else {
            print(#function, String(describing: Person.self), "JSON missing required properties")
            return nil
        self.identifier = id
        self.name = json["name"] as? String ?? "No Name"
        self.favoriteSong = Song(jsonEntry: json["fav_song"])

extension Person: JSONConvertible {
    var asJSON: JSON {
        var json = JSON()
        json["id"] = IntToStringTransform().transform(toJSON: identifier)
        json["name"] = name
        if let favoriteSong = favoriteSong {
            json["fav_song"] = favoriteSong.asJSONEntry
        return json

extension Person: JSONModel {}

extension Person: JSONPersistable {
    var asPersistenceJSON: JSON {
        return asJSON

enum Song: String {
    case wiggle
    case talkDirty

extension Song: JSONEntryMappable, JSONEntryConvertible {

    init?(jsonEntry: JSONEntry?) {
        guard let jsonEntry = jsonEntry as? String else { return nil }
        self.init(rawValue: jsonEntry)
    var asJSONEntry: String {
        return rawValue


Swift 3.0


Derulo is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod 'Derulo'


Christian Hatch, christianhatch@gmail.com


Derulo is available under the MIT license. See the LICENSE file for more info.