Magical Data Modelling Framework for JSON

New: In version 0.12.0 I added experimental support for exporting JSON models to CoreData.

最新消息:在0.12.0版本中,我试验性的支持将 JSON models 转化成 CoreData .

Give it a try and let me know, post an issue or just get in touch. Try something like that:

如果你试验过了，有空告知哥一下，哥写开源库也不容易,发一篇博文或者给个链接以表支持：

NSError* error = nil;
GitHubRepoEntity* entity = [GitHubRepoEntity entityWithModel:model
                                                   inContext:self.managedObjectContext
                                                       error:&error];
[self.managedObjectContext save: nil];

If you like JSONModel and use it can you please: 1) star this repo 2)send me some feedback. Thanks!

JSONModel is a library, which allows rapid creation of smart data models. You can use it in your iOS or OSX apps.

JSONModel automatically introspects your model classes and the structure of your JSON input and reduces drastically the amount of code you have to write.

如果你喜欢 JSONModel ,那么你可以:1)长期关注这个开源项目,2)你是土豪的话,给哥捐点吧,谢谢.

JSONModel 是一个库,他能智能并且快速的创建出数据 model,你可以在你的 iOS 项目或者 OSX 项目上使用它.

Adding JSONModel to your project

添加 JSONModel 到你的工程中

Requirements

需要的环境:

ARC only; iOS 5.0+ / OSX 10.7+
SystemConfiguration.framework
ARC,iOS 5.0+ / OSX 10.7 +
引入框架SystemConfiguration.framework

Get it as: 1) source files

Download the JSONModel repository as a zip file or clone it
Copy the JSONModel sub-folder into your Xcode project
Link your app to SystemConfiguration.framework

1. 下载 JSONModel zip包

2. 将 JSONModel 文件夹拷贝到你的工程项目中

3. 将库 SystemConfiguration.framework 添加上

or 2) via Cocoa pods

In your project's Podfile add the JSONModel pod:

使用 Cocoa pods 来安装：

pod 'JSONModel'

If you want to read more about CocoaPods, have a look at this short tutorial.

如果你不会用 CocoaPods，你可以看看这简单的教程。

Source code documentation

源码的文档

The source code includes class docs, which you can build yourself and import into Xcode:

源码本身包含了类的文档，你可以自己编译后导入到你的Xcode中：

If you don't already have appledoc installed, install it with homebrew by typing brew install appledoc.
Install the documentation into Xcode by typing appledoc . in the root directory of the repository.
Restart Xcode if it's already running.

1. 如果你还没安装 appledoc ，先安装 appledoc

2. 在Xcode上键入 appledoc 安装文档，在根目录下

3. 重启Xcode

Basic usage

基本使用

Consider you have a JSON like this:

假设你的 JSON 串像下面这样子:

{"id":"10", "country":"Germany", "dialCode": 49, "isInEurope":true}

Create a new Objective-C class for your data model and make it inherit the JSONModel class.
Declare properties in your header file with the name of the JSON keys:
创建一个你自己的类,并继承至 JSONModel
在你的头文件里面进行声明你所需要的 JSON key值

#import "JSONModel.h"

@interface CountryModel : JSONModel

@property (assign, nonatomic) int id;
@property (strong, nonatomic) NSString* country;
@property (strong, nonatomic) NSString* dialCode;
@property (assign, nonatomic) BOOL isInEurope;

@end

There's no need to do anything in the .m file.

.m文件中你不需要做其他的事情了.

Initialize your model with data:
初始化你的 model ,如下所示:

#import "CountryModel.h"
...

NSString* json = (fetch here JSON from Internet) ... 
NSError* err = nil;
CountryModel* country = [[CountryModel alloc] initWithString:json error:&err];

If the validation of the JSON passes you have all the corresponding properties in your model populated from the JSON. JSONModel will also try to convert as much data to the types you expect, in the example above it will:

如果传过来的 JSON 合法,你所定义的所有的属性都会与该 JSON 值相匹配,并且 JSONModel 也会尝试尽可能的转换成你所想要的数据,就像上面的例子:

convert "id" from string (in the JSON) to an int for your class
just copy country's value
convert dialCode from number (in the JSON) to an NSString value
finally convert isInEurope to a BOOL for your BOOL property
转化 "id",从字符串转换成 int 型
拷贝 country 属性的值
转换 dialCode ,从NSNumber 转换为 NSString 值
最后一个呢是将 isInEurope 转换成 BOOL 的属性

And the good news is all you had to do is define the properties and their expected types.

所以，你需要做的就是定义出你期望的属性就行了。

Online tutorials

在线教程

Official website: http://www.jsonmodel.com

Class docs online: http://jsonmodel.com/docs/

Step-by-step tutorials:

傻瓜教程：

Examples

例子

Automatic name based mapping

命名自动匹配

{
  "id": "123",
  "name": "Product name",
  "price": 12.95
}

@interface ProductModel : JSONModel
@property (assign, nonatomic) int id;
@property (strong, nonatomic) NSString* name;
@property (assign, nonatomic) float price;
@end

@implementation ProductModel
@end

Model cascading (models including other models)

model中含有其他的model

{
  "order_id": 104,
  "total_price": 13.45,
  "product" : {
    "id": "123",
    "name": "Product name",
    "price": 12.95
  }
}

