一、文档说明

本文档面向对象为天猫（不支持酒店、门票&旅行）商品管理的第三方开发者或者自研发商家。

二、背景

Schema体系是开放平台与天猫/淘宝商品团队共同定义的一套新的开放API规范，用以解决天猫/集市商品管理平台的频繁变动给开发者带来的开发维护成本。天猫/淘宝商品平台通过开放平台API将商品管理涉及的元素及规则使用更接近开发者的语言通过xml的方式返回，开发者解析xml后，根据xml中的规则及元素生成一个商品信息xml，调用开放平台API上传完成商品管理。

基于Schema体系开发商品管理工具时，建议的最优方案是开发者在应用中建立动态映射管理获取的xml与本地DB的数据关系，这样在当天猫/淘宝变化时，获取的xml也会随着变动，这个时候只需要在动态映射管理中设置好xml和本地DB的新映射关系，即可适应变化，从而改变原有天猫/淘宝一变化，开发者需要随着修改代码的状态。

三、开放资源

1. APISchema体系完成商品管理将使用API（图片上传使用原有API）：tmall.item.schema.add；

2. SDK去开放平台后台下载。

四、 支持范围

Schema体系能够支持天猫全类目的商品管理。

五、 Schema体系说明规则（Rule)

要使用Schema接口必须先理解schema体系的结构。一个完整的schema xml会由若干个field组成，每一个field都是用来描述规则和元素。

schema结构针对field定义了以下组成部分：

1）id
用于描述唯一主键，以商品的标题为例，*id=‘title’*。

2）name
用于描述field的显示名，以商品的标题为例，*name=‘商品标题’*。

3）type 用于描述field的值的数据输入类型，schema结构对于field定义了七种类型，分别为input、multiInput、singleCheck、multiCheck、complex、multiComplex和label。

① input，说明当前field的值为文本输入型。

② multiInput ，说明当前field的值为多行文本输入型。

③ singleCheck，说明当前field的值为单选输入型，类似于radio。

④ multiCheck ，说明当前field的值为多选输入型，类似于checkbox。

⑤ complex ，说明当前field的值为复合结构，表示数据的聚合。

⑥ multiComplex ，说明当前field的值为复合结构，与complex有差别的在于multiComplex的field是可以有多份数据实例样本。

4）values
用于描述multiInput和multiCheck类型的field的value的集合。

5）complex-values
用于描述complex和multiComplex类型的field的多数据值的集合。

6）value
用于描述field的值，上一层级一般为values或者complex-values。

7）option 用于描述field的值的可选值，与html中select元素中的option标签类似。

① displayName，用于描述可选值的展示名。

② value，用于描述可选值主键。

8） default-value
用于描述field的默认值。
注意：default-value 字段回传的时候，需要把default去掉，只保留 value，因为default-value ,服务端是不会认的。

9）label-group用于描述label的聚合，label主要用于描述说明信息。

rule 用于描述field的各类系统或者业务规则。

① valueTypeRule，用于描述field值需要满足数据类型，包括了text（文本型）/decimal（小数型）/integer（整数型）/date（日期型）/long（长整数型）/url（超链接）/textarea（多行文本）/html（支持html标记语法的文本）。

② requiredRule，是否必填，默认为false，true/false。

③ disableRule ，是否忽略此field，为true时，将不对rule进行check，同时他的value也将无效。默认为false，值范围包含true/false。

④ maxLengthRule ，最大长度。

⑤ minLengthRule ，最小长度。

⑥ maxValueRule，最大值（数值类型时有效）。

⑦ minValueRule ，最小值（数值类型时有效）。

⑧ maxInputNumRule ，最多可选数（多选时有效）。

⑨ minInputNumRule ，至少要选数（多选时有效）。

⑩ maxTargetSizeRule ，最大目标文件大小。

①① minTargetSizeRule ，最小目标文件大小。

