新版schema商品发布

更新时间：2024/01/12 访问次数：123629

一、背景
二、相关API
三、Schema体系说明规则
四、需要特别注意的几个类型
五、Schema体系对接思路
六、商品新发步骤
七、商品编辑更新
八、新版TOP schema sdk下载地址

一、背景

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

二、相关API

1. 商品发布

a）获取商品发布规则信息：alibaba.item.publish.schema.get；

b）商品级联属性信息获取：alibaba.item.publish.props.get；

c）商品发布：alibaba.item.publish.submit；

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兼容老协议）。

FAQ

关于此文档暂时还没有FAQ

有用(0) 我要提问

开放平台

基础技术

新版schema商品发布

一、背景

二、相关API

1. 商品发布

2. 商品编辑

3. 商品管理

三、Schema体系说明规则

1. type类型说明

2. rule类型说明

3. depend-express支持的symbol

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

5. 数据示例

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

1. TipRule

2. DevTipRule

3. DisableRule

4. 最大和最小规则都是区间rule

5. sizeRule和lengthRule

五、Schema体系对接思路

1. 变更检测

2. 动态映射

3. 关注field的type

4. 增量更新

六、商品新发步骤

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

步骤二： 发布产品

1）产品匹配规则获取

2）产品匹配

3）产品发布规则获取

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

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

七、商品编辑更新

1. 编辑规则获取

2. 全量编辑

3. 增量编辑

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

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

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

八、新版TOP schema sdk下载地址

FAQ

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

步骤二：发布产品

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