This release of Mantle contains major breaking changes that we were unable to make after freezing the 1.0 API.
The changes in 2.0 focus on simplifying concepts and increasing flexibility in the framework.
For a complete list of the changes made in Mantle 2.0, see the milestone.
Additions and improvements
+JSONKeyPathsByPropertyKey will no
longer infer your property mappings
Instead, you must explicitly specify every property that should be mapped, and any properties omitted will not be considered for JSON serialization or deserialization.
For convenience, you can use
to automatically create a one-to-one mapping that matches the previous default
+JSONKeyPathsByPropertyKeythat were previously implicit.
+[NSDictionary mtl_identityPropertyMapWithModel:]for an initial property map.
+mtl_JSONArrayWithModelClass: methods have
This allows custom JSON adapter subclasses to substitute their own transformers with additional logic, and moves the transformers closer to their actual point of use.
MTLManagedObjectAdapter class, used for converting to and from Core Data
objects, has been moved to its own
framework. This better
indicates its “semi-official” status, as it gets less attention than the core
In addition to being a separate framework,
the behavior of
MTLManagedObjectAdapter has changed as well—specifically, the
direction of managed object attribute transformers has been flipped.
Managed object transformers now convert from managed object attributes to model properties in the forward direction. In the reverse direction, they convert from properties to managed object attributes.
-mtl_invertedTransformerto do it automatically.
Mantle now requires OS X 10.9+ or iOS 8+, for the use of Swift and dynamic frameworks.
Every element of a JSON key path specified in
now refer to an object (dictionary).
It was previously possible to use an array as a key path element, but this was unintended behavior, and is now explicitly disallowed.
<MTLModel> protocol represents the basic behaviors expected from any
model object, and can be used instead of the
MTLModel class when inheritance
is impossible, or to create more generic APIs.
<MTLModel> conformance can be added to the objects from other
persistence frameworks in order to use those objects in conjunction with
MTLJSONAdapter has been updated to only depend on
conformance, and no longer requires a
MTLModel subclass in order to serialize
or deserialize from JSON.
protocol can be used to add error
reporting behaviors to any
MTLValueTransformer has been updated to take advantage of the new interface,
with the following new methods that provide error information:
Similarly, the predefined transformers that Mantle provides now provide error information upon failure as well.
method can be used to redefine the
default behavior of methods like
-copy all at once.
Properties which have been omitted from
+propertyKeys by default will continue
to be omitted under the new API, with a default behavior of
MTLJSONAdapter now implicitly
validates the type of values
assigned to your
<MTLModel> objects during JSON parsing.
This can be prevent errors like an
NSString being assigned to a
This is only a simple safety check, though, and cannot catch every kind of error! Continue to verify that your types align ahead of time.
MTLJSONAdapter can now map multiple fields to a single property, and
vice-versa. Specify an array of keypaths for the property when implementing
+JSONKeyPathsByPropertyKey rather than an
The default behaviour is to set the property to a dictionary of values for the
specified keypaths. If you specify a value transformer for the given property
key, this transformer will receive an
NSDictionary of values.