①② readOnlyRule ，只读，用户无法修改返回值，值范围为true/false。

①③ regxRule ， 正则表达式匹配。

①④ tipRule ，Field中展示的tip信息，用于一些无法直接用语法描述或者过于复杂的规则，或者提示信息,需要给用户透出。

①⑤ maxImageSizeRule，最大图片大小，指的是分辨率，如800*800。

①⑥ minImageSizeRule ， 最小图片大小。
+devTipRule，一般用于给开发者提示，不需要展示给用户，开发者可以通过此Rule获取特定的信息，如例子中的如何获取售后模板信息。

Schema结构中不同输入类型的field可能出现的Rule有：

schema结构完整组成如下：

涉及到最大和最小规则的rule都是区间rule，在区间rule里面，都有一个exProperty属性，表示开闭区。当exProperty=include时，为闭区间，大小比较时，包含rule的value指定的值；当exProperty=not include时，为开区间，大小比较时，不包含rule的value指定的值。

说明：maxValueRule中value=2 且 exProperty=include时，表示返回值必须小于等于2；maxValueRule中value=2 且 exProperty=not include时，表示返回值必须小于2。

maxTargetSizeRule和minTargetSizeRule有个unit属性，表示规则的单位。这两个rule的单位主要有kb、mk、gb等，表示文件大小的单位。 maxLengthRule和minLengthRule也有unit属性，表示长度计量单位，有byte和character两种单位。

说明：“a汉字” 这个字符串，当单位为byte时，长度是5，当单位是character时，长度是3。

1）depend-group用于描述依赖关系的集合。

operator ，用于描述集合中多个依赖关系的关系，包括 ‘and’（与关系）和’or’（或关系）

2）depend-express用于描述依赖关系，上层为depend-group,与Rule中的disableRule是成组出现的。一般可以理解为当满足依赖关系时，disableRule为true才成立 depend-express中会包含fieldId、value和symbol。目前支持的symbol有：

① is null ，fieldId指向的字段的值为空；

② == ，fieldId指向的字段的值等于value；

③ != ， fieldId指向的字段的值不等于value；

④ ‘>’,fieldId指向的字段的值大于value；

⑤‘<’, fieldId指向的字段的值小于value；

⑥ ‘>=’ , fieldId指向的字段的值大于等于value；

⑦‘<=’ ,fieldId指向的字段的值小于等于value；

⑧ contains， fieldId指向的字段的值中包含有value；

⑨ not contains ，fieldId指向的字段的值中不包含有value；

⑩ this field’s value in fieldOptions ，fieldId指向的字段的值中在fieldId对应的value列表中；

①① this field’s value not in fieldOptions ，fieldId指向的字段的值中不在fieldId对应的value列表中；

一个field的sample：

开发者需要特别注意的几个类型有：

a）TipRule TipRule一般用于无法直接描述的复杂规则，isv需要将该规则在页面上透出给用户。

价格为例：

<field id="price" name="商品价格" type="input">
    <rules>
      <rule name="valueTypeRule" value="decimal"/>
      <rule name="requiredRule" value="true"/>
      <rule name="tipRule" value="一口价 应在 销售属性表中所填 最高与最低价格 范围区间内。"/>
      <rule name="minValueRule" value="0.00" exProperty="not include"/>
      <rule name="maxValueRule" value="100000000.00" exProperty="not include"/>
      <rule name="383278799_1" value="商品价格必须在销售属性表中所填最高与最低价格范围区间内"/>
      <rule name="tipRule" value="为避免一口价变动引发的违规，请谨慎输入价格。" url="http://rule.tmall.com/tdetail-1168.htm?tag=self"/>
    </rules>
    <default-value>338.00</default-value>
  </field>

b）DevTipRule DevTipRule一般用于给开发者提示，不需要展示给用户，开发者可以通过此Rule获取特定的信息，如例子中的如何获取售后模板信息。

以售后模板为例：

