flexible JSON to Model converter, specially optimized for immutable properties

What's New

Swift 5


Slightly update for swift 5


Swift Swift Package Manager Build Status Codecov branch

Mappable is a lightweight, flexible, easy-to-use framework to convert JSON to model, specially optimized for immutable property initialization.

struct Flight: Mappable {
    let number: String
    let time: Date
    init(map: Mapper) throws {

        // with the help of @dynamicMemberLookup feature
        number = try
        time   = try map.time()

        // or use the old way
        // number = try map.from("id")
        // time   = try map.from("time")
// Flight(JSONString: json)

A xcode plugin is also provided to genereate implementation automatically.


  • JSON to object by just specifying mapping relationships
  • Optimized for immutable and optional
  • Flexible: easy to mix with manual initailization
  • Compatible types conversion : e.g. a Int property could be initialized with String value
  • Key path support

Why Another?

Most JSON to model libraries cannot handle immutable property initialization well. They require to declare properties with var and nullable types, which break the sprint of Swift and lead to bad code. Mappable was born for solving this problem.

Pros Cons
Codable - Native in Swift
- Automatic (no mapping relationships)
- support 2-direction conversion
- Inflexible
- Doesn't support inherented class
HandyJSON - Automatic (no mapping relationships)
- 2-direction conversion
No immutable properties support
ObjectMapper 2-direction conversion - Immutable properties support is weak*
- Multiple partterns led to chaos
- Missing support for some combinations of types.
SwiftyJSON Not a JSON object convertor.
It's only a convenient tool to deal with JSON data.

* 1) Cannot handle optional conveniently. 2) Doesn't support of compatible types conversion, which fall the whole object for every small mal-format in JSON.

Mappable is highly inspired by ObjectMapper. You could tread Mappable as an improved version of ImmutableMappable in ObjectMapper.


The basics

To support mapping, a type should implement Mappable protocol, which have only an initializer method:

class Country: Mappable {
    let name: String
    let cities: [City]   // struct City: Mappable { ... }
    let atContinent: Continent // enum Continent: Mappable { ... }
    required init(map: Mapper) throws {
        name        = try map.from("name")
        cities      = try map.from("city")
        atContinent = try map.from("location.continent")

You just need write the mapping relationship: a key path for a property. Although these lines are just normal assignment statements, types aren't needed to specified, so you could tread these lines as a special representation of mapping relationships. (You could read the line as "try (to) map (value) from XXX" 😆 )

Then you could initialize a object like this:

// NOTE: these initializer throw errors, you should do error handling
let c = try Country(JSON: jsonDict)
let d = try? Country(JSONString: jsonString)

Supported types

  • Primitive types: Int, Double, String, Bool, URL, Date ...
  • Container types: Array, Dictionary, Set
  • Optional type
  • Enum, Struct, Object
  • Any combination of the types above

Default value

// just use `??`
cities = try map.from("city") ?? []

Optional handling

Optional types won't throw an error even if there's no corresponding date in JSON or the date is in mal-format. A nil will be assigned in this situation.

If you declare a property as an optional, it may mean this data isn't strictly required in JSON. So you wish to get a nil value if there's no data actually.

struct User: Mappable {
    let ID: String
    let summary: String?
    init(map: Mapper) throws {
        ID      = try map.from("id")
        summary = try map.from("summary")
let json = ["id": "a123"]
let user = try! User(JSONObject: json) // It won't crash.

Compatible types conversion

Convert from
Int, Double, Float, CGFloat String
Bool Int, "true", "True", "TRUE", "YES", "false", "False", "FALSE", "NO", "0", "1"
String Int, NSNumber
URL String
Date Double(secondsSince1970), String (RFC 3339, e.g. 2016-06-13T16:00:00+00:00)

More detail at here.

Custom conversion

The content in initializer is just plain assignment, so you could do anything with the data. Use map.getRootValue() and map.getValue(keyPath:) to the get the raw JSON value and do what you want.

For convenient date conversion, there's also a options property in Mapper to set custom date strategy. (More complex example here)


Enums conforming RawRepresentable have a default implementation of Mappable. You just need to declare the conforming of Mappable to your enum types, then it will work.

For enum with associated values, you could do the manual implementation:

enum EnumWithValues: Mappable {
    case a(Int)
    case b(String)
    init(map: Mapper) throws {
        // It could be initialized with a json date like:
        // {"type": "a", value: 123}
        let value = try map.getValue("type", as: String.self)
        switch value {
        case "a":
            self = .a(try map.from("value"))
        case "b":
            self = .b(try map.from("value"))
            throw ErrorType.JSONStructureNotMatchDesired(value, "string a/b")

Class inheritance

class ChildModel: BaseModel {
    let b : Int
    required init(map: Mapper) throws {
        b = try map.from("b")
        try super.init(map: map)

Nested key path

Use key path "AAA.BBB" to map a multi-level path value in JSON:

// let json = """ {"AAA": {"BBB": 1}} """
b = try map.from("AAA.BBB")

// use `n` to get a n-th value in array
// let json = """ {"AAA": [11,22,33]} """
b = try map.from("AAA.`2`") // b = 33

If a normal key contains . naturally, you could use like map.from("a.file", keyPathIsNested: false), to treat the key as a single-level path.


  • for Swift 5 & 4.2 : v1.3+
  • for Swift 4.1 and below : v1.2.2


pod 'Mappable'

Swift Package Manager

.Package(url: "", from: "1.5.0"),


github "leavez/Mappable"


Mappable is available under the MIT license. See the LICENSE file for more info.


  • Swift Tools 4.0.0
View More Packages from this Author


  • None
Last updated: Fri Apr 05 2024 10:18:44 GMT-0900 (Hawaii-Aleutian Daylight Time)