一、文档说明

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

二、背景介绍

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

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

三、开放资源

1. API

Schema体系完成商品管理将使用以下API（图片上传、价格、库存修改使用原有API）

tmall.item.schema.add

2. SDK

使用新体系开发商品管理工具涉及两部分SDK：

a.TOP API SDK——下载方式与旧有方式保持一致。

3. 测试账号

目前提供沙箱环境进行测试，所有开发者可以使用沙箱测试账号进行测试，沙箱测试账号：mallb140（密码： tmall1234），测试已尺码库类目请使用类目50008901，常规类目请使用类目162116。

四、支持范围

1. Schema体系覆盖范围

Schema体系能够支持天猫全类目的商品管理，集市接口开放还待评估；

天猫开发者需要关注以下公告：https://open.taobao.com/anno?spm=a219a.7386797.0.0.6927669aWSnRNt&source=search&docId=24931&docType=12

2. Schema体系进行商品管理的注意

1）天猫商品上新

使用Schema体系进行更新不需要判断是否达尔文体系。天猫商品上新的调用基本流程如下：

① 用户判断

由于Schema体系天猫/集市为两套接口，需要使用taobao.user.seller.get判断当前店铺是否属于天猫才能调用天猫Schema接口。

② 授权类目及品牌获取

天猫用户发布的商品类目及品牌需要天猫授权，因此在发布商品前需要先调用taobao.itemcats.authorize.get取得已授权的类目及品牌。

其中发布商品的类目需要叶子类目，因此在获取到类目id后需要再调用taobao.itemcats.get，获取发布商品的叶子类目cid 。

③ 产品检索

天猫所有的商品均挂靠在一个具体产品上，因此卖家上新时需要先查询目前在天猫上是否已上传产品信息，如果无产品则需要上传新产品后等待产品状态可用方可发布新品。

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

tmall.product.schema.match进行产品匹配，如果匹配到产品则调用tmall.product.schema.get查询产品状态，如果返回true则可以直接发布商品，否则需要等待；如果匹配为空，则说明当前需要发布的商品在天猫上还不存在可用产品信息，需要先发布一个新产品。通过调用tmall.product.add.schema.get接口获取产品发布涉及的规则，根据规则生成产品发布xml，调用tmall.product.schema.add发布产品，同样需要调用tmall.product.schema.get查询产品状态，如果返回true则可以直接发布商品，否则需要等待。需要注意的是如果tmall.product.add.schema.get获取为空时，说明该类目为无关键属性类目，直接去发布商品即可。

④ 商品发布

当匹配的产品状态为true时，可以进行商品上新。调用tmall.item.add.schema.get获取商品发布的规则，根据规则生成商品上新xml，调用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.product.add.schema.get。

接口获取产品发布涉及的规则，然后入参需要注意product_id传入0、isv_init传入true调用tmall.item.add.schema.get获取商品发布的通用规则（非全部规则）。

2）天猫商品编辑

① 商品价格编辑

商品和sku的价格建议使用独立的商品价格更新接口tmall.item.price.update进行更新。

② 商品库存同步

商品和sku的库存同步建议使用独立的商品库存同步接口taobao.item.quantity.update/taobao.skus.quantity.update进行更新。

③ 商品标题等信息更新

Schema体系接口支持对部分元素（TITLE（标 题）， SUBTITLE（子标题，即卖点），SHORT_TITLE（无线短标题），DESC（PC描述）， WAP_DESC（无线描述），FENQIGOU（分期购），VERTICAL_IMAGE（ 竖图） ，DRESS_ONLY_FOR_TMALL（天猫独家），SHOP_SAME_STYLE（商场同款 ））进行增量更新，支持增量的参数请以接口返回为准。

开发者调用tmall.item.increment.update.schema.get接口传入具体的商品id和需要更新的字段（这里也是一个xml，如果只修改标题，则xml中update_fields的value就只设置title；如果需要更新多个，则设置多个value）获取该商品更新该字段的规则，根据规则生成增量更新商品xml，调用tmall.item.schema.increment.update完成增量更新。生成更新商品xml时，获取的规则中的所有field都需要将default-value拼装上并回传回来。

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

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

④ 其他信息更新

除上述信息外的其他商品信息的更新需要使用schema全量更新接口进行更新。调用tmall.item.update.schema.get获取商品全量更新规则，根据规则生成商品更新信息xml后（所有不需要修改的信息需要将default-value统一回传），调用tmall.item.schema.update进行更新。

3）淘宝商品schema上新 （备注，淘宝schema接口已下线，不再维护)

淘宝商品上新的调用基本流程如下：

① 用户判断

由于Schema体系天猫/集市为两套接口，需要使用taobao.user.seller.get判断当前店铺是否属于淘宝才能调用淘Schema接口。

② 商品发布

调用taobao.item.add.schema.get获取商品发布的规则，根据规则生成商品上新xml，调用taobao.item.schema.add进行商品上新，涉及图片上传时请使用taobao.picture.upload接口。

4）淘宝商品更新

① 商品价格编辑

商品和sku的价格建议使用独立的商品价格更新接口taobao.item.price.update进行更新。

② 商品库存同步

商品和sku的库存同步建议使用独立的商品库存同步接口taobao.item.quantity.update/taobao.skus.quantity.update进行更新。

③ 商品标题schema增量信息更新 （备注，淘宝schema接口已下线，不再维护)