<field id="after_sale_id" name="售后说明模板ID" type="input">
    <rules>
      <rule name="valueTypeRule" value="long"/>
      <rule name="devTipRule" value="请使用taobao.aftersale.get接口获取售后说明模板信息" url="//open.taobao.com/apidoc/api.htm?path=cid:4-apiId:10448"/>
    </rules>

c）DisableRuleDisableRule=true表示该field可忽略，一般与depend-group成组出现，用于描述多个field之间的依赖关系。如例子中的开始时间是依赖于商品状态的值为1（定时上架）时才需要设置值，可以理解为只有fieldId="item_status"的值不等于1时，disableRule为true才成立。

以开始时间为例：

<field id="item_status" name="商品状态" type="singleCheck">
    <rules>
      <rule name="requiredRule" value="true"/>
    </rules>
    <options>
      <option displayName="出售中" value="0"/>
      <option displayName="定时上架" value="1"/>
      <option displayName="仓库中" value="2"/>
    </options>
    <default-value>0</default-value>
  </field>
  <field id="start_time" name="开始时间" type="input">
    <rules>
      <rule name="valueTypeRule" value="time"/>
      <rule name="disableRule" value="true">
        <depend-group operator="and">
          <depend-express fieldId="item_status" value="1" symbol="!="/>
        </depend-group>
      </rule>
    </rules>
  </field>

① 有单位的Rule；

② maxTargetSizeRule和minTargetSizeRule有个unit属性，表示规则的单位。这两个rule的单位主要有kb、mk、gb等，表示文件大小的单位。maxLengthRule和minLengthRule也有unit属性，表示长度计量单位，有byte和character两种单位.比如 ”a汉字” 这个字符串，当单位为byte时，长度是5，当单位是character时，长度是3。

六、Schema SDK方法使用说明

1. input类型

Map<String, Field> fieldMap = SchemaReader.readXmlForMap(file);
InputField priceField = (InputField) fieldMap.get("price");
priceField.setValue("20.00");

isv从xml文件中获取field的map，再根据field的id取出field，用field的get方法可以获取field中各个属性和规则的信息，最后只需要调用setValue方法就可以对field设置返回值了。

2. multiInput类型

Map<String, Field> fieldMap = SchemaReader.readXmlForMap(file);
MultiInputField itemTagField = (MultiInputField) fieldMap.get("itemTag");
itemTagField.addValue("t1");
itemTagField.addValue("t2");
itemTagField.addValue("t3");

3. singleCheck类型

Map<String, Field> fieldMap = SchemaReader.readXmlForMap(file);
SingleCheckField freightPayerField = (SingleCheckField) fieldMap.get("freightPayer");
freightPayerField.setValue("seller");

4. multiCheck类型

Map<String, Field> fieldMap = SchemaReader.readXmlForMap(file);
MultiCheckField sellerCidsField = (MultiCheckField) fieldMap.get("seller_cids");
sellerCidsField.addValue("410132580");
sellerCidsField.addValue("二级二级");

5. complex类型

Map<String, Field> fieldMap = SchemaReader.readXmlForMap(file);
ComplexField addressField = (ComplexField) fieldMap.get("address");
ComplexValue complexValue = new ComplexValue();
complexValue.setSingleCheckFieldValue("country", new Value("1"));
complexValue.setSingleCheckFieldValue("province", new Value("3"));
complexValue.setSingleCheckFieldValue("city", new Value("3"));
addressField.setComplexValue(complexValue);

6. multiComplex类型

