SwiftyJSON

SwiftyJSON makes it easy to deal with JSON data in Swift.

Platform Build Status
*OS Travis CI
Linux Build Status

Why is the typical JSON handling in Swift NOT good?

Swift is very strict about types. But although explicit typing is good for saving us from mistakes, it becomes painful when dealing with JSON and other areas that are, by nature, implicit about types.

Take the Twitter API for example. Say we want to retrieve a user's "name" value of some tweet in Swift (according to Twitter's API).

The code would look like this:

if let statusesArray = try? JSONSerialization.jsonObject(with: data, options: .allowFragments) as? [[String: Any]],
    let user = statusesArray[0]["user"] as? [String: Any],
    let username = user["name"] as? String {
    // Finally we got the username
}
Swift

It's not good.

Even if we use optional chaining, it would be messy:

if let JSONObject = try JSONSerialization.jsonObject(with: data, options: .allowFragments) as? [[String: Any]],
    let username = (JSONObject[0]["user"] as? [String: Any])?["name"] as? String {
        // There's our username
}
Swift

An unreadable mess--for something that should really be simple!

With SwiftyJSON all you have to do is:

let json = JSON(data: dataFromNetworking)
if let userName = json[0]["user"]["name"].string {
  //Now you got your value
}
Swift

And don't worry about the Optional Wrapping thing. It's done for you automatically.

let json = JSON(data: dataFromNetworking)
let result = json[999999]["wrong_key"]["wrong_name"]
if let userName = result.string {
    //Calm down, take it easy, the ".string" property still produces the correct Optional String type with safety
} else {
    //Print the error
    print(result.error)
}
Swift

Requirements

  • iOS 8.0+ | macOS 10.10+ | tvOS 9.0+ | watchOS 2.0+
  • Xcode 8

Integration

CocoaPods (iOS 8+, OS X 10.9+)

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

platform :ios, '8.0'
use_frameworks!

target 'MyApp' do
    pod 'SwiftyJSON', '~> 4.0'
end
Ruby

Carthage (iOS 8+, OS X 10.9+)

You can use Carthage to install SwiftyJSON by adding it to your Cartfile:

github "SwiftyJSON/SwiftyJSON" ~> 4.0

If you use Carthage to build your dependencies, make sure you have added SwiftyJSON.framework to the "Linked Frameworks and Libraries" section of your target, and have included them in your Carthage framework copying build phase.

Swift Package Manager

You can use The Swift Package Manager to install SwiftyJSON by adding the proper description to your Package.swift file:

// swift-tools-version:4.0
import PackageDescription

let package = Package(
    name: "YOUR_PROJECT_NAME",
    dependencies: [
        .package(url: "https://github.com/SwiftyJSON/SwiftyJSON.git", from: "4.0.0"),
    ]
)
Swift

Then run swift build whenever you get prepared.

Manually (iOS 7+, OS X 10.9+)

To use this library in your project manually you may:

  1. for Projects, just drag SwiftyJSON.swift to the project tree
  2. for Workspaces, include the whole SwiftyJSON.xcodeproj

Usage

Initialization

import SwiftyJSON
Swift
let json = JSON(data: dataFromNetworking)
Swift

Or

let json = JSON(jsonObject)
Swift

Or

if let dataFromString = jsonString.data(using: .utf8, allowLossyConversion: false) {
    let json = JSON(data: dataFromString)
}
Swift

Subscript

// Getting a double from a JSON Array
let name = json[0].double
Swift
// Getting an array of string from a JSON Array
let arrayNames =  json["users"].arrayValue.map {$0["name"].stringValue}
Swift
// Getting a string from a JSON Dictionary
let name = json["name"].stringValue
Swift
// Getting a string using a path to the element
let path: [JSONSubscriptType] = [1,"list",2,"name"]
let name = json[path].string
// Just the same
let name = json[1]["list"][2]["name"].string
// Alternatively
let name = json[1,"list",2,"name"].string
Swift
// With a hard way
let name = json[].string
Swift
// With a custom way
let keys:[JSONSubscriptType] = [1,"list",2,"name"]
let name = json[keys].string
Swift

