SwiftyJSON makes it easy to deal with JSON data in Swift.
Platform | Build Status |
---|---|
*OS | |
Linux |
- Why is the typical JSON handling in Swift NOT good
- Requirements
- Integration
- Usage
- Work with Alamofire
- Work with Moya
- SwiftyJSON Model Generator
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 toTwitter's API).
The code would look like this:
ifletstatusesArray=try?JSONSerialization.jsonObject(with:data,options:.allowFragments)as?[[String:Any]],
letuser=statusesArray[0]["user"]as?[String:Any],
letusername=user["name"]as?String{
// Finally we got the username
}
It's not good.
Even if we use optional chaining, it would be messy:
ifletJSONObject=tryJSONSerialization.jsonObject(with:data,options:.allowFragments)as?[[String:Any]],
letusername=(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:
letjson=try?JSON(data:dataFromNetworking)
ifletuserName=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.
letjson=try?JSON(data:dataFromNetworking)
letresult=json[999999]["wrong_key"]["wrong_name"]
ifletuserName=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)
}
- iOS 8.0+ | macOS 10.10+ | tvOS 9.0+ | watchOS 2.0+
- Xcode 8
You can useCocoaPodsto installSwiftyJSON
by adding it to yourPodfile
:
platform:ios,'8.0'
use_frameworks!
target'MyApp'do
pod'SwiftyJSON','~> 4.0'
end
You can useCarthageto installSwiftyJSON
by adding it to yourCartfile
:
github "SwiftyJSON/SwiftyJSON" ~> 4.0
If you use Carthage to build your dependencies, make sure you have addedSwiftyJSON.framework
to the "Linked Frameworks and Libraries" section of your target, and have included them in your Carthage framework copying build phase.
You can useThe Swift Package Managerto installSwiftyJSON
by adding the proper description to yourPackage.swift
file:
// swift-tools-version:4.0
import PackageDescription
letpackage=Package(
name:"YOUR_PROJECT_NAME",
dependencies:[
.package(url:"https://github /SwiftyJSON/SwiftyJSON.git",from:"4.0.0"),
]
)
Then runswift build
whenever you get prepared.
To use this library in your project manually you may:
- for Projects, just drag SwiftyJSON.swift to the project tree
- for Workspaces, include the whole SwiftyJSON.xcodeproj
import SwiftyJSON
letjson=try?JSON(data:dataFromNetworking)
Or
letjson=JSON(jsonObject)
Or
ifletdataFromString=jsonString.data(using:.utf8,allowLossyConversion:false){
letjson=JSON(data:dataFromString)
}
// Getting a double from a JSON Array
letname=json[0].double
// Getting an array of string from a JSON Array
letarrayNames=json["users"].arrayValue.map{$0["name"].stringValue}
// Getting a string from a JSON Dictionary
letname=json["name"].stringValue
// Getting a string using a path to the element
letpath:[JSONSubscriptType]=[1,"list",2,"name"]
letname=json[path].string
// Just the same
letname=json[1]["list"][2]["name"].string
// Alternatively
letname=json[1,"list",2,"name"].string
// With a hard way
letname=json[].string
// With a custom way
letkeys:[JSONSubscriptType]=[1,"list",2,"name"]
letname=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
}
SwiftyJSON 4.x introduces an enum type calledSwiftyJSONError
,which includesunsupportedType
,indexOutOfBounds
,elementTooDeep
,wrongType
,notExist
andinvalidJSON
,at the same time,ErrorDomain
are being replaced bySwiftyJSONError.errorDomain
.
Note: Those old error types are deprecated in SwiftyJSON 4.x and will be removed in the future release.
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.
letjson=JSON(["name","age"])
ifletname=json[999].string{
// Do something you want
}else{
print(json[999].error!)// "Array[999] is out of bounds"
}
letjson=JSON(["name":"Jack","age":25])
ifletname=json["address"].string{
// Do something you want
}else{
print(json["address"].error!)// "Dictionary[" address "] does not exist"
}
letjson=JSON(12345)
ifletage=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"
}
ifletname=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"
}
// NSNumber
ifletid=json["user"]["favourites_count"].number{
// Do something you want
}else{
// Print the error
print(json["user"]["favourites_count"].error!)
}
// String
ifletid=json["user"]["name"].string{
// Do something you want
}else{
// Print the error
print(json["user"]["name"].error!)
}
// Bool
ifletid=json["user"]["is_translator"].bool{
// Do something you want
}else{
// Print the error
print(json["user"]["is_translator"].error!)
}
// Int
ifletid=json["user"]["id"].int{
// Do something you want
}else{
// Print the error
print(json["user"]["id"].error!)
}
...
Non-optional getter is namedxxxValue
// If not a Number or nil, return 0
letid:Int=json["id"].intValue
// If not a String or nil, return ""
letname:String=json["name"].stringValue
// If not an Array or nil, return []
letlist:Array<JSON>=json["list"].arrayValue
// If not a Dictionary or nil, return [:]
letuser: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.dictionaryObject=["name":"Jack","age":25]
letrawObject:Any=json.object
letrawValue:Any=json.rawValue
//convert the JSON to raw NSData
do{
letrawData=tryjson.rawData()
//Do something you want
}catch{
print("Error\(error)")
}
//convert the JSON to a raw String
ifletrawString=json.rawString(){
//Do something you want
}else{
print("json.rawString is nil")
}
// shows you whether value specified in JSON or not
ifjson["name"].exists()
For more info about literal convertibles:Swift Literal Convertibles
// StringLiteralConvertible
letjson:JSON="I'm a json"
// IntegerLiteralConvertible
letjson:JSON=12345
// BooleanLiteralConvertible
letjson:JSON=true
// FloatLiteralConvertible
letjson:JSON=2.8765
// DictionaryLiteralConvertible
letjson:JSON=["I":"am","a":"json"]
// ArrayLiteralConvertible
letjson:JSON=["I","am","a","json"]
// With subscript in array
varjson: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
varjson: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
varjson:JSON=["name":"Jack","age":25,"list":["a","b","c",["what":"this"]]]
json["list"][3]["what"]="that"
json["list",3,"what"]="that"
letpath:[JSONSubscriptType]=["list",3,"what"]
json[path]="that"
// With other JSON objects
letuser:JSON=["username":"Steve","password":"supersecurepassword"]
letauth:JSON=[
"user":user.object,// use user.object instead of just user
"apikey":"supersecretapitoken"
]
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 theother
JSON.
If both JSONs contain a value for the same key,mostlythis 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 theother
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, whereasmerged
works non-destructively on a copy.
letoriginal:JSON=[
"first_name":"John",
"age":20,
"skills":["Coding","Reading"],
"address":[
"street":"Front St",
"zip":"12345",
]
]
letupdate:JSON=[
"last_name":"Doe",
"age":21,
"skills":["Writing"],
"address":[
"zip":"12342",
"city":"New York City"
]
]
letupdated=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"
// ]
// ]
There are two options available:
- use the default Swift one
- use a custom one that will handle optionals well and represent
nil
as"null"
:
letdict=["1":2,"2":"two","3":nil]as[String:Any?]
letjson=JSON(dict)
letrepresentation=json.rawString(options:[.castNilToNSNull:true])
// representation is "{\" 1\ ":2,\" 2\ ":\" two\ ",\" 3\ ":null}", which represents { "1":2, "2": "two", "3":null}
Work withAlamofire
SwiftyJSON nicely wraps the result of the Alamofire JSON response handler:
Alamofire.request(url,method:.get).validate().responseJSON{responsein
switch response.result{
case.success(letvalue):
letjson=JSON(value)
print("JSON:\(json)")
case.failure(leterror):
print(error)
}
}
We also provide an extension of Alamofire for serializing NSData to SwiftyJSON's JSON.
Work withMoya
SwiftyJSON parse data to JSON:
letprovider=MoyaProvider<Backend>()
provider.request(.showProducts){resultin
switch result{
caselet.success(moyaResponse):
letdata=moyaResponse.data
letjson=JSON(data:data)// convert network data to json
print(json)
caselet.failure(error):
print("error:\(error)")
}
}
Tools to generate SwiftyJSON Models