Mappable Protocol

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 Map object to do your validation:

StaticMappable Protocol

StaticMappable is an alternative to Mappable. It provides developers with a static function that is used by ObjectMapper for object initialization instead of init?(map: Map).

Note: StaticMappable, like Mappable, is a sub protocol of BaseMappable which is where the mapping(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 BaseMappable in 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 to BaseMappable) 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.

ImmutableMappable Protocol

ImmutableMappable provides the ability to map immutable properties. This is how ImmutableMappable differs from Mappable:

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.

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 the <- operator:

birthday <- (map["birthday"], DateTransform())

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 TransformType protocol:

TransformOf

In a lot of situations you can use the built-in transform class TransformOf to quickly perform a desired transformation. TransformOf is 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 String value to an Int you could use TransformOf as follows:

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:

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 List class.

To serialize Swift String, Int, Double and Bool arrays you can use ObjectMapperAdditions/Realm. It'll wrap Swift types into RealmValues that can be stored in Realm's List class.

Note: Generating a JSON string of a Realm Object using ObjectMappers' toJSON function only works within a Realm write transaction. This is because ObjectMapper uses the inout flag in its mapping functions (<-) which are used both for serializing and deserializing. Realm detects the flag and forces the toJSON function to be called within a write block even though the objects are not being modified.