0
deps
14K
stars
SwiftyJSON
3.1.4

SwiftyJSON

Travis CI Carthage compatible CocoaPods Platform

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

  1. Why is the typical JSON handling in Swift NOT good
  2. Requirements
  3. Integration
  4. Usage
  5. Work with Alamofire
  6. Work with Moya

For Legacy Swift support, take a look at the swift2 branch

中文介绍

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 https://dev.twitter.com/docs/api/1.1/get/statuses/home_timeline).

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
          }

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
          }

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
          }

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

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

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 SwiftyJSONby adding it to your Podfile:

platform :ios, '8.0'
          use_frameworks!
          
          target 'MyApp' do
          	pod 'SwiftyJSON'
          end

Note that this requires CocoaPods version 36, and your iOS deployment target to be at least 8.0:

Carthage (iOS 8+, OS X 10.9+)

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

github "SwiftyJSON/SwiftyJSON"
          

Swift Package Manager

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

import PackageDescription
          
          let package = Package(
              name: "YOUR_PROJECT_NAME",
              targets: [],
              dependencies: [
                  .Package(url: "https://github.com/SwiftyJSON/SwiftyJSON.git", versions: Version(1, 0, 0)..<Version(3, .max, .max)),
              ]
          )

Note that the Swift Package Manager is still in early design and development, for more information checkout its GitHub Page

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
let json = JSON(data: dataFromNetworking)
let json = JSON(jsonObject)
if let dataFromString = jsonString.data(using: .utf8, allowLossyConversion: false) {
              let json = JSON(data: dataFromString)
          }

Subscript

//Getting a double from a JSON Array
          let name = json[0].double
//Getting an array of string from a JSON Array
          let arrayNames =  json["users"].arrayValue.map({$0["name"].stringValue})
//Getting a string from a JSON Dictionary
          let name = json["name"].stringValue
//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
//With a hard way
          let name = json[].string
//With a custom way
          let keys:[SubscriptType] = [1,"list",2,"name"]
          let name = json[keys].string

Loop

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

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
          }

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"
          }
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"
          }
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"
          }

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!)
          }
//String
          if let id = json["user"]["name"].string {
             //Do something you want
          } else {
             //Print the error
             print(json["user"]["name"].error!)
          }
//Bool
          if let id = json["user"]["is_translator"].bool {
             //Do something you want
          } else {
             //Print the error
             print(json["user"]["is_translator"].error!)
          }
//Int
          if let id = json["user"]["id"].int {
             //Do something you want
          } else {
             //Print the error
             print(json["user"]["id"].error!)
          }
          ...

Non-optional getter

Non-optional getter is named xxxValue

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

Setter

json["name"] = JSON("new-name")
          json[0] = JSON(1)
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]

Raw object

let jsonObject: Any = json.object
if let jsonObject: Any = json.rawValue
//convert the JSON to raw NSData
          if let data = json.rawData() {
              //Do something you want
          }
//convert the JSON to a raw String
          if let string = json.rawString() {
              //Do something you want
          }

Existence

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

Literal convertibles

For more info about literal convertibles: Swift Literal Convertibles

//StringLiteralConvertible
          let json: JSON = "I'm a json"
//IntegerLiteralConvertible
          let json: JSON =  12345
//BooleanLiteralConvertible
          let json: JSON =  true
//FloatLiteralConvertible
          let json: JSON =  2.8765
//DictionaryLiteralConvertible
          let json: JSON =  ["I":"am", "a":"json"]
//ArrayLiteralConvertible
          let json: JSON =  ["I", "am", "a", "json"]
//NilLiteralConvertible
          let json: JSON =  nil
//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
//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
//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"
//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"
          ]

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 case, where two fields in a JSON have a 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"
          //     ]
          // ]

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}

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)
              }
          }

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)")
              }
          }
          

Enter your project's GitHub URL

It will be indexed and available for search momentarily. Non-github projects are not supported at the moment.

Error indexing this package

If you think it should have worked, contact support with the link in question.

Thanks!

Your project should be indexed momentarily