Schema体系接口支持对部分元素（标题、热点、描述和无线描述）进行增量更新，支持增量的参数请以接口传入all或者不传获取到的返回为准。

开发者调用taobao.item.increment.update.schema.get接口传入具体的商品id和需要更新的字段（这里也是一个string，比如更新标题，只需要在）获取该商品更新该字段的规则，根据规则生成增量更新商品xml，调用taobao.item.schema.increment.update完成增量更新。生成更新商品xml时，获取的规则中的所有field都需要将default-value拼装上并回传回来。

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

建议开发者将增量接口支持的每个元素独立封装，这样性能上更优越，报错也会更少。需要关注的是增量接口并不保证所有场景下都能增量成功，对于一些运营规则强要求的数据会使增量接口被规则校验住报错。并且对于一些模块化的字段，如无线描述wl_description，整个完整模块统一进行增量校验。

④ 其他信息更新（备注，淘宝schema接口已下线，不再维护)

除上述信息外的其他商品信息的更新需要使用schema全量更新接口进行更新。调用taobao.item.update.schema.get获取商品全量更新规则，根据规则生成商品更新信息xml后（所有不需要修改的信息需要将default-value统一回传），调用taobao.item.schema.update进行更新。

五、Schema体系说明

一个商品的Schema结构是由多个field组成的。以下示例为通过商品增量规则获取接口（tmall.item.increment.update.schema.get）获取到规则xml的片段：

<field id="title" name="商品标题" type="input">
    <rules>
      <rule name="valueTypeRule" value="text"/>
      <rule name="requiredRule" value="true"/>
      <rule name="minLengthRule" value="1" exProperty="include"/>
      <rule name="maxLengthRule" value="30" exProperty="include"/>
    </rules>
    <default-value>韩版2014秋冬新款女装高领套头长款纯色毛衣TK4178</default-value>
  </field>

从上述片段可以看到商品的标题规则通过xml上的一个节点输出，可以看到一个schema结构下的field包含了id、name和type三个内容，同时还包含了多个rule及default-value，根据这个片段我们可以了解到的是商品的标题这个信息是一个input类型的字段，值的类型为文本型的、要求必填、字符长度不小于1个字符，并且不超过30个字符，并且现在商品标题为韩都衣舍韩版2014秋冬新款女装高领套头长款纯色毛衣TK4178婏。

schema结构完整组成如下：

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

1. TipRule

以价格为例：

<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>

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

2. DevTipRule

以售后模板为例：

<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>

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

3. DisableRule

以开始时间为例：

<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>

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

4. 有单位的Rule

maxTargetSizeRule和minTargetSizeRule有个unit属性，表示规则的单位。这两个rule的单位主要有kb、mk、gb等，表示文件大小的单位。 

maxLengthRule和minLengthRule也有unit属性，表示长度计量单位，有byte和character两种单位.比如 ”a汉字” 这个字符串，当单位为byte时，长度是5，当单位是character时，长度是3。

六、schema体系使用说明

 以增量更新商品标题为例，当商家进行商品标题编辑时，一般来说可以分成以下几个步骤：

1）获取商品增量更新时所有需要的规则xml；

2）使用Schema SDK读取规则xml，通过readXmlForList拿到一个List<Field>，然后调用readXmlForMap方法读取出一个map，map的key就是FieldId，然后调用sdk中setValue的方法给每一个Field设置Value,完成所有Field的数据组装后，通过writeParamXmlString方法生成商品信息xml；

3）调用schema增量更新接口传入商品信息xml及其他参数完成商品标题的更新。

1. 简单示例

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

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);
    Long itemId = Long.parseLong(updateRes.getUpdateItemResult());

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  

<xml version="1.0" encoding="utf-8">
    <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.存在父子属性需要使用 <complex-values>

<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>

5. 一个复杂规则xml和信息xml

规则xml:   文件下载；

入参信息xml：文件下载；

七、Schema体系对接思路

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

1. 变更检测

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

2. 动态映射

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

3. 关注field的type

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

八、FAQ

Q：使用增量接口更新卖点应该怎么提示更新字段列表不能为空？

A：检查传入的xml中的update_fields中是否传入了通过get接口获取的规则xml中的对应卖点的option，所有value的范围必须根据规则xml中进行获取。

Q：遇到以下类型错误：

    [msg] => Remote service error
   [sub_code] => isv.item-add-service-error:ITEM_PROPERTIES_ERROR
   [sub_msg] => “帐底材质、外帐材质”属性出错:类目属性在标准属性中不存在:帐底材质, 外帐材质。  

A：一般为行业小二对类目的属性进行了调整，不管在商品发布还是在更新的情况下遇到此情况时，如果是天猫商品，调用tmall.product.update.schema.get接口获取产品更新规则后，根据规则更新一下产品，再进行商品更新和商品发布；如果是集市商品，直接获取最新的规则xml后再进行商品更新或者发布。

Q：遇到以下错误：

{"error_response":{"code":15,"msg":"Remote service error","sub_code":"isv.invalid-parameter:cid","sub_msg":"商品类目未授权，请重新选择类目","request_id":"9wy7rnl2x7k7"}}。

A：一般出现于天猫商家，天猫对于商家能够发布的商品类目和品牌有管控，开发者可以通过调用tmall.brandcat.control.get接口去获取当前商家允许发布的类目，控制schema中接口的类目id的入参范围。

九、附件下载

top schema sdk : 文件下载。