Map<String, Field> fieldMap = SchemaReader.readXmlForMap(file);
MultiComplexField skuField = (MultiComplexField) fieldMap.get("sku");
ComplexValue complexValue1 = new ComplexValue();
complexValue1.setSingleCheckFieldValue("prop_1627207", new Value("3232483"));
complexValue1.setSingleCheckFieldValue("prop_20509", new Value("28381"));
complexValue1.setInputFieldValue("price", "10.00");
ComplexValue complexValue2 = new ComplexValue();
complexValue2.setSingleCheckFieldValue("prop_1627207", new Value("3232484"));
complexValue2.setSingleCheckFieldValue("prop_20509", new Value("28381"));
complexValue2.setInputFieldValue("price", "15.00");
skuField.addComplexValue(complexValue1);
skuField.addComplexValue(complexValue2);

七、Schema体系使用说明

Schema体系的top接口调用方式统一，固定模式为先调用读接口获取schema 规则xml，使用Schema SDK读取规则xml，通过readXmlForList拿到一个List，然后调用readXmlForMap方法读取出一个map，map的key就是FieldId，然后调用sdk中setValue的方法给每一个Field设置Value,完成所有Field的数据组装后，通过writeParamXmlString方法生成商品信息xml，然后调用对应的写接口完成操作。

针对商品40905418326增量更新商品标题为例：（JAVA伪代码，仅用于说明调用逻辑）

1）简单示例

String sessionKey = “该商品对应卖家的sessionKey”；
Long itemId = 40905418326L;
String xmlData = '<?xml version="1.0" encoding="UTF-8"?><itemParam><field id="update_fields" name="更新字段列表" type="multiCheck"><values><value>title</value><value>title</value></values></field></itemParam>';
TaobaoClient client=new DefaultTaobaoClient(url, appkey, secret);
TmallItemIncrementUpdateSchemaGetRequest req=new TmallItemIncrementUpdateSchemaGetRequest();
req.setItemId(itemId);
req.setXmlData(xmlData);
TmallItemIncrementUpdateSchemaGetResponse response = client.execute(req , sessionKey);
String xmlStirng = response.getUpdateItemResult();
List<Field> fieldList = SchemaReader.readXmlForList(xmlStirng);
    /**
     * 对fieldList进行各种修改操作数据组装
     */
String addXml = SchemaWriter.writeParamXmlString(fieldList);
TmallItemSchemaIncrementUpdateRequest addReq = new TmallItemSchemaIncrementUpdateRequest();
addReq.setItemId(itemId);
addReq.setXmlData(addXml);
TmallItemSchemaIncrementUpdateResponse updateRes = client.execute(updateReq , sessionKey);

2）对fieldList进行操作数据组装的方法

InputField field1 = new InputField();
        field1.setValue("input值");
 
        SingleCheckField field2 = new SingleCheckField();
        field2.setValue("singleCheck值");
        
        MultiInputField field3 = new MultiInputField();
        List<String> values1 = new ArrayList<String>();
        values1.add("multiInput值");
        field3.setValues(values1);
        
        MultiCheckField field4 = new MultiCheckField();
        List<Value> values2 = new ArrayList<Value>();
        values2.add(new Value("multiInput值"));
        field4.setValues(values2);
        
        ComplexField field5 = new ComplexField();
        ComplexValue complexValue = new ComplexValue();
        complexValue.setInputFieldValue("inputId", "input值");
        complexValue.setSingleCheckFieldValue("checkId", new Value("input值"));
        field5.setComplexValue(complexValue);
        
        MultiComplexField field6 = new MultiComplexField();
        List<ComplexValue> values3 = new ArrayList<ComplexValue>();
        ComplexValue complexValue2 = new ComplexValue();
        complexValue2.setInputFieldValue("inputId", "input值");
        complexValue2.setSingleCheckFieldValue("checkId", new Value("input值"));
        values3.add(complexValue2);
        field6.setComplexValues(values3);
        
        LabelField field7 = new LabelField();
        LabelGroup labelGroup = new LabelGroup();
        Label label = new Label();
        label.setDesc("label描述");
        labelGroup.add(label);
        field7.setLabelGroup(labelGroup);

3）一个完整增量更新标题的商品信息xml

