JSONUtilities

Easily load JSON objects and decode them into structs or classes. The json(atKeyPath:) function infers the type from the constant or variable definition to decode meaning no casting is needed. Both string keys and keypaths (keys separated by dots .) are supported when decoding JSON.

• Check out the Example.playground inside the JSONUtilities.xcodeproj for a working example

Installation

CocoaPods:

Add the line pod 'JSONUtilities' to your Podfile.

Carthage:

Add the line github "lucianomarisi/JSONUtilities" to your Cartfile.

Manual:

Add the files inside the Sources folder into your Xcode project.

Swift Package Manager:

Add the line .Package(url: "https://github.com/lucianomarisi/JSONUtilities", majorVersion: 3) to your Package.swift.

Types supported

JSON raw types:

• Int
• Double
• Float
• String
• Bool
• [String: AnyObject]
• RawRepresentable enums

Array of JSON raw types:

• [Int]
• [Double]
• [Float]
• [String]
• [Bool]
• [[String: AnyObject]]
• [RawRepresentable]

Custom JSON objects and custom JSON object arrays

e.g. if MyClass and MyStruct conform to JSONObjectConvertible protocol

• MyClass
• [MyClass]
• MyStruct
• [MyStruct]

Typed dictionaries with a String key

• [String: JSONRawType]
• [String: JSONObjectConvertible]
• [String: JSONPrimitiveConvertible]
• [String: RawRepresentable]

InvalidItemBehaviour

When decoding arrays or dictionaries an invalidItemBehaviour parameter can be passed which controls what happens when an error occurs while decoding child items

• .remove this will simply remove the item from the array or dictionary. This is the default
• .fail if any of the children encounter an error the whole array or dictionary decoding will fail. For optional properties this means the array or dictionary will return nil, and for non optional properties it will throw an error
• .value(T) Provide an alternative value
• .custom((DecodingError) -> InvalidItemBehaviour) Lets you specify the behaviour based on the specific DecodingError

Examples of JSON loading

From file

let filename = "myjsonfile"
let dictionary: [String: AnyObject] = try JSONDictionary.from(filename: filename)

From data

let data: Data = ...
let dictionary: [String: AnyObject] = try JSONDictionary.from(jsonData: data)

Examples of JSON decoding

Consider a JSON object that represents a person:

{
  "name" : "John Doe",
  "age" : 24,
  "weight" : 72.4
}

Decode JSON inline

let jsonDictionary = try JSONDictionary.from(filename: "person.json")
let name: String = try jsonDictionary.json(atKeyPath: "name")
let age: Int = try jsonDictionary.json(atKeyPath: "age")
let weight: Int = try jsonDictionary.json(atKeyPath: "weight")
let profession: String? = jsonDictionary.json(atKeyPath: "profession") // Optional decoding

Decode structs or classes

struct Person { //OR class Person {

  let name: String
  let age: Int
  let weight: Double
  let profession: String?

  init(jsonDictionary: JSONDictionary) throws {
    name = try jsonDictionary.json(atKeyPath: "name")
    age = try jsonDictionary.json(atKeyPath: "age")
    weight = try jsonDictionary.json(atKeyPath: "weight")
    profession = jsonDictionary.json(atKeyPath: "profession")
  }

}

Decode nested structs or classes by conforming to the JSONObjectConvertible protocol

Consider a company JSON object:

{
    "name" : "Working name LTD.",
    "employees": [
        {
            "name": "John Doe",
            "age": 24,
            "weight": 72.4
        },
        {
            "name": "Jane Doe",
            "age": 22,
            "weight": 70.1
        }
    ]
}

The Company struct can decode an array of Person structs/classes by making Person conform to the JSONObjectConvertible protocol

struct Company {
  let name: String
  let employees: [Person]

  init(jsonDictionary: JSONDictionary) throws {
    name = try jsonDictionary.json(atKeyPath: "name")
    employees = try jsonDictionary.json(atKeyPath: "employees")
  }
}

Support custom primitive types by conforming to JSONPrimitiveConvertible

Any type can extend the JSONPrimitiveConvertible protocol in order to allow decoding. For example extending URL: Note that this extension come out of the box :

extension URL: JSONPrimitiveConvertible {

  public typealias JSONType = String

  public static func from(jsonValue: String) -> Self? {
    return self.init(string: jsonValue)
  }

}

let urlDictionary = ["url": "www.google.com"]
let url: URL = try! urlDictionary.json(atKeyPath: "url") // www.google.com

It’s also possible to have an array of JSONPrimitiveConvertible values, for example:

let urlsDictionary = ["urls": ["www.google.com", "www.yahoo.com"]]
let urls: [URL] = try! urlsDictionary.json(atKeyPath: "urls") // [www.google.com, www.yahoo.com]