A JSON parser with concise API written in Swift

Maps JSON attributes to different Swift types with just two methods: map and mapArrayOfObjects.
The library can be used on any platform that runs Swift.
Supports casting to optional types.
Indicates if the mapping was successful.
Can be used in Swift apps for Apple devices and in open source Swift programs on other platforms.

Example

The following is an example of mapping a JSON text into a Swift Person structure.

struct Person {
  let name: String
  let age: Int
}

let mapper = JsonSwiftson(json: "{ \"name\": \"Peter\", \"age\": 41 }")

let person = Person(
  name: mapper["name"].map() ?? "",
  age: mapper["age"].map() ?? 0
)

if !mapper.ok { /* report error */ }

Setup (Swift 3.0)

There are four ways you can add JsonSwiftson into your project.

Add the source file (iOS 7+)

Simply add JsonSwiftson.swift file to your Xcode project.

Setup with Carthage (iOS 8+)

Alternatively, add github "evgenyneu/JsonSwiftson" ~> 4.0 to your Cartfile and run carthage update.

Setup with CocoaPods (iOS 8+)

If you are using CocoaPods add this text to your Podfile and run pod install.

use_frameworks!
target 'Your target name'
pod 'JsonSwiftson', git: 'https://github.com/evgenyneu/JsonSwiftson.git', tag: '4.0.0'

Setup with Swift Package Manager

Add the following text to your Package.swift file and run swift build.

import PackageDescription

let package = Package(
    name: "YourPackageName",
    targets: [],
    dependencies: [
        .Package(url: "https://github.com/evgenyneu/JsonSwiftson.git",
                 versions: Version(3,0,0)..<Version(4,0,0))
    ]
)

Legacy Swift versions

Setup a previous version of the library if you use an older version of Swift.

Usage

Add import JsonSwiftson to your source code if you used Carthage or CocoaPods setup.
Create an instance of JsonSwiftson class and supply a JSON text for parsing.

let mapper = JsonSwiftson(json: "{ \"person\": { \"name\": \"Michael\" }}")

Supply the name of JSON attribute you want to get and call the map method. The type of the JSON value is inferred from the context.

let name: String? = mapper["person"]["name"].map()

The example above mapped JSON to an optional String type. One can map to a non-optional by using the ?? operator and supplying a default value.

let name: String = mapper["person"]["name"].map() ?? "Default name"

Finally, check ok property to see if mapping was successful.

if !mapper.ok { /* report error */ }

The ok property will return false if JSON parsing failed or the attribute with the given name was missing. You can allow the attribute to be missing by supplying the optional: true argument to the map method.

let name: String? = mapper["person"]["name"].map(optional: true)

Map to simple Swift types

Use the map method to parse JSON to types like strings, numbers and booleans.

// String
let stringMapper = JsonSwiftson(json: "\"Hello World\"")
let string: String? = stringMapper.map()

// Integer
let intMapper = JsonSwiftson(json: "123")
let int: Int? = intMapper.map()

// Double
let doubleMapper = JsonSwiftson(json: "123.456")
let double: Double? = doubleMapper.map()

// Boolean
let boolMapper = JsonSwiftson(json: "true")
let bool: Bool? = boolMapper.map()

Map property by name

Use square brackets to reach JSON properties by name: mapper["name"].

let mapper = JsonSwiftson(json: "{ \"name\": \"Michael\" }")
let name: String? = mapper["name"].map()

One can use square brackets more than once to reach deeper JSON properties: mapper["person"]["name"].

let mapper = JsonSwiftson(json: "{ \"person\": { \"name\": \"Michael\" }}")
let name: String? = mapper["person"]["name"].map()

Map arrays of simple values

JsonSwiftson will automatically map to the arrays of strings, numbers and booleans.

// String
let stringMapper = JsonSwiftson(json: "[\"One\", \"Two\"]")
let string: [String]? = stringMapper.map()

// Integer
let intMapper = JsonSwiftson(json: "[1, 2]")
let int: [Int]? = intMapper.map()

// Double
let doubleMapper = JsonSwiftson(json: "[1.1, 2.2]")
let double: [Double]? = doubleMapper.map()

// Boolean
let boolMapper = JsonSwiftson(json: "[true, false]")
let bool: [Bool]? = boolMapper.map()

Map an array of objects

Use mapArrayOfObjects with a closure to map array of objects.

struct Person {
  let name: String
  let age: Int
}

let mapper = JsonSwiftson(json:
  "[ " +
    "{ \"name\": \"Peter\", \"age\": 41 }," +
    "{ \"name\": \"Ted\", \"age\": 51 }" +
  "]")

let people: [Person]? = mapper.mapArrayOfObjects { j in
  Person(
    name: j["name"].map() ?? "",
    age: j["age"].map() ?? 0
  )
}

Tip: Use map method instead of mapArrayOfObjects for mapping arrays of simple values like strings, numbers and booleans.

Mapping to Swift structures

struct Person {
  let name: String
  let age: Int
}

let mapper = JsonSwiftson(json: "{ \"name\": \"Peter\", \"age\": 41 }")

let person = Person(
  name: mapper["name"].map() ?? "",
  age: mapper["age"].map() ?? 0
)

Check if mapping was successful

Verify the ok property to see if mapping was successful. Mapping fails for incorrect JSON and type casting problems.

Note: map and mapArrayOfObjects methods always return nil if mapping fails.

let successMapper = JsonSwiftson(json: "\"Correct type\"")
let string: String? = successMapper.map()
if successMapper.ok { print("👏👏👏") }

let failMapper = JsonSwiftson(json: "\"Wrong type\"")
let number: Int? = failMapper.map()
if !failMapper.ok { print("🐞") }

Allow missing values

Mapping fails by default if JSON value is null or attribute is missing.

Tip: Pass optional: true parameter to allow missing JSON attributes and null values.

let mapper = JsonSwiftson(json: "{ }")
let string: String? = mapper["name"].map(optional: true)
if mapper.ok { print("👏👏👏") }

Allow missing objects

Use map method with optional: true parameter and a closure to allow empty objects.

struct Person {
  let name: String
  let age: Int
}

let mapper = JsonSwiftson(json: "null") // empty

let person: Person? = mapper.map(optional: true) { j in
  Person(
    name: j["name"].map() ?? "",
    age: j["age"].map() ?? 0
  )
}

if mapper.ok { print("👏👏👏") }

Tip: map to a non-optional type

Use ?? operator after the mapper if you need to map to a non-optional type like let number: Int.

let numberMapper = JsonSwiftson(json: "123")
let number: Int = numberMapper.map() ?? 0

let arrayMapper = JsonSwiftson(json: "[1, 2, 3]")
let numbers: [Int] = arrayMapper.map() ?? []