Guide · Open source

How to use SwiftyJSON: read nested JSON in Swift

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

SwiftyJSON is an MIT-licensed Swift library for working with JSON data, the text format apps use to exchange information with servers. It replaces long chains of type casts with short paths such as json[0]["user"]["name"]. This guide shows you how to install it, read values from nested JSON, check for errors, and decide whether it fits your project.

SwiftyJSONSwiftyJSON/SwiftyJSON · ★ 22.9k · MIT Install options & downloads

Quick start

1Check requirements. Confirm your project uses Xcode 16 or later and Swift 6.0 or later, and that your target platform meets the minimums listed in the README.
2Add the dependency. Add https://github.com/SwiftyJSON/SwiftyJSON.git to Package.swift, or add pod 'SwiftyJSON', '~> 4.0' to your Podfile.
3Import the library. Add import SwiftyJSON at the top of the Swift file that reads JSON.
4Create a JSON value. Pass your network data to JSON(data:) using try? so a failed parse returns nil.
5Read values with paths. Walk the structure with subscripts and finish with an optional getter such as .string or a non-optional getter such as .stringValue.
6Handle errors. Use if let for optional getters and inspect the error property when a value is missing.

What problem does SwiftyJSON solve?

Swift is strict about types, which is helpful in most code but awkward with JSON, where values are often implicitly typed. Reading one nested value with JSONSerialization requires several optional casts, and the README describes the result as hard to read.

SwiftyJSON lets you write the lookup as one short path. If a key is missing or a type is wrong, the library stores the error on the result instead of crashing, according to the README.

Install SwiftyJSON with Swift Package Manager or CocoaPods

The README lists Swift Package Manager and CocoaPods as install options. For Swift Package Manager, add the repository URL as a dependency in your Package.swift file, then run swift build. The README lists Xcode 16+ and Swift 6.0+ as requirements.

For CocoaPods, add the pod to your Podfile. The README's example targets iOS 8.0 and uses a version constraint of ~> 4.0.

Swift Package Manager: add https://github.com/SwiftyJSON/SwiftyJSON.git to your dependencies in Package.swift.
CocoaPods: add a pod entry to your Podfile inside your app target.
Carthage and manual integration are also described in the README.

pod 'SwiftyJSON', '~> 4.0'

Parse JSON data and read values

Import the library, then create a JSON value from the data you received from the network. The README uses try? so a failed parse produces nil rather than an error thrown to your code.

Use subscripts to walk into arrays and dictionaries. Finish the path with a getter such as .string, .int or .bool to get an optional value. Use a non-optional getter such as .stringValue when you want a default instead of nil.

Optional getters: .number, .string, .bool, .int return an optional.
Non-optional getters: .intValue, .stringValue, .arrayValue, .dictionaryValue return a default when the value is missing or of the wrong type.
Paths can be passed as an array of keys or as a list of keys in one call.

import SwiftyJSON
let json = try? JSON(data: dataFromNetworking)
if let userName = json[0]["user"]["name"].string {
  // Use the value
}

Handle missing keys and read errors

When a value cannot be read, the optional getter returns nil and the result's error property explains why. The README's example prints result.error in the else branch.

In SwiftyJSON 4.x, errors are represented by the SwiftyJSONError enum, which includes cases such as indexOutOfBounds, notExist, wrongType and invalidJSON. The README notes that the older error types are deprecated.

Check the optional getter with if let before using the value.
Print or log the error property while debugging.
Use the non-optional getter when a default value is acceptable.

let result = json[999999]["wrong_key"]["wrong_name"]
if let userName = result.string {
    // Use the value
} else {
    print(result.error)
}

Loop, set and merge values

You can loop over a JSON value with a for-in statement. The README notes that the key is always a String, even when the JSON is an array, so array indexes arrive as strings.

The README also shows how to set values with subscripts and how to create JSON from Swift values using JSON(...). It lists sections on merging and removing elements, which are covered in the full README.

Dictionary: the loop key is the dictionary key.
Array: the loop key is the index as a string.
Setter: assign a new JSON value to a subscript.

json["name"] = JSON("new-name")
json[0] = JSON(1)

Use SwiftyJSON with networking libraries

The README has dedicated sections for using SwiftyJSON with Alamofire and with Moya. Those sections are not included in the excerpt this page is based on, so check the README for the exact examples.

The README also links a SwiftyJSON Model Generator for producing model code. Use the README for details on its use.

What people use it for

Reading a user's name from a nested web API response in an iOS app
Reading a list of items from a JSON array and mapping each entry to a String
Quickly reading a few values from a large JSON response without writing many optional casts
Maintaining an existing Swift project that already uses SwiftyJSON

Frequently asked questions

How do I install SwiftyJSON?

The README describes two installation options shown on this page: Swift Package Manager, by adding https://github.com/SwiftyJSON/SwiftyJSON.git to Package.swift, and CocoaPods, by adding pod 'SwiftyJSON', '~> 4.0' to your Podfile. Carthage and manual installation are also described there.

What are the requirements for SwiftyJSON?

The README lists Xcode 16+ and Swift 6.0+. It also lists minimum platform versions of iOS 8.0, macOS 10.10, tvOS 9.0 and watchOS 2.0.

Is SwiftyJSON free to use?

SwiftyJSON is released under the MIT licence, as stated in the project information for this directory entry. Check the LICENSE file in the repository for the full terms.

Does SwiftyJSON crash when a key is missing?

The README says SwiftyJSON avoids crashes from missing keys or wrong types, because errors are stored on the result rather than thrown. You can then check the value with an optional getter or inspect the error property.

What is the alternative to SwiftyJSON?

The README discusses Swift's JSONSerialization approach, which needs nested optional casts. Codable is a standard-library option for strongly typed models, though the README excerpt does not compare it directly with SwiftyJSON.

Is SwiftyJSON good for strongly typed models?

The README describes SwiftyJSON as a dynamic lookup approach. If your project needs strongly typed models, the source suggests considering other options, and the SwiftyJSON Model Generator is listed in the README for generating model code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

SwiftyJSON suits Swift developers who read JSON from web APIs and want short, safe access to nested values, and it is a good fit for teams already using it. If you need strongly typed models or you work outside Swift, pick another approach such as Codable or JSONSerialization.

Install options & downloads