Simple JSON Object mapping written in Swift
ObjectMapper is a framework written in Swift that makes it easy for you to convert your model objects (classes and structs) to and from JSON.
To support mapping, a class or struct just needs to implement the
Mappableprotocol which includes the following functions:
swift init?(map: Map) mutating func mapping(map: Map)ObjectMapper uses the
operator to define how each member variable maps to and from JSON.class User: Mappable { var username: String? var age: Int? var weight: Double! var array: [Any]? var dictionary: [String : Any] = [:] var bestFriend: User? // Nested User object var friends: [User]? // Array of Users var birthday: Date?required init?(map: Map) { } // Mappable func mapping(map: Map) { username
Once your class implements
Mappable, ObjectMapper allows you to easily convert to and from JSON.Convert a JSON string to a model object:
swift let user = User(JSONString: JSONString)Convert a model object to a JSON string:
swift let JSONString = user.toJSONString(prettyPrint: true)Alternatively, the
Mapper.swiftclass can also be used to accomplish the above (it also provides extra functionality for other situations):swift // Convert JSON String to Model let user = Mapper().map(JSONString: JSONString) // Create JSON String from Model let JSONString = Mapper().toJSONString(user, prettyPrint: true)ObjectMapper can map classes composed of the following types: -
Int-Bool-Double-Float-String-RawRepresentable(Enums) -Array-Dictionary-Object-Array-Array>-Set-Dictionary-Dictionary>- Optionals of all the above - Implicitly Unwrapped Optionals of the above
MappableProtocol
mutating func mapping(map: Map)This function is where all mapping definitions should go. When parsing JSON, this function is executed after successful object creation. When generating JSON, it is the only function that is called on the object.
init?(map: Map)This failable initializer is used by ObjectMapper for object creation. It can be used by developers to validate JSON prior to object serialization. Returning nil within the function will prevent the mapping from occuring. You can inspect the JSON stored within the
Mapobject to do your validation:swift required init?(map: Map){ // check if a required "name" property exists within the JSON. if map.JSON["name"] == nil { return nil } }
StaticMappableProtocolStaticMappableis an alternative toMappable. It provides developers with a static function that is used by ObjectMapper for object initialization instead ofinit?(map: Map).Note:
StaticMappable, likeMappable, is a sub protocol ofBaseMappablewhich is where themapping(map: Map)function is defined.
static func objectForMapping(map: Map) -> BaseMappable?ObjectMapper uses this function to get objects to use for mapping. Developers should return an instance of an object that conforms to
BaseMappablein this function. This function can also be used to: - validate JSON prior to object serialization - provide an existing cached object to be used for mapping - return an object of another type (which also conforms toBaseMappable) to be used for mapping. For instance, you may inspect the JSON to infer the type of object that should be used for mapping (see examples in ClassClusterTests.swift)If you need to implement ObjectMapper in an extension, you will need to adopt this protocol instead of
Mappable.
ImmutableMappableProtocolImmutableMappableprovides the ability to map immutable properties. This is howImmutableMappablediffers fromMappable:
ImmutableMappable | Mappable |
---|---|
Properties | |
let id: Int let name: String? |
var id: Int! var name: String? |
JSON -> Model | |
init(map: Map) throws { id = try map.value("id") name = try? map.value("name") } |
mutating func mapping(map: Map) { id |
Model -> JSON | |
func mapping(map: Map) { id >>> map["id"] name >>> map["name"] } |
mutating func mapping(map: Map) { id |
Initializing | |
try User(JSONString: JSONString) |
User(JSONString: JSONString) |
init(map: Map) throws
This throwable initializer is used to map immutable properties from the given
Map. Every immutable property should be initialized in this initializer.
This initializer throws an error when: -
Mapfails to get a value for the given key -
Mapfails to transform a value using
Transform
ImmutableMappableuses
Map.value(_:using:)method to get values from the
Map. This method should be used with the
trykeyword as it is throwable.
Optionalproperties can easily be handled using
try?.
init(map: Map) throws { name = try map.value("name") // throws an error when it fails createdAt = try map.value("createdAt", using: DateTransform()) // throws an error when it fails updatedAt = try? map.value("updatedAt", using: DateTransform()) // optional posts = (try? map.value("posts")) ?? [] // optional + default value surname = try? map.value("surname", default: "DefaultSurname") // optional + default value as an argument }
mutating func mapping(map: Map)
This method is where the reverse transform is performed (model to JSON). Since immutable properties cannot be mapped with the
operator, developers have to define the reverse transform using the>>>operator.mutating func mapping(map: Map) { name >>> map["name"] createdAt >>> (map["createdAt"], DateTransform()) updatedAt >>> (map["updatedAt"], DateTransform()) posts >>> map["posts"] }Easy Mapping of Nested Objects
ObjectMapper supports dot notation within keys for easy mapping of nested objects. Given the following JSON String:
json "distance" : { "text" : "102 ft", "value" : 31 }You can access the nested objects as follows:swift func mapping(map: Map) { distance Nested keys also support accessing values from an array. Given a JSON response with an array of distances, the value could be accessed as follows:swift distance If you have a key that contains., you can individually disable the above feature as follows:swift func mapping(map: Map) { identifier When you have nested keys which contain., you can pass the custom nested key delimiter as follows (#629):swift func mapping(map: Map) { appName com.myapp.name", delimiter: "->"] }Custom Transforms
ObjectMapper also supports custom transforms that convert values during the mapping process. To use a transform, simply create a tuple with
map["field_name"]and the transform of your choice on the right side of theoperator:swift birthday The above transform will convert the JSON Int value to an Date when reading JSON and will convert the Date to an Int when converting objects to JSON.You can easily create your own custom transforms by adopting and implementing the methods in the
TransformTypeprotocol: ```swift public protocol TransformType { associatedtype Object associatedtype JSONfunc transformFromJSON(_ value: Any?) -> Object? func transformToJSON(_ value: Object?) -> JSON?} ```
TransformOf
In a lot of situations you can use the built-in transform class
TransformOfto quickly perform a desired transformation.TransformOfis initialized with two types and two closures. The types define what the transform is converting to and from and the closures perform the actual transformation.For example, if you want to transform a JSON
Stringvalue to anIntyou could useTransformOfas follows: ```swift let transform = TransformOf(fromJSON: { (value: String?) -> Int? in // transform value from String? to Int? return Int(value!) }, toJSON: { (value: Int?) -> String? in // transform value from Int? to String? if let value = value { return String(value) } return nil })id <- (map["id"], transform)
Here is a more condensed version of the above:swift id <- (map["id"], TransformOf(fromJSON: { Int($0!) }, toJSON: { $0.map { String($0) } })) ```Subclasses
Classes that implement the
Mappableprotocol can easily be subclassed. When subclassing mappable classes, follow the structure below:class Base: Mappable { var base: String?required init?(map: Map) { } func mapping(map: Map) { base
Make sure your subclass implementation calls the right initializers and mapping functions to also apply the mappings from your superclass.
Generic Objects
ObjectMapper can handle classes with generic types as long as the generic type also conforms to
Mappable. See the following example: ```swift class Result: Mappable { var result: T?required init?(map: Map){}
func mapping(map: Map) { result
}
let result = Mapper>().map(JSON) ```
Mapping Context
The
Mapobject which is passed around during mapping, has an optionalMapContextobject that is available for developers to use if they need to pass information around during mapping.To take advantage of this feature, simply create an object that implements
MapContext(which is an empty protocol) and pass it intoMapperduring initialization. ```swift struct Context: MapContext { var importantMappingInfo = "Info that I need during mapping" }class User: Mappable { var name: String?
required init?(map: Map){}
func mapping(map: Map){ if let context = map.context as? Context { // use context to make decisions about mapping } }
}
let context = Context() let user = Mapper(context: context).map(JSONString) ```
ObjectMapper + Alamofire
If you are using Alamofire for networking and you want to convert your responses to Swift objects, you can use AlamofireObjectMapper. It is a simple Alamofire extension that uses ObjectMapper to automatically map JSON response data to Swift objects.
ObjectMapper + Realm
ObjectMapper and Realm can be used together. Simply follow the class structure below and you will be able to use ObjectMapper to generate your Realm models:
class Model: Object, Mappable { dynamic var name = ""required convenience init?(map: Map) { self.init() } func mapping(map: Map) { name
If you want to serialize associated RealmObjects, you can use ObjectMapper+Realm. It is a simple Realm extension that serializes arbitrary JSON into Realm's
Listclass.To serialize Swift
String,Int,DoubleandBoolarrays you can use ObjectMapperAdditions/Realm. It'll wrap Swift types into RealmValues that can be stored in Realm'sListclass.Note: Generating a JSON string of a Realm Object using ObjectMappers'
toJSONfunction only works within a Realm write transaction. This is because ObjectMapper uses theinoutflag in its mapping functions () which are used both for serializing and deserializing. Realm detects the flag and forces thetoJSONfunction to be called within a write block even though the objects are not being modified.Projects Using ObjectMapper
Mappableand
ImmutableMappablecode
Json4Swift - Supports generating
ImmutableMappablestructs online (no plugins needed)
JSON to Model - Template based MacOS app which generates structs with customisation. ⬇️Download App
If you have a project that utilizes, extends or provides tooling for ObjectMapper, please submit a PR with a link to your project in this section of the README.
throws
Contributions are very welcome 👍😃.
Before submitting any pull request, please ensure you have run the included tests and they have passed. If you are including new functionality, please write test cases for it as well.
ObjectMapper can be added to your project using CocoaPods 0.36 or later by adding the following line to your
Podfile:
pod 'ObjectMapper', '~> 3.5' (check releases to make sure this is the latest version)
If you're using Carthage you can add a dependency on ObjectMapper by adding it to your
Cartfile:
github "tristanhimmelman/ObjectMapper" ~> 3.5 (check releases to make sure this is the latest version)
To add ObjectMapper to a Swift Package Manager based project, add:
.package(url: "https://github.com/tristanhimmelman/ObjectMapper.git", .upToNextMajor(from: "4.1.0")),
to your
Package.swiftfiles
dependenciesarray.
Otherwise, ObjectMapper can be added as a submodule:
cd-ing into your top-level project directory, and entering the command
git submodule add https://github.com/tristanhimmelman/ObjectMapper.git
ObjectMapperfolder, and drag
ObjectMapper.xcodeprojinto the file navigator of your app project.
ObjectMapper.frameworkmatches that of the application target.
ObjectMapper.framework.
+button at the top left of the panel and select "New Copy Files Phase". Rename this new phase to "Copy Frameworks", set the "Destination" to "Frameworks", and add
ObjectMapper.framework.