数据校验规则

元字段定义（Metafield definition）支持通过数据校验规则约束元字段值。在基础类型校验的基础上，你还可以限制元字段值的取值范围或格式。例如，你可以限制单行文本只能从预设选项中选择、限制小数最多保留两位、或要求 URL 仅指向指定域名。本文说明各校验选项的适用数据类型、传值格式，以及如何在 REST Admin API 中配置数据校验规则。

工作原理​

元字段校验分为两层：

  1. 基础类型校验：校验数据类型是否支持，以及元字段的值是否符合该类型的基础格式。

  2. 定义级校验：在基础类型校验通过后，根据元字段定义中配置的数据校验规则继续校验元字段的值。

数据校验规则在创建或更新元字段定义时配置。写入元字段的值时，系统会读取关联定义上的数据校验规则并执行校验。基础类型校验不通过时，不会进入定义级规则校验。

数据结构​

validations 是数据校验规则对象的数组。每个规则对象必须包含非空的 name 和 value 字段。

参数名类型说明
namestring数据校验规则的名称。枚举值为固定枚举，仅支持 数据校验规则总览 中列出的规则名称。
valuestring数据校验规则的值。

例如：

[
  {"name": "regex", "value": "^[A-Z0-9]+$"},
  {"name": "choices", "value": "[\"S\",\"M\",\"L\"]"}
]

通用约束：

  • 同一元字段定义中，每个数据校验规则名称最多出现一次。重复配置会导致创建或更新元字段定义失败。

  • 单条 value 的最大长度为 300,000 个字符。

  • 调用 更新元字段定义 接口时，传入空的 validations 数组表示清空数据校验规则。

配置数据校验规则​

通过 REST Admin API 创建或更新元字段定义时，在请求体的 definition 对象中传入 validations 数组来配置数据校验规则。

name 的枚举值为固定枚举，仅支持 数据校验规则总览 中列出的规则名称。传入未支持的规则名称时，创建或更新元字段定义会失败。

value 在 API 中始终是字符串。即使规则语义上是数字或数组，也须以字符串形式提交，勿省略外层引号。

请求示例​

创建包含单个数据校验规则的元字段定义​

为商品创建 Size label 元字段定义，其元字段值仅可为 S、M、L 或 XL。

curl --request POST 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "definition": {
      "owner_resource": "products",
      "namespace": "$app:size_fields",
      "key": "size_label",
      "name": "Size label",
      "type": "single_line_text_field",
      "validations": [
        {
          "name": "choices",
          "value": "[\"S\",\"M\",\"L\",\"XL\"]"
        }
      ],
      "access": {
        "admin": "MERCHANT_READ_WRITE"
      }
    }
  }'

创建包含多个校验规则的元字段定义​

为商品创建 Package weight 元字段定义，数据类型为 weight，并将元字段值限制在 10g 至 500g。

curl --request POST 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}' \
  --data '{
    "definition": {
      "owner_resource": "products",
      "namespace": "$app:spec_fields",
      "key": "package_weight",
      "name": "Package weight",
      "type": "weight",
      "validations": [
        {
          "name": "min",
          "value": "{\"unit\":\"g\",\"value\":10}"
        },
        {
          "name": "max",
          "value": "{\"unit\":\"g\",\"value\":500}"
        }
      ],
      "access": {
        "admin": "MERCHANT_READ_WRITE"
      }
    }
  }'

数据校验规则总览​

下表汇总各规则名称、含义、支持的数据类型（type）和规则的值（ value ）格式，以及写入元字段值时的校验行为。

提示

整体约束：

  • 对于数据类型中的 列表类型（list.*），list.min 和 list.max 用于限制数组元素数量；其他校验规则用于校验每个非空元素。
  • 从 v20260901 版本开始，元字段的值不可为空。
  • min 必须小于等于 max，list.min 必须小于等于 list.max，scale_min 必须小于等于 scale_max。
