KakaJSON

KakaJSON supports deeply nested JSON structures, including arrays, dictionaries, and sets, as long as the nested types also conform to Convertible.

Nested Objects and Collections

struct Book: Convertible {
    var name: String = ""
    var price: Double = 0.0
}

struct Person: Convertible {
    var name: String = ""
    var car: Car?            // Optional nested object
    var books: [Book]?       // Array of nested objects
    var dogs: [String: Dog]? // Dictionary of nested objects
}

Default Values in Nested Models

If a property in your model is initialized with a default value, KakaJSON will preserve that value if the corresponding key is missing from the JSON, rather than overwriting it with a new instance.

struct Person: Convertible {
    var name: String = ""
    // If 'car' is missing in JSON, this default instance is kept
    var car: Car = Car(name: "Bently", price: 106.5)
}

When using classes that conform to Convertible, you can override kj_modelKey(from:) to change how keys are resolved for a subclass.

• To extend mapping: Call super.kj_modelKey(from: property) within your override to maintain the parent's mapping logic while adding new rules.
• To completely replace mapping: Implement the method without calling super to ignore the parent's configuration for that specific subclass.

class Person: Convertible {
    var name: String = ""
    required init() {}
    
    func kj_modelKey(from property: Property) -> ModelPropertyKey {
        return property.name == "name" ? "_name_" : property.name
    }
}
 
class Student: Person {
    var score: Int = 0
    
    override func kj_modelKey(from property: Property) -> ModelPropertyKey {
        // `score` -> `_score_`, but `name` still uses Person's logic via super
        return property.name == "score" ? "_score_" : super.kj_modelKey(from: property)
    }
}

When defining models that conform to Convertible, follow these rules based on the type:

Structs

• Simple Structs: If all properties have default values, no explicit initializer is needed.
• Manual Initializers: If properties do not have default values, you must implement an init() to satisfy the protocol requirements.

Classes

• Required Initializer: You must implement required init().
• NSObject Inheritance: If your class inherits from NSObject, you must use required override init().

Best Practices

• Immutability: Avoid using let for properties you want KakaJSON to populate in release mode. Instead, use private(set) var to allow the library to set the value while keeping it read-only for consumers.

// Struct with default values
struct Dog: Convertible {
    var weight: Double = 0.0
    var name: String = ""
}

// Class with NSObject inheritance
class Person: NSObject, Convertible {
    var name: String = ""
    var age: Int = 0
    required override init() {}
}

// Recommended way to handle 'let' properties
struct Cat: Convertible {
    private(set) var weight: Double = 0.0
    let name: String = ""
}

Instead of implementing kj_modelKey(from:) on every model, you can use ConvertibleConfig to define mapping rules centrally.

Global Configuration

Sets a rule for all types conforming to Convertible.

ConvertibleConfig.setModelKey { property in
    property.name.kj.underlineCased()
}

Local (Type-Specific) Configuration

Sets a rule for specific types. This also affects subclasses.

ConvertibleConfig.setModelKey(for: [Person.self, Car.self]) { property in
    property.name.kj.underlineCased()
}

Resolution Order

When KakaJSON looks for a key mapping, it follows this priority:

1. The model's own kj_modelKey(from:) implementation.
2. ConvertibleConfig for the specific type.
3. ConvertibleConfig for the type's superclass.
4. ... (continuing up the inheritance chain)
5. The global ConvertibleConfig.

// Global config
ConvertibleConfig.setModelKey { property in
    property.name.kj.underlineCased()
}

// Config of Person
ConvertibleConfig.setModelKey(for: Person.self) { property in
    property.name == "name" ? "_name_" : property.name
}