Loop

// If json is .Dictionary
for (key,subJson):(String, JSON) in json {
   // Do something you want
}
Swift

The first element is always a String, even if the JSON is an Array

// If json is .Array
// The `index` is 0..<json.count's string value
for (index,subJson):(String, JSON) in json {
    // Do something you want
}
Swift

Error

SwiftyJSON 4.x

SwiftyJSON 4.x introduces an enum type called SwiftyJSONError, which includes unsupportedType, indexOutOfBounds, elementTooDeep, wrongType, notExist and invalidJSON, at the same time, ErrorDomain are being replaced by SwiftyJSONError.errorDomain.
Note: Those old error types are deprecated in SwiftyJSON 4.x and will be removed in the future release.

SwiftyJSON 3.x

Use a subscript to get/set a value in an Array or Dictionary

If the JSON is:

  • an array, the app may crash with "index out-of-bounds."
  • a dictionary, it will be assigned to nil without a reason.
  • not an array or a dictionary, the app may crash with an "unrecognised selector" exception.

This will never happen in SwiftyJSON.

let json = JSON(["name", "age"])
if let name = json[999].string {
    // Do something you want
} else {
    print(json[999].error!) // "Array[999] is out of bounds"
}
Swift
let json = JSON(["name":"Jack", "age": 25])
if let name = json["address"].string {
    // Do something you want
} else {
    print(json["address"].error!) // "Dictionary["address"] does not exist"
}
Swift
let json = JSON(12345)
if let age = json[0].string {
    // Do something you want
} else {
    print(json[0])       // "Array[0] failure, It is not an array"
    print(json[0].error!) // "Array[0] failure, It is not an array"
}

if let name = json["name"].string {
    // Do something you want
} else {
    print(json["name"])       // "Dictionary[\"name"] failure, It is not an dictionary"
    print(json["name"].error!) // "Dictionary[\"name"] failure, It is not an dictionary"
}
Swift

Optional getter

// NSNumber
if let id = json["user"]["favourites_count"].number {
   // Do something you want
} else {
   // Print the error
   print(json["user"]["favourites_count"].error!)
}
Swift
// String
if let id = json["user"]["name"].string {
   // Do something you want
} else {
   // Print the error
   print(json["user"]["name"].error!)
}
Swift
// Bool
if let id = json["user"]["is_translator"].bool {
   // Do something you want
} else {
   // Print the error
   print(json["user"]["is_translator"].error!)
}
Swift
// Int
if let id = json["user"]["id"].int {
   // Do something you want
} else {
   // Print the error
   print(json["user"]["id"].error!)
}
...
Swift

Non-optional getter

Non-optional getter is named xxxValue

// If not a Number or nil, return 0
let id: Int = json["id"].intValue
Swift
// If not a String or nil, return ""
let name: String = json["name"].stringValue
Swift
// If not an Array or nil, return []
let list: Array<JSON> = json["list"].arrayValue
Swift
// If not a Dictionary or nil, return [:]
let user: Dictionary<String, JSON> = json["user"].dictionaryValue
Swift

Setter

json["name"] = JSON("new-name")
json[0] = JSON(1)
Swift
json["id"].int =  1234567890
json["coordinate"].double =  8766.766
json["name"].string =  "Jack"
json.arrayObject = [1,2,3,4]
json.dictionaryObject = ["name":"Jack", "age":25]
Swift

Raw object

let rawObject: Any = json.object
Swift
let rawValue: Any = json.rawValue
Swift
//convert the JSON to raw NSData
do {
	let rawData = try json.rawData()
  //Do something you want
} catch {
	print("Error \(error)")
}
Swift
//convert the JSON to a raw String
if let rawString = json.rawString() {
  //Do something you want
} else {
	print("json.rawString is nil")
}
Swift

Existence

// shows you whether value specified in JSON or not
if json["name"].exists()
Swift

Literal convertibles

For more info about literal convertibles: Swift Literal Convertibles

