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.
- Explicit JSON key paths
- Predefined transformers now part of JSON adapter
- Core Data adapter now separate
- Managed object transformers reversed
- OS X 10.9 and iOS 8
- JSON key paths can only traverse objects
- MTLModel protocol
- Error handling for value transformers
- Storage behaviors for properties
- Type checking during JSON parsing
- Mapping multiple JSON fields to a single property
Explicit JSON key paths
+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
- Explicitly declare any property mappings in
+JSONKeyPathsByPropertyKeythat were previously implicit.
- Optionally use
+[NSDictionary mtl_identityPropertyMapWithModel:]for an initial property map.
Predefined transformers now part of JSON adapter
+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.
- Replace occurrences of
- Replace occurrences of
Core Data adapter now separate
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
- Import the MTLManagedObjectAdapter framework into your project.
Managed object transformers reversed
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.
- Swap the forward and reverse transformation logic of any custom managed
object transformers, or use
-mtl_invertedTransformerto do it automatically.
OS X 10.9 and iOS 8
Mantle now requires OS X 10.9+ or iOS 8+, for the use of Swift and dynamic frameworks.
- Increase your project’s deployment target to at least OS X 10.9 or iOS 8.
JSON key paths can only traverse objects
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.
- If you were using an array as an element in a key path, change the key path to end at the array, and update your JSON transformer to handle the nested elements instead.
Additions and improvements
<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.
Error handling for value transformers
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.
Storage behaviors for properties
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
Type checking during JSON parsing
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.
Mapping multiple JSON fields to a single property
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.