规则名称含义支持的数据类型规则的值格式校验方式
choices预设选项列表single_line_text_field、list.single_line_text_field非空 JSON 字符串数组，不允许包含重复值或换行符。
最大个数限制：128
最大长度限制：300,000		元字段的值必须在选项列表中。
对于列表类型（list.*）将逐个校验非空元素。
allowed_domains允许的 URL 域名url、list.url、link、list.link非空 JSON 字符串数组。每个元素必须为带白名单协议的完整 URL，不支持裸域名。
最大个数限制：100		对 url 类型直接校验。对 link 类型校验其 url 字段。
file_type_options允许的文件类型file_reference、list.file_referenceJSON 字符串数组。空字符串数组表示不限制文件类型。
例如，[\"Image\",\"Video\"] 表示仅允许图片或视频文件，包括 JPEG、JPG、PNG、WEBP、SVG、GIF 和 MP4 等格式。		根据配置的文件类型校验。
list.min列表最小元素个数所有 列表类型（list.*）非负整数字符串，最大值为 128。数组元素个数不得小于该值。
list.max列表最大元素个数所有 列表类型（list.*）非负整数字符串，最大值为 128。数组元素个数不得大于该值。
min最小边界single_line_text_field、multi_line_text_field、date、list.date、date_time、list.date_time、weight、list.weight、volume、list.volume、dimension、list.dimension、number_integer、list.number_integer、number_decimal、list.number_decimal、list.single_line_text_field格式取决于数据类型：
• date 与 date_time 使用对应的 ISO 8601 格式。
• number_decimal、list.number_decimal 支持负数，其他数值类型仅支持非负数。
元字段的值不得小于边界。对于列表类型，逐个校验非空元素。
max最大边界同 min。同 min。元字段的值不得大于边界。对于列表类型，逐个校验非空元素。
max_precision小数最大精度number_decimal、list.number_decimal非负整数字符串，最大值为 9。小数位数不得超过该值。对于列表类型，逐个校验非空元素。
regex正则表达式single_line_text_field、multi_line_text_field、list.single_line_text_field正则表达式字符串。元字段的值必须匹配元字段定义中配置的正则表达式。对于列表类型，逐个校验非空元素。
scale_min评分下界rating、list.rating小数字符串。必须与 scale_max 一同配置，且不大于 scale_max。元字段的值必须大于或等于 scale_min。
scale_max评分上界rating、list.rating小数字符串。必须与 scale_min 一同配置，且不小于 scale_min。元字段的值必须小于或等于 scale_max。
schemaJSON Schema 规范jsonJSON Schema 规范 字符串。元字段的值必须符合该 JSON Schema 规范。
metaobject_definition_id引用的元对象定义 ID。metaobject_reference、list.metaobject_reference数字 ID 或 全局 ID (GID)，例如 gid://shopline/MetaobjectDefinition/{id}。校验引用的元对象定义是否存在。

各数据校验规则说明与示例​

choices：预设选项​

限制元字段值只能从指定选项中选择，适用于尺码、风味标签等固定选项场景。例如：

"validations": [
  {
    "name": "choices",
    "value": "[\"Floral\",\"Sweet\",\"Nutty\",\"Other\"]"
  }
]

allowed_domains：允许域名​

限制 url 或 link 类型元字段只能指向指定域名，适用于社交链接、站内跳转等场景。例如：

"validations": [
  {
    "name": "allowed_domains",
    "value": "[\"https://www.shopline.com\",\"https://developer.shopline.com\"]"
  }
]

file_type_options：文件类型​

限制文件引用类型元字段允许的文件类型。例如，可仅允许图片或视频文件：

"validations": [
  {
    "name": "file_type_options",
    "value": "[\"Image\",\"Video\"]"
  }
]

list.min 与 list.max：列表长度​

限制列表类型元字段的元素数量。例如：

"validations": [
  {"name": "list.min", "value": "2"},
  {"name": "list.max", "value": "5"}
]

min 与 max：边界值​

限制元字段值的最小值和最大值。min 和 max 的含义取决于元字段定义的数据类型，可用于限制文本长度、日期范围或数值范围。例如：

文本长度限制示例​

"validations": [
  {"name": "min", "value": "8"},
  {"name": "max", "value": "100"}
]

日期限制示例​

"validations": [
  {"name": "min", "value": "2026-01-01"},
  {"name": "max", "value": "2026-12-31"}
]

重量限制示例​

"validations": [
  {"name": "min", "value": "{\"unit\":\"g\",\"value\":10}"},
  {"name": "max", "value": "{\"unit\":\"g\",\"value\":500}"}
]

max_precision：小数精度​

限制小数类型元字段的小数位数。例如：

"validations": [
  {"name": "max_precision", "value": "2"}
]

regex：正则表达式​

限制文本类型元字段值的格式。例如：

"validations": [
  {
    "name": "regex",
    "value": "^[A-Z0-9]+$"
  }
]

scale_min 与 scale_max：评分刻度​

限制评分类型元字段的评分下限和上限。例如：

"validations": [
  {"name": "scale_min", "value": "1"},
  {"name": "scale_max", "value": "5"}
]

schema：JSON Schema​

限制 json 类型元字段值的格式，使其符合指定的 JSON Schema 规范。例如：

"validations": [
  {
    "name": "schema",
    "value": "{\"type\":\"object\",\"properties\":{\"title\":{\"type\":\"string\"},\"stock\":{\"type\":\"integer\",\"minimum\":0}},\"required\":[\"title\"]}"
  }
]

metaobject_definition_id：元对象引用​

限制元对象引用类型的元字段只能引用指定元对象定义下的元对象。以下示例传入元对象定义的全局 ID（GID），用于指定元字段可引用的元对象定义。例如：

"validations": [
  {
    "name": "metaobject_definition_id",
    "value": "gid://shopline/MetaobjectDefinition/123"
  }
]

也支持传入元对象定义的数字 ID：

"validations": [
  {"name": "metaobject_definition_id", "value": "123"}
]

注意事项​

使用数据校验规则前，注意以下限制和影响：

  • 数据校验规则仅约束元字段的值范围或格式，不能替代元字段数据类型的选择。

  • 修改元字段定义的数据校验规则后，系统会异步扫描已有元字段值，不符合规则校验的元字段值会被标记为无效，可在 SHOPLINE 商家后台查看无效值。

这篇文章对你有帮助吗？
SHOPLINE
SHOPLINE
SHOPLINE Enterprise
条款协议
隐私
条款
开发者协议
LinkedInEmail
LinkedInEmail
© Copyright 2013-2026 SHOPLINE Limited.