Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
This branch is 85 commits ahead, 342 commits behind SwiftyJSON:master.

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

SwiftyJSON 中文介绍

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

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? NSJSONSerialization.JSONObjectWithData(data, options: .AllowFragments) as? [[String: AnyObject]],
    let user = statusesArray[0]["user"] as? [String: AnyObject],
    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 NSJSONSerialization.JSONObjectWithData(data, options: .AllowFragments) as? [[String: AnyObject]],
    let username = (JSONObject[0]["user"] as? [String: AnyObject])?["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


Swift 3


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: "", versions: "2.3.3" ..< Version.max)



import SwiftyJSON
let json = JSON(data: dataFromNetworking)
let json = JSON(jsonObject)
if let dataFromString = jsonString.dataUsingEncoding(NSUTF8StringEncoding, allowLossyConversion: false) {
    let json = JSON(data: dataFromString)


//Getting a double from a JSON Array
let name = json[0].double
//Getting a string from a JSON Dictionary
let name = json["name"].stringValue
//Getting a string using a path to the element
let path = [1,"list",2,"name"]
let name = json[path].string
//Just the same
let name = json[1]["list"][2]["name"].string
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


//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


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

if let id = json["user"]["favourites_count"].number {
   //Do something you want
} else {
   //Print the error
if let id = json["user"]["name"].string {
   //Do something you want
} else {
   //Print the error
if let id = json["user"]["is_translator"].bool {
   //Do something you want
} else {
   //Print the error
if let id = json["user"]["id"].int {
   //Do something you want
} else {
   //Print the 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 a 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


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.dictionary = ["name":"Jack", "age":25]

Raw object

let jsonObject: AnyObject = json.object
if let jsonObject: AnyObject = 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


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

Literal convertibles

For more info about literal convertibles: Swift Literal Convertibles

let json: JSON = "I'm a json"
let json: JSON =  12345
let json: JSON =  true
let json: JSON =  2.8765
let json: JSON =  ["I":"am", "a":"json"]
let json: JSON =  ["I", "am", "a", "json"]
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 = ["list",3,"what"]
json[path] = "that"

Work with Alamofire

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

Alamofire.request(.GET, url).validate().responseJSON { response in
    switch response.result {
    case .Success:
        if let value = response.result.value {
          let json = JSON(value)
          print("JSON: \(json)")
    case .Failure(let error):


The better way to deal with JSON data in Swift







No packages published


  • Swift 100.0%