---
title: "元字段定义使用说明"

doc_type: static
doc_category: static
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/rest-api/metafield-definition-guide'
  md: 'https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/rest-api/metafield-definition-guide.md'
---
# 元字段定义使用说明

元字段定义（Metafield definition）用于规定元字段的数据结构、数据类型与访问权限。写入元字段值之前，建议先创建元字段定义，以便在 SHOPLINE 商家后台展示和管理元字段定义。本文说明如何通过 REST Admin API 管理元字段定义。

***

## 什么是元字段定义

元字段定义不等同于元字段值本身。元字段定义与元字段值的关系如下：

| **对象** | **说明**                | **示例**                                                      |
| ------ | --------------------- | ----------------------------------------------------------- |
| 元字段定义  | 规定元字段的字段模型、数据类型和访问权限。 | 为商品资源创建“产品简介”的元字段定义，并将数据类型设为 `multi_line_text_field`（多行文本）。 |
| 元字段值   | 存储在具体资源实例上的实际数据。      | 具体商品的“产品简介”实际内容。                                            |

元字段定义由以下核心字段组成：

| **参数名**          | **类型** | **说明**                                                                                                                    |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| `owner_resource` | string | 元字段定义所归属的资源类型，如 `products`。                                                                                               |
| `namespace`      | string | 元字段定义的命名空间，与 `key` 共同构成元字段定义的唯一标识。                                                                                        |
| `key`            | string | 元字段定义在命名空间下的唯一标识符。仅支持字母、数字、连字符与下划线。<br />最小长度限制：3<br />最大长度限制：64                                                          |
| `type`           | string | 元字段定义支持的数据类型，如 `single_line_text_field`、`boolean`。详情参见 [数据类型](https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-types.md)。                   |
| `name`           | string | 元字段定义的名称，用于在 SHOPLINE 商家后台展示。<br />最大长度限制：255                                                                             |
| `description`    | string | 元字段定义的描述。<br />最大长度限制：255                                                                                                 |
| `access.admin`   | string | 元字段定义的访问权限，详情参见 [访问权限](#访问权限)。                                                                                           |

***

## 适用场景

以下场景建议创建元字段定义：

- 需要长期维护，且数据类型和数据校验规则相对固定的扩展字段（如商品保养说明、合规标签）。

- 需要在 SHOPLINE 商家后台中展示并由商家维护的扩展字段。

- 需要限制元字段的访问和管理范围，例如仅允许创建该定义的应用访问和管理元字段。

***

## 管理元字段定义

你可以通过 REST Admin API 创建、查询、更新和删除元字段定义。

### 前置条件

在开始调用 REST Admin API 前，确认你已具备以下条件：

- 已创建应用，并完成店铺授权。

- 已根据 [应用授权](https://developer.shopline.com/zh-hans-cn/docs/apps/api-instructions-for-use/app-authorization.md) 获取有效的 access token。

- 已明确元字段定义所归属的资源类型（如 `products`、`orders`）和支持的数据类型。

### 访问权限

在创建或更新元字段定义时，可以通过 `access.admin` 配置访问权限。各权限值的访问范围如下：

| **权限值**               | **创建该定义的应用**               | **SHOPLINE 商家后台** | **其他应用** |
| --------------------- | -------------------------- | ----------------- | -------- |
| `MERCHANT_READ_WRITE` | 可管理元字段定义                   | 可管理元字段定义和元字段值     | 不可读写     |
| `MERCHANT_READ`       | 可管理元字段定义                   | 仅可查看元字段定义，不可删除    | 不可读写     |
| `PUBLIC_READ`         | 可管理元字段定义                   | 仅可查看元字段定义，不可删除    | 只读       |
| `PRIVATE`             | 可通过 REST Admin API 管理元字段定义 | 不支持查看             | 不可读写     |
| `NONE`                | 可管理元字段定义                   | 可管理元字段定义和元字段值     | 可读写      |

### 配置数据校验规则

在创建或更新元字段定义时，可以通过 `validations` 根据数据类型配置相应的数据校验规则。数据校验规则用于约束允许写入元字段的值，避免无效或错误数据。`validations` 包含以下字段：

| **参数名** | **类型** | **说明**                              | **示例**     |
| ------- | ------ | ----------------------------------- | ---------- |
| `name`  | string | 数据校验规则的名称。枚举值为固定枚举，具体取值取决于元字段的数据类型。 | `list.min` |
| `value` | string | 数据校验规则的值。                           | `2`        |

完整规则名称、支持的数据类型、规则的值格式与校验方式参见 [数据校验规则](https://developer.shopline.com/zh-hans-cn/docs/apps/metafields/references/data-validation-rules.md)。

> **注意**
>
> - 每个数据校验规则名称在同一元字段定义中最多出现一次。
> - 修改 `validations` 后，SHOPLINE 会异步扫描存量元字段值；不符合新规则的存量值会被标记为无效。
> - 更新元字段定义时，请求体中 `validations` 为空数组时表示清空数据校验规则。

### 创建元字段定义

端点：`POST /metafield_definition.json`

为指定资源（`owner_resource`）创建元字段定义。接口详情参见 [创建元字段定义](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafield-definition/create-a-metafield-definition.md)。建议使用最新稳定版本。

#### 请求示例

```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": "size_fields",
      "key": "size_label",
      "name": "Size label",
      "description": "Product size label",
      "type": "single_line_text_field",
      "validations": [
        {
          "name": "choices",
          "value": "[\"S\",\"M\",\"L\",\"XL\"]"
        }
      ]
    }
  }'
```

#### 响应示例

建议保存响应中的 `id`、`key` 和 `namespace`，供后续查询、更新与写入元字段值使用。

```json
{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Product size label",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-04-15T16:21:03+08:00"
  }
}
```

### 查询元字段定义

端点：`GET /metafield_definition.json`

根据元字段定义 ID 查询元字段定义详情。接口详情参见 [查询元字段定义](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafield-definition/get-a-metafield-definition.md)。建议使用最新稳定版本。

#### 请求示例

```bash
curl --request GET 'https://{handle}.myshopline.com/admin/openapi/v20260901/metafield_definition.json?id={definition_id}' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --header 'Authorization: Bearer {access_token}'
```

#### 响应示例

```json
{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Product size label",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-04-15T16:21:03+08:00"
  }
}
```

### 更新元字段定义

端点：`PUT /metafield_definition.json`

更新已有元字段定义的名称、描述和访问权限等信息。接口中非必填字段不传和传 `null` 则保留原值，传空字符串表示清空数据。接口详情参见 [更新元字段定义](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafield-definition/update-a-metafield-definition.md)。建议使用最新稳定版本。

#### 请求示例

```bash
curl --request PUT '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": "size_fields",
      "key": "size_label",
      "name": "Size label",
      "description": "Updated description"
    }
  }'
```

#### 响应示例

```json
{
  "definition": {
    "id": 43601019606,
    "owner_resource": "products",
    "namespace": "size_fields",
    "key": "size_label",
    "name": "Size label",
    "description": "Updated description",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"S\",\"M\",\"L\",\"XL\"]"
      }
    ],
    "access": null,
    "created_at": "2025-04-15T16:21:03+08:00",
    "updated_at": "2025-07-15T16:54:00+08:00"
  }
}
```

### 删除元字段定义

端点：`DELETE /metafield_definition.json`

删除指定的元字段定义。接口详情参见 [删除元字段定义](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafield-definition/delete-a-metafield-definition.md)。建议使用最新稳定版本。

> **注意**
>
> 删除元字段定义可能影响线上数据与主题展示。生产环境操作前确认是否备份或迁移关联元字段值。

***

## 常见问题

### 何时必须先创建元字段定义

当你需要为元字段值配置数据校验规则、在 SHOPLINE 商家后台中展示和管理字段，或设置访问权限时，应先创建元字段定义。若仅需快速写入元字段值、且可接受未定义元字段的管理限制，可考虑使用 [批量操作元字段](https://developer.shopline.com/zh-hans-cn/docs/admin-rest-api/shopline-metafields/metafields/resource-metafields/operate-metafields-in-bulk.md) 接口直接写入元字段值。

### 数据校验规则应在哪一步配置

在创建或更新元字段定义时通过 `validations` 配置数据校验规则。写入元字段值时无需重复传入数据校验规则，系统会根据关联的元字段定义自动校验该值。
