Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Functional JSON parsing library for Swift

Subscribe to updates I use Argo

Statistics on Argo

Number of watchers on Github 3305
Number of open issues 18
Average time to close an issue 16 days
Main language Swift
Average time to merge a PR 6 days
Open pull requests 28+
Closed pull requests 32+
Last commit over 2 years ago
Repo Created over 5 years ago
Repo Last Updated about 2 years ago
Size 1.19 MB
Homepage https://thoughtbo...
Organization / Authorthoughtbot
Latest Releasev4.1.2
Page Updated
Do you use Argo? Leave a review!
View open issues (18)
View Argo activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating Argo for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)

Argo Carthage compatible

Argo is a library that lets you extract models from JSON or similar structures in a way that's concise, type-safe, and easy to extend. Using Argo, you won't need to write validation code to ensure that incoming data is of the right type, or to make sure required data fields aren't turning up empty. Argo uses Swift's expressive type system to do that for you, and reports back explicit failure states in case it doesn't find what you've told it to expect.

Argo is the Greek word for swift and the name of the ship used by Jason, son of Aeson, of the Argonauts. Aeson is the JSON parsing library in Haskell that inspired Argo, much like Aeson inspired his son Jason.

Version Compatibility

Note that we're aggressive about pushing master forward along with new versions of Swift. Therefore, we highly recommend against pointing at master, and instead using one of the releases we've provided.

Here is the current Swift compatibility breakdown:

Swift Version Argo Version
4.X master
3.X 4.X
2.2, 2.3 3.X
2.0, 2.1 2.X
1.2 - 2.0 1.X
1.1 0.3.X



Add the following to your Cartfile:

github "thoughtbot/Argo"

Then run carthage update.

Follow the current instructions in Carthage's README for up to date installation instructions.

Note that if you are using newer versions of Argo, you will need to link both Argo.framework and Runes.framework into your app.


Add the following to your Podfile:

pod 'Argo'

You will also need to make sure you're opting into using frameworks:


Then run pod install with CocoaPods 0.36 or newer.

Git Submodules

I guess you could do it this way if that's your thing.

Add this repo as a submodule, and add the project file to your workspace. You can then link against Argo.framework for your application target.

You will need to do the same for Runes if you are using newer versions of Argo.

Usage tl;dr:

Please note: the example below requires an additional, external module named Curry which lets us use the curry function to curry User.init.

It also imports Runes, which is a dependency of Argo in newer versions. If you are using an older version of Argo, you might not need that import.

import Argo
import Curry
import Runes

struct User {
  let id: Int
  let name: String
  let email: String?
  let role: Role
  let companyName: String
  let friends: [User]

extension User: Decodable {
  static func decode(_ json: JSON) -> Decoded<User> {
    return curry(User.init)
      <^> json <| "id"
      <*> json <| "name"
      <*> json <|? "email" // Use ? for parsing optional values
      <*> json <| "role" // Custom types that also conform to Decodable just work
      <*> json <| ["company", "name"] // Parse nested objects
      <*> json <|| "friends" // parse arrays of objects

// Wherever you receive JSON data:

let json: Any? = try? NSJSONSerialization.JSONObjectWithData(data, options: [])

if let j: Any = json {
  let user: User? = decode(j)

For more information, see the Documentation


See the CONTRIBUTING document. Thank you, contributors!


Argo is Copyright (c) 2015 thoughtbot, inc. It is free software, and may be redistributed under the terms specified in the LICENSE file.



Argo is maintained and funded by thoughtbot, inc. The names and logos for thoughtbot are trademarks of thoughtbot, inc.

We love open source software! See our other projects or look at our product case studies and hire us to help build your iOS app.

Argo open issues Ask a question     (View All Issues)
  • over 3 years Supporting XML Parsing
  • over 3 years Error when specifying type in swift 3
  • over 3 years Decoding OptionSets
  • over 3 years no such module 'Runes'
  • over 3 years Nested dictionary with dynamic keys
  • almost 4 years Problem with the way we use .optional
  • almost 4 years Relationships up the chain
  • over 4 years Document the use of the `alternate` operator
  • over 4 years Automate CocoaPods releases
  • over 4 years Higher order functions using `rethrows`?
  • almost 5 years Make decoding lazy
Argo open pull requests (View All Pulls)
  • Enable bitcode for all targets except Mac
  • Remove reduce usage for better performance
  • Add a Boolean case to JSON
  • Change Argo to lazy parse json
  • Add alternative named instance method on Decoded
  • Add inline documentation for the public interface
  • [RFC]: Remove Optional versions of `<|` operators
  • Add Relationship documentation
  • Make DecodeError Hashable
  • Documentation for common gotchas
  • WIP: Update Argo for Swift 3
  • WIP: Improve speed with multithreading
  • Set SWIFT_VERSION = 2.3 (for Xcode 8)
  • Better Swift 2.3/Xcode 8 support
  • Update for Swift 3 & Xcode 8 b3
  • Use Semigroup type to coalesce multiple errors
  • Updates for newest Swift beta
  • Try to fix how Runes and Curry are included so things build.
  • A missing key in an embedded type should be a failure
  • Bring back .optional how it originally was
  • [Don't merge] Argo can't be used with SwiftPM
  • Add `import CoreFoundation` for `CFBooleanGetTypeID` and `CFGetTypeID`
  • Improve the way we detect Boolean values
  • Update README.md
  • Replace 'Generator' with 'Iterator'
  • fix typos using misspell
  • An attempt at "Lazy" JSON parsing
  • Rename JSON to Value
Argo questions on Stackoverflow (View All Questions)
  • Argo Error: Ambiguous reference to member ‘curry’
  • Simple Example - Argo and Swift 2
  • Parsing JSON with Argo on Swift
  • Using Swift Argo framework : Could not find an overload for '<*>'
  • Using Alamofire & Argo: Could not find member 'None'
  • Parsing JSON with Argo
  • Java argo JSON how to?
  • Display visibility in Argo UML
Argo list of languages used
Argo latest release notes
v4.1.2 4.1.2: The Iteration Generation
  • [FIXED]: Now using Iterator instead of Generator in our definition of decode for Collections. This was renamed in Swift 3.0, and honestly I'm not positive how this was compiling the way it was.
v4.1.1 4.1.1: An Actual Useable Library
  • [FIXED]: Fixed compilation when building via Swift Package Manager
v4.1.0 4.1: Optional Packages
  • [NEW]: Swift Package Manager Support (Gordon Fontenot)
  • [NEW]: Re-introduced Decoded.optional with better, simplified behavior (Tony DiPasquale)
  • [FIXED]: Use NSNumber transformation properties instead of casting to decode number values. This now prevents a crash that could occur with Swift 3.0.1 (Gordon Fontenot)
Other projects in Swift