Latest 0.1.3
Homepage https://github.com/roonieone/JSON
License MIT
Platforms ios 10.0, osx 10.12, watchos 3.0, tvos 10.0, requires ARC
Authors

JSON

Version
Build Status
Swift Version
Carthage compatible
CocoaPods compatible

Micro framework for easily parsing JSON in Swift 3 with rich error messages in less than 100 lines of code — Originally created by Sam Soffes.

Usage

Let’s say we have a simple user struct:

struct User {
    let name: String
    let createdAt: Date
}

Deserializing Attributes

We can add JSON deserialization to this really easily:

extension User: JSONDeserializable {
    init(jsonRepresentation json: JSONDictionary) throws {
        name = try decode(json, key: "name")
        createdAt = try decode(json, key: "created_at")
    }
}

(JSONDictionary is simply a typealias for [String: Any].)

Notice that you don’t have to specify types! This uses Swift generics and pattern matching so you don’t have to worry about this. The interface for those decode functions look like this:

func decode<T>(_ dictionary: JSONDictionary, key: String) throws -> T
func decode(_ dictionary: JSONDictionary, key: String) throws -> Date

There’s a specialized version that returns a Date. You can supply your own functions for custom types if you wish.

Here’s deserialization in action:

let dictionary = [
    "name": "Mark Malstrom",
    "created_at": "2016-09-22T22:28:37+02:00"
]

let sam = try User(jsonRepresentation: dictionary)

You can also simply do the following since user is JSONDeserializable.

let sam: User = try decode(dictionary)

Optional Attributes

Decoding an optional attribute is easy:

struct Comment {
    let body: String
    let publishedAt: Date?
}

extension Comment {
    init(jsonRepresentation json: JSONDictionary) throws {
        body = try deocde(json, key: "body")

        // See how we use `try?` to just get `nil` if it fails to decode?
        // Easy as that!
        publishedAt = try? deocde(json, key: "published_at")
    }
}

Deserializing Nested Dictionaries

Working with nested models is easy. Let’s say we have the following post model:

struct Post {
    let title: String
    let author: User
}

extension Post: JSONDeserializable {
    init(jsonRepresentation json: JSONDictionary) throws {
        title = try decode(json, key: "title")
        author = try decode(json, key: "author")
    }
}

We can simply treat a nested model like any other kind of attribute because there’s a generic function constrained to JSONDeserializable. Here’s the annotated implementation:

public func decode<T: JSONDeserializable>(_ dictionary: JSONDictionary, key: String) throws -> T {
    // Decode the value like normal as a JSONDictionary. If this fails for whatever
    // reason, it will throw the appropriate errors.
    let value: JSONDictionary = try decode(dictionary, key: key)

    // Decode the model. This will call the initializer in the protocol for the
    // expected type. If decoding fails in the model, this will also throw the
    // appropriate errors.
    return try decode(value)
}

Deserializing Custom Types

Let’s say you have the following enum:

enum RelationshipStatus: String {
    case stranger
    case friend
    case blocked
}

You could define a decode function for this type very easily:

func decode(_ dictionary: JSONDictionary, key: String) throws -> RelationshipStatus {
    let string: String = try decode(dictionary, key: key)

    guard let status = RelationshipStatus(rawValue: string) else {
        throw JSONDeserializationError.invalidAttribute(key: key)
    }

    return status
}

Then you can do try decode(dictionary, key: "status") like normal and it will throw the appropriate errors for you.

Installation

CocoaPods

You can use CocoaPods to install JSON by adding it to your Podfile:

pod 'JSON-Swift'

Carthage

Create a Cartfile that lists the framework and run carthage update. Follow the instructions to add $(SRCROOT)/Carthage/Build/iOS/YourLibrary.framework to an iOS project.

github "roonieone/JSON"

Swift Package Manager

Create a new directory where you want your project to live. Use swift package init --type executable to create set up your package. In your new Package.swift add the following:

import PackageDescription

let package = Package(
   name: "Project Name",
   dependencies: [
      .Package(url: "https://github.com/roonieone/JSON.git", "0.1.3")
   ]
)

Then use swift package fetch to download the JSON dependency and swift package generate-xcodeproj to create an Xcode Project. For more information on how to use Swift Package Manager with iOS, see this gist.

Latest podspec

{
    "name": "JSON-Swift",
    "version": "0.1.3",
    "summary": "A Micro framework for easily parsing JSON in Swift 3 with rich error messages in less than 100 lines of code",
    "description": "A Micro framework for easily parsing JSON in Swift 3 with rich error messages in less than 100 lines of code -- Originally created by Sam Soffes",
    "homepage": "https://github.com/roonieone/JSON",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    },
    "authors": {
        "Mark Malstrom": "[email protected]"
    },
    "social_media_url": "http://twitter.com/markmalstrom",
    "platforms": {
        "ios": "10.0",
        "osx": "10.12",
        "watchos": "3.0",
        "tvos": "10.0"
    },
    "source": {
        "git": "https://github.com/roonieone/JSON.git",
        "tag": "0.1.3"
    },
    "requires_arc": true,
    "source_files": "Sources",
    "pushed_with_swift_version": "3.1"
}

Pin It on Pinterest

Share This