Easily load JSON objects and decode them into structs or classes
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
Example.playground
JSONUtilities.xcodeproj
Metadata
NonSwiftPackageManagerTests
Sources/JSONUtilities
Tests
.gitignore
.hound.yml
.swift-version
.swiftlint.yml
.travis.yml
CHANGELOG.md
JSONUtilities.podspec
LICENSE
Package.swift
README.md
codecov.yml

README.md

JSONUtilities

Build Status codecov.io Carthage Compatible Swift Version

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]