<itemRule>
      <field id="title" name="商品标题" type="input">
        <value>这是一个示例商品而已</value>
      </field>
      <field id="update_fields" name="更新字段列表" type="multiCheck">
        <values>
          <value>title</value>
        </values>
      </field>
    </itemRule>

4）存在父子属性需要使用

<field id="sell_points" name="商品卖点" type="complex">
<complex-values>
<field id="sell_point_2" type="input">
<value>文艺</value>
</field>
<field id="sell_point_0" type="input">
<value>拼贴</value>
</field>
<field id="sell_point_1" type="input">
<value>棉质</value>
</field>
</complex-values>
</field>

八、Schema体系对接思路

在schema体系的对接中需要调整以前的思路，需要关注三点：

1）变更检测

由于业务的变化速度非常快，开发者实现一个变更检测的功能，对于天猫商家来说，每天定期拉取商家对应类目下规则，比较xml差异，根据差异进行业务处理的调整；

2）动态映射

开发者需要针对每一个商家实现一个动态映射的能力，将本地数据与线上返回的xml结构的元素进行一一映射，改变以前的写死参数的方式，这是接入schema体系最重要的事情；

3）关注field的type

开发者在实现时，应该考虑的是field的type和rule，关注不同type的field的处理方式和不同规则的前置校验和透出，而业务字段

则由动态映射能力去处理。

九、天猫发布流程

1. 商品发布示意图

2. 三大概念

1）类目 所有的产品都有一个类目，分类的基础,发布前需要确定已授权的类目和品牌；

2）产品 产品挂在类目上面，发布产品前需要确定产品的类目；

3）商品 商品挂在产品上面，发布商品前需要确定发布好产品。

3. 商品新发步骤

步骤一： 确定已授权的类目和品牌

涉及接口：

taobao.itemcats.authorize.get；

taobao.itemcats.get；

步骤二： 发布产品（编辑产品）

1）产品匹配规则获取 调用tmall.product.match.schema.get接口获取产品匹配的规则，根据规则生成产品匹配xml；

2）产品匹配 调用tmall.product.schema.match进行产品匹配；

① 匹配成功（说明已存在产品）调用tmall.product.schema.get查询产品状态；

a.产品状态（true) 如果返回true则可以直接发布商品 （下一步发布商品）；

b.产品状态（false) 如果返回false则需要等待；

② 匹配失败（说明没有可用产品，需要先发布产品）调用tmall.product.add.schema.get接口获取产品发布涉及的规则xml；

调用tmall.product.schema.add?发布产品；

3）产品发布（编辑） 调用tmall.product.schema.add?发布产品?tmall.product.schema.update?更新产品；

查询产品状态调用tmall.product.schema.get查询产品状态；

a.产品状态（true) 如果返回true则可以直接发布商品（下一步发布商品）；

b.产品状态（false) 如果返回false则需要等待；

备注：如果获取产品规则tmall.product.add.schema.get获取为空时，说明该类目为无关键属性类目，直接去发布商品即可。

涉及接口：

tmall.product.match.schema.get

tmall.product.schema.match

tmall.product.schema.get

tmall.product.add.schema.get

tmall.product.schema.add

步骤三： 发布商品（编辑商品）

当第二步的产品可用后，即可发布商品。

1）商品规则获取 调用tmall.item.add.schema.get获取规则；

2）商品发布 tmall.item.schema.add进行商品上新 （注意 涉及图片上传时请使用taobao.picture.upload接口）；

备注：当发布商品时，偶尔会遇到报[isv.item-service-error:ITEM_PROPERTIES_ERROR–“xxx”属性出错:类目属性在标准属性中不存在]这一类错误时，一般是由于行业小二对类目属性进行了调整，（需要去第二步编辑产品）需要调用；tmall.product.update.schema.get接口获取产品更新规则，检查是否有必填元素的value为空，重新生成产品更新信息xml调用tmall.product.schema.update接口完成补充即可。

涉及接口：

