HandyJSON: Swift JSON Mapping Without NSObject or Mapping Functions

What HandyJSON Solves and Who It Is For

HandyJSON addresses a specific annoyance in Swift JSON handling: the requirement, common in other libraries, that model classes inherit from NSObject or implement a mapping function. For developers working with pure Swift structs or classes, that inheritance is a design constraint. HandyJSON removes it. The README states that it does not require objects to inherit from NSObject and does not require a mapping function. Instead it uses reflection and writes values directly to memory. The target audience is iOS and macOS developers who want to keep their model types plain Swift and still get JSON conversion with minimal boilerplate. It also supports enums, optionals, and nested types, which covers most typical model definitions.

The Mechanism: Reflection and Direct Memory Writes

HandyJSON's approach is unusual. Instead of using KVC or asking you to define mappings, it relies on the memory layout rules of Swift. The README says it is 'totally depend on the memory layout rules inferred from Swift runtime code.' When deserializing, it reflects on the type's properties, finds their offsets in memory, and writes the JSON values directly into those locations. This is why it can work with structs and classes that do not inherit from NSObject. The trade-off is fragility. The library is coupled to Swift's internal memory layout, which can change between Swift versions. The README acknowledges this by saying the authors are 'watching it and will follow every bit if it changes.' That is a honest warning, but it also means you are betting on the library being updated when Swift changes. The last push was on 2024-03-08, and the most recent GitHub release dates from 2018.

Getting It Running: Installation and Version Pinning

Installation follows standard dependency manager routes. With CocoaPods, add `pod 'HandyJSON', '~> 5.0.2'` to your Podfile and run `pod install`. With Carthage, add `github "alibaba/HandyJSON" ~> 5.0.2` to your Cartfile. Manual integration is also possible: add the project as a submodule, drag HandyJSON.xcodeproj into your project, and embed the framework that matches your platform. Version pinning is critical. The README gives exact version requirements: for Swift 5.0/5.1, use version 5.0.2; for Swift 4.2, use 4.2.0; for Swift 4.0, use 4.1.1 or later; for Swift 3.x, use 1.8.0 or later. Ignoring these pins is a likely failure mode. The repository also notes a crash on iOS 15 beta3, with version 5.0.4-beta as a fix, so if you target iOS 15, that beta is the version to test.

Deserialization and Serialization in Practice

The README gives clear examples. For deserialization, a class conforms to HandyJSON and implements a required empty initializer. For example, `class BasicTypes: HandyJSON { var int: Int = 2; required init() {} }`, then `let object = BasicTypes.deserialize(from: jsonString)` returns an optional. Structs get the empty initializer for free, but if you define a designated initializer, you must declare an empty one explicitly. For enums, the type must conform to HandyJSONEnum. Serialization is symmetric: `object.toJSON()` returns a dictionary, `object.toJSONString()` returns a JSON string, and `toJSONString(prettyPrint: true)` gives pretty output. The library supports optional, implicitly unwrapped optional, array, dictionary, and nested types. It also does type-adaption, meaning a string JSON field can map to an int property and vice versa. That is a convenience, but it can also mask data type mismatches in your JSON, so you should be aware of it.

A Real Limitation: The Swift Runtime Dependency

The biggest limitation is the reliance on Swift runtime memory layout. The README is explicit: the library is 'totally depend on the memory layout rules inferred from Swift runtime code.' That means any change in Swift's internal layout can break deserialization silently. The README's version table stops at Swift 5.0/5.1, and the most recent GitHub release dates from 2018. If you use a modern Swift version, you may hit crashes or incorrect behavior. The README's note about an iOS 15 beta3 crash points to a 5.0.4-beta build rather than a stable release. For production apps targeting current iOS and Swift, this is a risk. The wrong tool would be any project that requires long-term stability or that cannot afford to pin to an old Swift toolchain.

Alternative: Codable and Its Different Approach

The standard alternative is Swift's built-in Codable protocol. Codable works differently: it does not use reflection or direct memory writes. Instead, you conform your type to Codable and optionally implement `CodingKeys` to map JSON keys to property names. The compiler synthesizes the encoding and decoding methods. This is a compile-time approach, not a runtime one, so it does not depend on Swift's memory layout. The trade-off is that you must add conformance, and for custom key names you write a `CodingKeys` enum. HandyJSON, by contrast, uses property names automatically and supports type-adaption without extra code. Codable is safer for future Swift versions because it is part of the standard library. If you are starting a new project, Codable is the more maintainable choice. HandyJSON makes sense only if you have a legacy codebase that already uses it or if you need to avoid NSObject inheritance at all costs.

Maintenance and Upgrade Cost

The repository's last push was on 2024-03-08, and the latest release is 4.1.3, though the README references 5.0.2 and 5.0.4-beta. This discrepancy suggests the release tags are not consistently updated. The license is listed as NOASSERTION, which means the repository does not declare a standard license. That is a legal concern: you cannot assume you have permission to use it without checking the actual license file in the repo. Verify the LICENSE file before using it commercially. Upgrade cost is high: every Swift version change may require a HandyJSON update or a workaround. If you adopt HandyJSON, you must pin your Swift version and be prepared to fork the library if issues arise. For a new project, the maintenance burden likely outweighs the convenience.

Editorial conclusion

Adopt HandyJSON if you need to map JSON to pure Swift structs or classes without NSObject inheritance and you can accept a library whose last GitHub release dates from 2018 and depends on Swift runtime memory layout. Do not adopt it if you need active maintenance, Swift 6 compatibility, or a solution that avoids fragile runtime internals. Before adopting, verify that your target Swift version matches the pinned release (5.0.2 for Swift 5.0/5.1, 4.2.0 for Swift 4.2) and test on the iOS version you support, especially iOS 15 beta, where the README warns of a crash that version 5.0.4-beta addresses.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes