一、背景

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

二、相关API

1. 商品发布

说明：不同类型的应用请使用不同的商品发布接口来进行商品发布。

接口描述	接口名称
获取商品发布规则信息	alibaba.item.publish.schema.omnichannel.get（全渠道&垂直行业应用） alibaba.item.publish.schema.distribute.get（分销铺货类应用） alibaba.item.publish.schema.get（自研应用）
商品发布	alibaba.item.publish.omnichannel.submit（全渠道&垂直行业应用） alibaba.item.publish.distribute.submit（分销铺货类应用） alibaba.item.publish.submit（自研应用）
商品级联属性信息获取	alibaba.item.publish.props.get

2. 商品编辑

a）商品编辑获取schema信息：alibaba.item.edit.schema.get；

b）商品编辑提交schema信息：alibaba.item.edit.submit；

c）商品增量编辑：alibaba.item.edit.fastupdate；

3. 商品管理

a）商品上架：alibaba.item.operate.upshelf；

b）商品下架：alibaba.item.operate.downshelf；

c）商品删除：alibaba.item.operate.delete。

三、Schema体系说明规则

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

段名称	说明
id	用于描述唯一主键，以商品的标题为例，id=“title”。
name	用于描述field的显示名，以商品的标题为例，name=“商品标题”。
type	用于描述field的值的数据输入类型，schema结构对于field定义了七种类型，分别为input、multiInput、 singleCheck、multiCheck、complex、multiComplex和label。详见3.1说明。
values	用于描述multiInput和multiCheck类型的field的value的集合。
complex-value	用于描述complex类型的field的多数据值的集合。
complex-values	用于描述multiComplex类型的field的多数据值的集合。
value	用于描述field的值，上一层级一般为values或者complex-values。
option	用于描述field的值的可选值，与html中select元素中的option标签类似。 （1）displayName，用于描述可选值的展示名。（2）value，用于描述可选值主键。
label-group	用于描述label的聚合，label主要用于描述说明信息。
rule	用于描述field的各类系统或者业务规则。详见3.2说明。
depend-group	用于描述依赖关系的集合。
operator	用于描述集合中多个依赖关系的关系，包括 ‘and’（与关系）和’or’（或关系）。
depend-express	用于描述依赖关系，上层为depend-group,与Rule中的disableRule是成组出现的。一般可以理解为当满足依赖关系时，disableRule为true才成立 depend-express中会包含fieldId、value和symbol。目前支持的symbol见3.3说明。

1. type类型说明

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是可以有多份数据实例样本

2. rule类型说明

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

rule类型	类型说明
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获取特定的信息，如 例子中的如何获取售后模板信息

3. depend-express支持的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列表中

4. 输入类型(type)与规则(rule)关系

	input	multiInput	singleCheck	multiCheck	complex	multiComple
valueTypeRule	√	√
requiredRule	√	√	√	√	√	√
disableRule	√	√	√	√	√	√
maxLengthRule	√	√
minLengthRule	√	√
maxValueRule	√	√
minValueRule	√	√
maxInputNumRule		√		√		√
minInputNumRule		√		√		√
maxTargetSizeRule	√	√	√	√
minTargetSizeRule	√	√	√	√
readOnlyRule	√	√	√	√	√	√
regxRule	√	√
tipRule	√	√	√	√	√	√
maxImageSizeRule	√	√	√	√
minImageSizeRule	√	√	√	√

5. 数据示例

数据过大，请点击查看全量schema查看。

四、需要特别注意的几个类型

1. 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>
 </field>

2. DevTipRule

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

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

3. DisableRule

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

4. 最大和最小规则都是区间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。

5. sizeRule和lengthRule

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

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

五、Schema体系对接思路

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

1. 变更检测

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

2. 动态映射

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

3. 关注field的type

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

4. 增量更新

增量更新的字段有限，按需提交filed的value(s)即可，新版中不需要update_fields字段。

六、商品新发步骤

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

涉及接口：

taobao.itemcats.authorize.get；

taobao.itemcats.get；

步骤二： 发布产品

