BWJSONMatcher

BWJSONMatcher is a lightweight Objective-c library which helps you easily match a JSON data or JSON string or JSON object up with your data model.

It provides:

• A universal JSON Matcher that matches a JSON data or JSON string or JSON object up with your data model
• A catalog based on NSObject, helps you easily transform JSON with any object
• Three protocols, to which your data model should conforms

How To Use

API documentation is available at CocoaDocs - BWJSONMatcher.

Sample project can be found here.

Working with NSObject+BWJSONMatcher (Recommend)

#import "NSObject+BWJSONMatcher.h"

...
// convert json data to data model
NSData *jsonData = your-json-bytes;
YourValueObject *dataModel = [YourValueObject fromJSONData:jsonData];

// convert json string to data model
NSString *jsonString = @"{your-json-string}";
YourValueObject *dataModel = [YourValueObject fromJSONString:jsonString];

// convert json object to data model
NSDictionary *jsonObject = @{your-json-object};
YourValueObject *dataModel = [YourValueObject fromJSONObject:jsonObject];

...
YourValueObject *dataModel = instance-of-your-value-object;

// convert data model to json data
NSData *jsonData = [dataModel toJSONData];
// convert data model to json string
NSString *jsonString = [dataModel toJSONString];
// convert data model to json object
NSDictionary *jsonObject = [dataModel toJSONObject];
...

Working with BWJSONMatcher

#import "BWJSONMatcher.h"

...
NSDictionary *jsonObject = @{your-json-object};
YourValueObject *dataModel = [BWJSONMatcher matchJSON:jsonObject withClass:[YourValueObject class]];

...
NSString *jsonString = "[{your-json-string}, ...]";
NSArray *jsonArray = [BWJSONMatcher matchJSONString:jsonObject withClass:[YourValueObject class]];

...
YourValueObject *dataModel = instance-of-your-value-object;
NSDictionary *jsonObject = [BWJSONMatcher convertObjectToJSON:dataModel];
...

How to handle property with type NSArray

As with the example here, if you have a property with type NSArray, make your ValueObject conforms to the protocol BWJSONHasArrayProperties and implement the method typeInProperty:, tell BWJSONMatcher which type of object will be included in this array.

- (Class)typeInProperty:(NSString *)property {
    if ([property isEqualToString:@"emails"]) {
        return [NSString class];
    }
    
    return nil;
}

How to ignore certain properties

In some cases, there will be certain properties which don't need to be extracted from json data. Make your ValueObject conforms to the protocol BWJSONHasIgnoredProperties, provide the property names you want to ignore in class method ignoredProperties:, BWJSONMatcher will ignore these properties when matching json data with your data model.

+ (NSArray *)ignoredProperties {
    return @[@"street", @"valet"];
}

How to rename the property

It is quite common that JSON with ill-considered property names or names which are inconsistent with your convention will be returned from certain open APIs. In this circumstance, just make your data model conforms to the protocol BWJSONHasToMapProperty, provide a property mapper translating the name in data model to that in JSON.

+ (NSDictionary *)propertyMapper {
    return @{@"userId": @"id", @"userName": @"user_name"};
}

Installation

Installation with CocoaPods (Recommend)

CocoaPods is a dependency manager for Objective-C, which automates and simplifies the process of using 3rd-party libraries in your projects. See the Get Started section for more details.

platform :ios, '6.0'

pod 'BWJSONMatcher', '~>1.1.3'

Installation with Carthage (iOS 8+)

Carthage is a lightweight dependency manager for Swift and Objective-C. It leverages CocoaTouch modules and is less invasive than CocoaPods.

To install with carthage, follow the instruction on Carthage

github "BurrowsWang/BWJSONMatcher"

Other Ways

• Copying all the files into your project
• Importing the project as a dynamic framework, PS: ADD FRAMEWORK TO Embedded Binaries
• Importing the project as a static library, PS: ADD -ObjC TO BUILD SETTING Other Linker Flags

License

All source code is licensed under the MIT License.