---
title: "数据校验规则"

doc_type: static
doc_category: static
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-validation-rules'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-validation-rules.md'
---
# 数据校验规则

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

***

## 工作原理

元字段校验分为两层：

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

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

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

***

## 数据结构

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

| **参数名** | **类型** | **说明**                                              |
| ------- | ------ | --------------------------------------------------- |
| `name`  | string | 数据校验规则的名称。枚举值为固定枚举，仅支持 [数据校验规则总览](#数据校验规则总览) 中列出的规则名称。 |
| `value` | string | 数据校验规则的值。                                           |

例如：

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

通用约束：

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

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

- 调用 [更新元字段定义](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafield-definition/update-a-metafield-definition.md) 接口时，传入空的 `validations` 数组表示清空数据校验规则。

***

## 配置数据校验规则

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

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

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

### 请求示例

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

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

```bash
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`。

```bash
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` ）格式，以及写入元字段值时的校验行为。


> **提示**
>
> 整体约束：
> 
> - 对于数据类型中的 [列表类型](https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-types.md#列表类型)（`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 字符串数组，不允许包含重复值或换行符。<br />最大个数限制：128 <br />最大长度限制：300,000                                                                                                                                 | 元字段的值必须在选项列表中。<br />对于列表类型（`list.*`）将逐个校验非空元素。 |
| `allowed_domains`          | 允许的 URL 域名     | `url`、`list.url`、`link`、`list.link`                                                                                                                                                                                                                                                     | 非空 JSON 字符串数组。每个元素必须为带白名单协议的完整 URL，不支持裸域名。<br />最大个数限制：100                                                                                                                                 | 对 `url` 类型直接校验。对 `link` 类型校验其 `url` 字段。        |
| `file_type_options`        | 允许的文件类型        | `file_reference`、`list.file_reference`                                                                                                                                                                                                                                                  | JSON 字符串数组。空字符串数组表示不限制文件类型。<br />例如，`[\"Image\",\"Video\"]` 表示仅允许图片或视频文件，包括 JPEG、JPG、PNG、WEBP、SVG、GIF 和 MP4 等格式。                                                                           | 根据配置的文件类型校验。                                   |
| `list.min`                 | 列表最小元素个数       | 所有 [列表类型](https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-types.md#列表类型)（`list.*`）                                                                                                                                                                                                          | 非负整数字符串，最大值为 `128`。                                                                                                                                                                        | 数组元素个数不得小于该值。                                  |
| `list.max`                 | 列表最大元素个数       | 所有 [列表类型](https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-types.md#列表类型)（`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` | 格式取决于数据类型：<br />  **•** `date` 与 `date_time` 使用对应的 [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) 格式。<br /> **•** `number_decimal`、`list.number_decimal` 支持负数，其他数值类型仅支持非负数。<br /> | 元字段的值不得小于边界。对于列表类型，逐个校验非空元素。                   |
| `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`。                      |
| `schema`                   | JSON Schema 规范 | `json`                                                                                                                                                                                                                                                                                  | [JSON Schema 规范](https://json-schema.org/specification) 字符串。                                                                                                                               | 元字段的值必须符合该 JSON Schema 规范。                     |
| `metaobject_definition_id` | 引用的元对象定义 ID。   | `metaobject_reference`、`list.metaobject_reference`                                                                                                                                                                                                                                      | 数字 ID 或 全局 ID (GID)，例如 `gid://shopline/MetaobjectDefinition/{id}`。                                                                                                                         | 校验引用的元对象定义是否存在。                                |

***

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

### `choices`：预设选项

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

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

### `allowed_domains`：允许域名

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

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

### `file_type_options`：文件类型

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

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

### `list.min` 与 `list.max`：列表长度

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

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

### `min` 与 `max`：边界值

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

#### 文本长度限制示例

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

#### 日期限制示例

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

#### 重量限制示例

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

### `max_precision`：小数精度

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

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

### `regex`：正则表达式

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

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

### `scale_min` 与 `scale_max`：评分刻度

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

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

### `schema`：JSON Schema

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

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

### `metaobject_definition_id`：元对象引用

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

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

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

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

***

## 注意事项

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

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

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