@interface OrderModel : JSONModel
@property (assign, nonatomic) int order_id;
@property (assign, nonatomic) float total_price;
@property (strong, nonatomic) ProductModel* product;
@end

@implementation OrderModel
@end

Model collections

model中含有其他model的集合

{
  "order_id": 104,
  "total_price": 103.45,
  "products" : [
    {
      "id": "123",
      "name": "Product #1",
      "price": 12.95
    },
    {
      "id": "137",
      "name": "Product #2",
      "price": 82.95
    }
  ]
}

@protocol ProductModel
@end

@interface ProductModel : JSONModel
@property (assign, nonatomic) int id;
@property (strong, nonatomic) NSString* name;
@property (assign, nonatomic) float price;
@end

@implementation ProductModel
@end

@interface OrderModel : JSONModel
@property (assign, nonatomic) int order_id;
@property (assign, nonatomic) float total_price;
@property (strong, nonatomic) NSArray<ProductModel>* products;
@end

@implementation OrderModel
@end

Key mapping

键值转回匹配

{
  "order_id": 104,
  "order_details" : [
    {
      "name": "Product#1",
      "price": {
        "usd": 12.95
      }
    }
  ]
}

@interface OrderModel : JSONModel
@property (assign, nonatomic) int id;
@property (assign, nonatomic) float price;
@property (strong, nonatomic) NSString* productName;
@end

@implementation OrderModel

+(JSONKeyMapper*)keyMapper
{
  return [[JSONKeyMapper alloc] initWithDictionary:@{
    @"order_id": @"id",
    @"order_details.name": @"productName",
    @"order_details.price.usd": @"price"
  }];
}

@end

Global key mapping (applies to all models in your app)

设置全局的键值转回匹配

[JSONModel setGlobalKeyMapper:[
    [JSONKeyMapper alloc] initWithDictionary:@{
      @"item_id":@"ID",
      @"item.name": @"itemName"
   }]
];

Map automatically under_score case to camelCase

将下滑线转换成首字母大写

{
  "order_id": 104,
  "order_product" : @"Product#1",
  "order_price" : 12.95
}

@interface OrderModel : JSONModel

@property (assign, nonatomic) int orderId;
@property (assign, nonatomic) float orderPrice;
@property (strong, nonatomic) NSString* orderProduct;

@end

@implementation OrderModel

+(JSONKeyMapper*)keyMapper
{
  return [JSONKeyMapper mapperFromUnderscoreCaseToCamelCase];
}

@end

Optional properties (i.e. can be missing or null)

可以为空的属性值

{
  "id": "123",
  "name": null,
  "price": 12.95
}

@interface ProductModel : JSONModel
@property (assign, nonatomic) int id;
@property (strong, nonatomic) NSString<Optional>* name;
@property (assign, nonatomic) float price;
@property (strong, nonatomic) NSNumber<Optional>* uuid;
@end

@implementation ProductModel
@end

Ignored properties (i.e. JSONModel completely ignores them)

忽略某些属性

{
  "id": "123",
  "name": null
}

@interface ProductModel : JSONModel
@property (assign, nonatomic) int id;
@property (strong, nonatomic) NSString<Ignore>* customProperty;
@end

@implementation ProductModel
@end

Make all model properties optional (avoid if possible)

让所有的属性都可以有空的属性值

@implementation ProductModel
+(BOOL)propertyIsOptional:(NSString*)propertyName
{
  return YES;
}
@end

Lazy convert collection items from dictionaries to models

将集合元素转换成 model

{
  "order_id": 104,
  "total_price": 103.45,
  "products" : [
    {
      "id": "123",
      "name": "Product #1",
      "price": 12.95
    },
    {
      "id": "137",
      "name": "Product #2",
      "price": 82.95
    }
  ]
}

@protocol ProductModel
@end

@interface ProductModel : JSONModel
@property (assign, nonatomic) int id;
@property (strong, nonatomic) NSString* name;
@property (assign, nonatomic) float price;
@end

@implementation ProductModel
@end

@interface OrderModel : JSONModel
@property (assign, nonatomic) int order_id;
@property (assign, nonatomic) float total_price;
@property (strong, nonatomic) NSArray<ProductModel, ConvertOnDemand>* products;
@end

@implementation OrderModel
@end

Using the built-in thin HTTP client

使用内置的 HTTP 链接

//add extra headers
[[JSONHTTPClient requestHeaders] setValue:@"MySecret" forKey:@"AuthorizationToken"];

//make post, get requests
[JSONHTTPClient postJSONFromURLWithString:@"http://mydomain.com/api"
                                   params:@{@"postParam1":@"value1"}
                               completion:^(id json, JSONModelError *err) {

                                   //check err, process json ...

                               }];

Export model to NSDictionary or to JSON text

将 model 导出为字典或者json字符串

ProductModel* pm = [[ProductModel alloc] initWithString:jsonString error:nil];
pm.name = @"Changed Name";

//convert to dictionary
NSDictionary* dict = [pm toDictionary];

//convert to text
NSString* string = [pm toJSONString];

json validation
data transformations
error handling
custom data validation
automatic compare and equality features
and more.
json数据键值匹配
数据转换
好的容错能力
自定义数据键值匹配
自动比较以及判断的特性
还有更多的等待亲来挖掘

以下是本人使用的测试结果

使用 JSONModel