说明：天猫商品需要挂靠产品，所以产品发布仅支持天猫店铺；淘宝 和 特价版商品无需挂靠产品，不需要产品发布，直接按照“步骤三”发布商品即可。

涉及接口：

tmall.product.match.schema.get( 获取匹配产品规则 )

tmall.product.schema.match( product匹配接口 )

tmall.product.schema.get( 产品信息获取schema获取 )

tmall.product.add.schema.get( 产品发布规则获取接口 )

tmall.product.schema.add( 使用Schema文件发布一个产品 )

类目：女装/女士精品 >> POLO衫(类目id：201241307) 为例说明产品发布步骤；

1）产品匹配规则获取

涉及API：tmall.product.match.schema.get；

参考示例：https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=23258；

入参：category_id = 201241307；

出参：规则xml；

如果没有返回产品匹配规则，说明该类目不需要发布产品，直接到"步骤三： 发布商品"。

2）产品匹配

涉及API：tmall.product.schema.match；

参考示例：https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=23259；

入参：category_id = 201241307；propvalues = xml_data（示例XML如下）；

<itemRule>
    <field id="prop_20000" name="品牌" type="singleCheck">
        <value>10000497</value>
    </field>
    <field id="prop_13021751" name="货号" type="input">
        <value>2157813</value>
    </field>
</itemRule>

出参：产品id；product_id = 1459669507 ；

调用tmall.product.schema.get查询产品状态【<field id="can_publish_item" name="能否发布商品" type="input">】；

产品状态（true)如果返回true则可以直接发布商品（直接到"步骤三： 发布商品"。）；

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

3）产品发布规则获取

注意：如果上一步（产品匹配）没有匹配到产品，需要自己添加。

涉及API： tmall.product.add.schema.get；

参考示例：https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=23257；

入参：category_id = 201241307 ； brand_id = 10000497；

出参：规则xml。

4）产品发布,根据上一步取到的规则组装xml

涉及API： tmall.product.schema.add；

参考示例：https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=23260；

入参：category_id = 201241307 ； brand_id = 10000497 ； xml_data ；

出参：产品id product_id；

调用tmall.product.schema.get查询产品状态【<field id="can_publish_item" name="能否发布商品" type="input">】；

产品状态（true)如果返回true则可以直接发布商品（直接到"步骤三： 发布商品"。）；

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

注意：部分产品发布后需要审核通过后才可使用，所以需要等待产品状态可用后再发布商品。

备注：

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

2）产品schema 接口继续使用老的schema SDK 协议；

新老schema协议差异

1）

字段	老协议	新协议	是否变动
ComplexField	complex-values	complex-value	是
MultiComplexField	complex-values	complex-values	否

2）所有field的default-complex-values/default-values/default-complex-value/default-value都已取消，统一用field的值取代。

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

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

1）商品规则获取 调用alibaba.item.publish.schema.get获取类目和属性规则

2）商品级联属性信息获取 调用alibaba.item.publish.props.get，当alibaba.item.publish.schema.get接口返回的某些属性的值特别多时，会提示使用此接口。根据入参获取商品级联属性信息（基本很少用到），比如alibaba.item.publish.schema.get返回如下结果是：

<field id="p-20000" name="品牌" type="singleCheck">
    <rules>
        <rule name="requiredRule" value="true"/>
        <rule name="tipRule" value="请使用SelectProp接口查询并填充完整子属性后提交" devInfo="即将废弃，请参考devTipRule"/>
        <rule name="devTipRule" value="请使用[alibaba.item.publish.props.get]接口查询并填充完整[子属性]后提交"/>
        <rule name="tipRule" value="请使用SelectProp接口查询并填充完整子属性后提交" devInfo="即将废弃，请参考devTipRule"/>
        <rule name="devTipRule" value="请使用[alibaba.item.publish.props.get]接口查询并填充完整[子属性]后提交"/>
        <rule name="devTipRule" value="如需获取全部属性值,请使用[alibaba.item.publish.props.get]接口查询"/>
    </rules>
</field>

3）商品发布alibaba.item.publish.submit进行商品上新 （注意 涉及图片上传时请使用taobao.picture.upload接口）。

备注：

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

涉及接口：

