# JSONModel: An Objective-C JSON mapping library frozen in 2016 > JSONModel automates JSON-to-model conversion for Apple platforms with key mapping, cascading, and custom transformers. It has been unmaintained since October 2016, which makes it a risky choice for new projects. **jsonmodel/jsonmodel** — GitHub describes it as Magical Data Modeling Framework for JSON - allows rapid creation of smart data models. You can use it in your iOS, macOS, watchOS and tvOS apps.. The repository metadata lists Objective-C as its primary language. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README. - Repository: https://github.com/jsonmodel/jsonmodel - Stars: 6,801 · Forks: 1,047 - Language: Objective-C - License: MIT - Published: 2026-08-13 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/jsonmodel-jsonmodel ## What JSONModel solves and who it targets JSONModel addresses the boilerplate of converting JSON payloads into typed Objective-C objects. Without it, a developer writes manual parsing code for every key, handles type conversions, and manages nested dictionaries. JSONModel automates this by inspecting the model class properties and the JSON input at runtime. The target audience is Objective-C developers building apps for iOS, macOS, watchOS, or tvOS who want to define a model class and get populated instances with a single initializer call. The README's example shows a CountryModel subclass with properties like NSInteger id and NSString *country, then a one-line init with an error pointer. That is the core promise: declare properties, init with JSON, and the framework does the rest. It is not a Swift library, and it does not support Swift's Codable protocol. It is a pre-Swift solution, which is a key consideration for any current project. ## The mechanism: runtime introspection and property mapping JSONModel works by using Objective-C runtime features to enumerate the properties of a JSONModel subclass. For each property, it looks up the corresponding key in the JSON dictionary. The README shows that property names match JSON keys by default. For example, a property named country maps to the JSON key "country". Type conversion happens automatically: the documentation states that a JSON string for an integer property is converted to an int, and a JSON number for an NSString property is converted to a string. This is not a compile-time mechanism; it is runtime introspection. The framework also supports cascading, where a property of type ProductModel is populated from a nested JSON object. Collections work by declaring a protocol in angle brackets, like NSArray *products, which is not the same as Objective-C generics but is required for JSONModel to recognize the element type. This runtime approach reduces code but adds a layer of indirection that can hide mapping errors until runtime. ## Installation and the three supported methods The README lists three installation methods. CocoaPods is the simplest: add pod 'JSONModel' to your Podfile. Carthage users add github "jsonmodel/jsonmodel" to their Cartfile. For manual installation, you download the repository, copy the JSONModel sub-folder into your Xcode project, and link your app to SystemConfiguration.framework. The manual method is the least convenient because it requires you to track the source files yourself and manage the framework dependency. CocoaPods and Carthage give you versioned dependencies, but the last release is v1.7.0 from October 2016. That means any new installation pulls a library that predates the iPhone X, let alone recent iOS versions. There is no Swift Package Manager support mentioned, which is a notable gap for modern tooling. If you use SPM, you cannot adopt JSONModel without a workaround. ## Key mapping and snake_case support save real code One of the strongest features is the JSONKeyMapper. The README shows how to map flat model properties to nested JSON paths. For instance, a property named productName can map to "orderDetails.name" using a dictionary in initWithModelToJSONDictionary. This eliminates manual traversal of nested dictionaries. There is also a built-in mapper for snake_case JSON: +[JSONKeyMapper mapperForSnakeCase] automatically converts order_id to orderId. This is a concrete, time-saving feature. The key mapper is a class method you override in your model. It returns a JSONKeyMapper instance that defines the bidirectional mapping. This works for both parsing and exporting. The export direction is covered by toDictionary and toJSONString, which use the same key mapper. That symmetry is useful when you need to send data back to a server. ## Optional, ignored, and scalar properties: flexibility with caveats JSONModel provides protocols to mark properties as Optional or Ignore. A property declared as NSString *name can be missing or null in the JSON without causing an error. A property marked is completely skipped by JSONModel. For scalar types like NSInteger, you cannot use the Optional protocol because protocols do not apply to primitive types. Instead, the README shows overriding +propertyIsOptional: to return YES for a specific property name. This is a workaround, and it is per-property, which gets verbose for many optional scalars. The Ignore protocol is useful for properties that are derived or not part of the API. However, the documentation is thin on what happens when a required property is missing. The basic example initializes with an NSError pointer, but the README does not state whether the error is populated on failure or whether the model is nil. That lack of clarity is a risk for error handling. ## Custom transformers and getters: extending the framework JSONModel allows you to extend JSONValueTransformer with custom methods. The README gives an example of converting an NSString to NSDate using a specific date format. You define a category on JSONValueTransformer with methods like NSDateFromNSString: and JSONObjectFromNSDate:. The framework calls these based on the property type and the JSON value type. This is a clean extension point for date handling, which is a common pain point in JSON parsing. Additionally, you can define custom setter methods like setLocaleWithNSString: and setLocaleWithNSDictionary: to handle multiple JSON representations for a single property. The reverse direction is a method like JSONObjectForLocale. This gives you fine-grained control without leaving the JSONModel paradigm. However, these custom methods rely on naming conventions, which can be fragile if you mistype a method name. The framework does not appear to validate that the custom methods exist until runtime. ## The fatal flaw: no maintenance since 2016 The repository's last push was on October 7, 2016, and the last release is v1.7.0 from the same day. There is no indication of any activity since then. The README links to a CHANGELOG.md, but the provided material does not include its contents. This means there are no documented changes for the last eight years. Objective-C itself is still supported by Apple, but the ecosystem has moved to Swift. JSONModel has no Swift interface, so you cannot use it from Swift without a bridging header, and even then, the dynamic nature of the library may conflict with Swift's type safety. The lack of maintenance is a hard blocker for new projects. There is no guarantee that JSONModel works with the latest Xcode or the latest SDKs. For example, changes in Objective-C runtime behavior or in Foundation could break the introspection logic. The README does not mention any known issues, but the absence of updates is a clear signal. ## Alternatives: Mantle, RestKit, and Swift Codable If you need an Objective-C JSON mapping library, Mantle is a direct alternative. Mantle uses a similar model-subclass approach but with a different mechanism: it requires you to implement +JSONKeyPathsByPropertyKey to define the mapping. It does not use runtime introspection for type conversion; instead, you use transformers for non-standard types. Mantle has a more explicit API, which some developers prefer for clarity. RestKit is a heavier alternative that includes networking and object mapping, but it is also largely unmaintained. For Swift projects, the standard solution is Codable. Codable is a compile-time protocol, not a runtime mapping, which means errors are caught at compile time. It does not have automatic snake_case conversion, but you can implement CodingKeys. The key difference is that Codable is part of the Swift standard library, so there is no third-party dependency. If you are starting a new app today, Codable is the obvious choice. JSONModel is only relevant if you are locked into an old Objective-C codebase. ## Conclusion Adopt JSONModel only if you are maintaining an existing Objective-C codebase that already depends on it and you cannot migrate to Swift's Codable or a maintained alternative. New projects should avoid it: the library has no commits since October 2016, no support for Swift native types, and no clear migration path. Before adopting it in a legacy app, verify that the key mapper and custom transformer APIs still compile with your current Xcode version, and check whether the MIT license terms match your distribution requirements. If you need a maintained Objective-C JSON mapper, consider Mantle or RestKit, which have more recent activity. If you can move to Swift, Codable is the standard and removes the need for a third-party library. Do not expect bug fixes or new features from JSONModel. ## FAQ ### What is JSONModel? It is an Objective-C framework for Apple platform apps that populates model objects from JSON. You subclass JSONModel, declare properties named after the JSON keys, and the framework converts and fills them, so the implementation file stays empty. ### How do I add JSONModel without CocoaPods? The manual route is three steps: download the JSONModel repository, copy the JSONModel sub-folder into your Xcode project, and link your app to SystemConfiguration.framework. That route carries no version marker, so which revision a build shipped with is up to you to track. ### How do I map a property to a nested JSON key? Override + (JSONKeyMapper *)keyMapper and build a mapper with initWithModelToJSONDictionary:, using dotted paths such as orderDetails.price.usd as the values. For payloads in snake_case, the same method can return [JSONKeyMapper mapperForSnakeCase] instead. ### How do I convert a JSONModel object back to JSON? Call toDictionary for an NSDictionary or toJSONString for a string. Values for types the framework does not know, such as NSDate, are supplied by a category on JSONValueTransformer whose method names encode the direction, for example NSDateFromNSString and JSONObjectFromNSDate. ## Sources - [Official README](https://github.com/jsonmodel/jsonmodel#readme) - [Project repository](https://github.com/jsonmodel/jsonmodel) - [Release notes](https://github.com/jsonmodel/jsonmodel/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jsonmodel-jsonmodel