// StringLiteralConvertible
let json: JSON = "I'm a json"
Swift
/ /IntegerLiteralConvertible
let json: JSON =  12345
Swift
// BooleanLiteralConvertible
let json: JSON =  true
Swift
// FloatLiteralConvertible
let json: JSON =  2.8765
Swift
// DictionaryLiteralConvertible
let json: JSON =  ["I":"am", "a":"json"]
Swift
// ArrayLiteralConvertible
let json: JSON =  ["I", "am", "a", "json"]
Swift
// With subscript in array
var json: JSON =  [1,2,3]
json[0] = 100
json[1] = 200
json[2] = 300
json[999] = 300 // Don't worry, nothing will happen
Swift
// With subscript in dictionary
var json: JSON =  ["name": "Jack", "age": 25]
json["name"] = "Mike"
json["age"] = "25" // It's OK to set String
json["address"] = "L.A." // Add the "address": "L.A." in json
Swift
// Array & Dictionary
var json: JSON =  ["name": "Jack", "age": 25, "list": ["a", "b", "c", ["what": "this"]]]
json["list"][3]["what"] = "that"
json["list",3,"what"] = "that"
let path: [JSONSubscriptType] = ["list",3,"what"]
json[path] = "that"
Swift
// With other JSON objects
let user: JSON = ["username" : "Steve", "password": "supersecurepassword"]
let auth: JSON = [
  "user": user.object, // use user.object instead of just user
  "apikey": "supersecretapitoken"
]
Swift

Merging

It is possible to merge one JSON into another JSON. Merging a JSON into another JSON adds all non existing values to the original JSON which are only present in the other JSON.

If both JSONs contain a value for the same key, mostly this value gets overwritten in the original JSON, but there are two cases where it provides some special treatment:

  • In case of both values being a JSON.Type.array the values form the array found in the other JSON getting appended to the original JSON's array value.
  • In case of both values being a JSON.Type.dictionary both JSON-values are getting merged the same way the encapsulating JSON is merged.

In a case where two fields in a JSON have different types, the value will get always overwritten.

There are two different fashions for merging: merge modifies the original JSON, whereas merged works non-destructively on a copy.

let original: JSON = [
    "first_name": "John",
    "age": 20,
    "skills": ["Coding", "Reading"],
    "address": [
        "street": "Front St",
        "zip": "12345",
    ]
]

let update: JSON = [
    "last_name": "Doe",
    "age": 21,
    "skills": ["Writing"],
    "address": [
        "zip": "12342",
        "city": "New York City"
    ]
]

let updated = original.merge(with: update)
// [
//     "first_name": "John",
//     "last_name": "Doe",
//     "age": 21,
//     "skills": ["Coding", "Reading", "Writing"],
//     "address": [
//         "street": "Front St",
//         "zip": "12342",
//         "city": "New York City"
//     ]
// ]
Swift

String representation

There are two options available:

  • use the default Swift one
  • use a custom one that will handle optionals well and represent nil as "null":
let dict = ["1":2, "2":"two", "3": nil] as [String: Any?]
let json = JSON(dict)
let representation = json.rawString(options: [.castNilToNSNull: true])
// representation is "{\"1\":2,\"2\":\"two\",\"3\":null}", which represents {"1":2,"2":"two","3":null}
Swift

Work with Alamofire

SwiftyJSON nicely wraps the result of the Alamofire JSON response handler:

Alamofire.request(url, method: .get).validate().responseJSON { response in
    switch response.result {
    case .success(let value):
        let json = JSON(value)
        print("JSON: \(json)")
    case .failure(let error):
        print(error)
    }
}
Swift

We also provide an extension of Alamofire for serializing NSData to SwiftyJSON's JSON.

See: Alamofire-SwiftyJSON

Work with Moya

SwiftyJSON parse data to JSON:

let provider = MoyaProvider<Backend>()
provider.request(.showProducts) { result in
    switch result {
    case let .success(moyaResponse):
        let data = moyaResponse.data
        let json = JSON(data: data) // convert network data to json
        print(json)
    case let .failure(error):
        print("error: \(error)")
    }
}
Swift

SwiftyJSON Model Generator

Tools to generate SwiftyJSON Models

GitHub

https://github.com/SwiftyJSON/SwiftyJSON