alibaba.item.publish.schema.get

alibaba.item.publish.props.get

alibaba.item.publish.submit

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

七、商品编辑更新

涉及接口

a）商品编辑获取schema信息：alibaba.item.edit.schema.get；

b）商品编辑提交schema信息：alibaba.item.edit.submit；

c）商品增量编辑：alibaba.item.edit.fastupdate；

更新分类

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

2）局部更新（局部更新API）。

1. 编辑规则获取

涉及API：alibaba.item.edit.schema.get；

参考示例：https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=53943；

说明：全量和增量编辑的规则都使用接口alibaba.item.edit.schema.get 获取；

增量编辑规则获取还需入参 fields，比如传入fields=title ，接口alibaba.item.edit.schema.get只获取 title 的编辑规则。

2. 全量编辑

涉及API：alibaba.item.edit.submit；

参考示例：https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=53968。

3. 增量编辑

涉及API：alibaba.item.edit.fastupdate；

参考示例：https://open.taobao.com/v2/doc#/apiFile?docType=2&docId=54542；

说明：

A）目前淘宝支持的增量更新字段有：

catId,bizIdentity,id，price，quantity，title，wirelessDesc，desc，barcode，outerId，video，images，recommendReason，imageVideo，sellPromise，taobaoFoodPrdLicense，taobaoFoodDesignCode，taobaoFoodFactoryName，taobaoFoodFactorySite，taobaoFoodFactoryContact，taobaoFoodPrdLicense，taobaoFoodDesignCode，taobaoFoodFactoryName，taobaoFoodFactorySite，taobaoFoodFactoryContact，taobaoFoodMix，taobaoFoodPlanStorage，taobaoFoodPeriod，taobaoFoodAdditive，taobaoFoodSupplier，taobaoFoodProduceDate，taobaoFoodStockDate，sku，descRepublicOfSell，shopcat；

i）sku 信息支持修改已有sku的图片、价格、数量、商家编码、条形码，但不能新增(删除)sku；

ii）新增sku要用全量接口。

B）天猫市场支持增量更新的字段如下：

title（标 题）

subtitle（子标题，即卖点）

show_title (展示标题)

short_title（无线短标题）

description（商品描述）

wireless_desc (旺铺无线详情描述)

vertical_image（竖图）

white_bg_image (白底图)

large_screen_image (电子大屏图)

shop_category (店铺类目)

item_image(主图)

item_wireless_images(无线主图)

image_video_type (主图视频比例类型)

main_video (主图视频)

three_to_four_item_images(3:4商品图片)

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

1）如果 image_video_type 选择1:1或者16:9类型，那么main_video 需要传值1:1或者16:9类型的视频，此时three_to_four_item_images 这个字段，不管你传值与否，都不会生效。

2）如果 image_video_type 选择3:4类型，那么 main_video 需要传值3:4类型视频，且需要同时传three_to_four_item_images 这个字段。

C）特价版支持增量更新的字段如下：

title(宝贝标题)

catProp(类目属性) 支持修改枚举类型字段，不支持修改input类型的字段；

sku(宝贝销售规格)支持修改已有sku的价格、库存、商家编码等信息，但不能新增sku；新增sku要用全量接口alibaba.item.edit.submit，并且先设置销售属性;

price(特价) 需与marketPrice同时修改；

marketPrice(划线价) 需与price同时修改；

quantity(总数量)

outerId(商家编码)

images(宝贝图片)

clearImage(非牛皮癣图)

imageVideo(主图视频)

verticalImage(宝贝长图)

desc(商品描述)

subStock(库存计数)

tbDeliveryTime(发货时效)

deliveryTimeSetBySku(按宝贝规格设置发货时间) 需与“sku-相对发货时间” 字段同时修改；

tbExtractWay(运费)

invoice(提供发票)

warranty(保修服务)

sellPromise(退换货承诺)

sevenDaySupport、sevenDayOptional(七天退货)

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

八、新版TOP schema sdk下载地址

1. 点击下载：top-schema-1.3.1.jar；

2. 点击下载：top-schema-1.3.2.jar（新增类OldSchemaReader兼容老协议）。