一、文档说明

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

二、 背景介绍

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

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

三、 开放资源

    1. API

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

     //open.taobao.com/doc/api_cat_detail.htm?scope_id=11430&category_id=102

    2. SDK

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

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

    b. Schema SDK—— 开放平台将单独提供用于解析商品规则xml和生成商品信息xml的SDK，下载地址为云盘地址http://box.cloud.taobao.com/file/downloadFile.htm?shareLink=qUMsITX

    PHP版本SDK感谢欢乐逛的同学共建。

    3. 测试账号

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

    4. 支持渠道

    开发者在阅读仔细完本文档后，如果有问题请加入旺旺群（836280177）咨询

四、 支持范围

4.1 Schema体系覆盖范围

    Schema体系能够支持天猫全类目的商品管理，集市接口全量开放预计在6月前；

    天猫开发者需要关注以下公告：//open.taobao.com/support/announcement_detail.htm?id=24939

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

4.2.1 天猫商品上新

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

    1. 用户判断

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

    2. 产品检索

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

    调用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获取为空时，说明该类目为无关键属性类目，直接去发布商品即可。

    3. 商品发布

    当匹配的产品状态为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接口完成补充即可

    4.特别提示

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

4.2.2 天猫商品编辑

    1） 商品价格编辑

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

    2） 商品库存同步

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

    3） 商品标题等信息更新

        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获取当前商品所属类目支持增量更新的元素。

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

    4） 其他信息更新

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

4.2.3 淘宝商品上新

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

    1. 用户判断

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

    2. 商品发布

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

4.2.4  淘宝商品更新

    1） 商品价格编辑

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

    2） 商品库存同步

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

    3） 商品标题等信息更新

        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，整个完整模块统一进行增量校验。

    4） 其他信息更新

    除上述信息外的其他商品信息的更新需要使用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

六、 schema体系使用说明

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

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

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

• 调用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. 一个复杂规则xml和信息xml

     规则xml:http://yunpan.taobao.com/s/1IcqnB2UBuF

     入参信息xml：http://yunpan.taobao.com/s/8cdLFtDxi2

七、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的入参范围。

FAQ

• 关于此文档暂时还没有FAQ