tmall.item.add.schema.get

tmall.item.schema.add

tmall.item.schema.update

TIPS：开发者如果涉及需要获取某一类目下的商品上新的所有规则，可以同时调用tmall.product.add.schema.get接口获取产品发布涉及的规则，然后入参需要注意product_id传入0、isv_init传入true调用tmall.item.add.schema.get获取商品发布的通用规则（非全部规则）。

4. 商品编辑更新

1）更新分类

a. 全量更新（除局部更新外的均需要走全量更新）；

b. 局部更新（局部更新API）；

2）增量更新API

a. 商品和sku价格编辑 建议使用?tmall.item.price.update；

b. 商品库存同步?taobao.item.quantity.update/taobao.skus.quantity.update；

c. 商品标题等信息增量更新 （支持元素如下）Schema 增量：

① TITLE（标 题）

② SUBTITLE（子标题，即卖点）

③ SHOW_TITLE (展示标题)

④ SHORT_TITLE（无线短标题）

⑤ DESC（PC描述）

⑥ WAP_DESC（无线描述）

⑦ WIRELESS_DESC (新版无线描述字段)

⑧ VERTICAL_IMAGE（竖图）

⑨ WHITE_BG_IMAGE (白底图)

⑩ LARGE_SCREEN_IMAGE (电子大屏图)

①① SHOP_CATEGORY (店铺类目)

①② ITEM_IMAGE(主图)

①③ ITEM_WIRELESS_IMAGES(无线主图)

①④ POSTAGE_ID_INCREMENT（运费模板ID）

①⑤ IMAGE_VIDEO_TYPE (主图视频比例类型)

①⑥ MAIN_VIDEO (主图视频)

①⑦ THREE_TO_FOUR_IMAGES (3:4商品图片)

3）增量更新过程

a. 增量更新规则获取 tmall.item.increment.update.schema.get（注意：这里也是一个xml，如果只修改标题，则xml中update_fields的value就只设置title；如果需要更新多个，则设置多个value）

b. 根据规则拼接xml

c. 调用增量更新接口 tmall.item.schema.increment.update （注意：获取的规则中的所有field都需要将default-value拼装上并回传回来）

TIPS1： 由于增量更新支持的元素可能会进行扩展，建议用户可以每天调用tmall.item.increment.update.schema.get接口仅入参item_id获取当前商品所属类目支持增量更新的元素。

TIPS2：建议开发者将增量接口支持的每个元素独立封装，这样性能上更优越，报错也会更少。

TIPS3：关于主图视频，目前商品已经支持3：4主图视频，并且支持3：4商品主图图片更新，建议三个字段为一个组件来使用：

① 如果IMAGE_VIDEO_TYPE 选择1：1或者16：9类型，那么MAIN_VIDEO需要传值1：1或者16：9类型的视频，此时THREE_TO_FOUR_IMAGES 这个字段，不管你传值与否，都不会生效；

② 如果IMAGE_VIDEO_TYPE 选择3：4类型，那么MAIN_VIDEO需要传值3：4类型视频，如果商品本来就有3：4视频和图片，则可以只上传3：4视频或图片来更新，其他情况下需要同时传3：4视频和图片。

十、商品管理相关的主要接口列表

可通过top api查询详细说明。

1. 产品检索

2. 产品发布

3. 产品更新

4. 产品其它接口(非schema)

5. 商品发布

注: taobao.item.add/taobao.item.vip.add不再维护，作不支持处理。

6. 商品更新(增量,全量及快速接口)

注: taobao.item.update/taobao.item.vip.update不再维护，作不支持处理。

7. 简化schema商品接口

备注：针对国外大卖家, 只允许具有官网直售商家标(27841)的商家使用

8. vip商品接口

备注：只允许具有Vip商家标(34113)的商家使用

9. 商品其它接口(非schema接口)

10. 附件下载

top schema sdk : 文件下载（jar文件）。