Data validation rules

Metafield definitions support using data validation rules to constrain metafield values. In addition to basic type validation, you can restrict the range or format of metafield values. For example, you can limit single-line text to predefined options, limit decimals to two decimal places, or require URLs to point only to specified domains. This article describes the supported data types, value formats, and configuration methods for each validation rule in the REST Admin API.

How it works​

Metafield validation has two levels:

1. Basic type validation: Validates whether the data type is supported and whether the metafield value matches the basic format of that data type.

2. Definition-level validation: After basic type validation succeeds, applies the data validation rules configured in the metafield definition to validate the metafield value.

Data validation rules are configured when creating or updating a metafield definition. When writing a metafield value, the associated metafield definition applies its data validation rules to validate the value. If basic type validation fails, definition-level validation does not run.

Structure​

validations is an array of data validation rule objects. Each rule object must contain nonempty name and value fields.

For example:

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

General constraints:

• Each data validation rule name can appear only once in the same metafield definition. Duplicate rules cause metafield definition creation or update to fail.

• The maximum length of a single value is 300,000 characters.

• When calling the Update a metafield definition API, an empty validations array indicates that all data validation rules are cleared.

Configure data validation rules​

When creating or updating a metafield definition through the REST Admin API, pass the validations array in the request body’s definition object to configure data validation rules.

name has a fixed set of valid values. Only rule names listed in the Data validation rule overview are supported. Metafield definition creation or update fails if you pass an unsupported rule name.

value is always a string in the API. Even if a rule semantically represents a number or an array, submit it as a string and do not omit the outer quotation marks.

Request examples​

Create a metafield definition with a single data validation rule​

Create a Size label metafield definition for products. Its metafield value can only be S, M, L, or 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"
      }
    }
  }'

Create a metafield definition with multiple data validation rules​

Create a Package weight metafield definition for products with the weight data type. Its metafield value is limited to 10g through 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"
      }
    }
  }'

Data validation rule overview​

The following table summarizes each rule name, meaning, supported data types (type), the rule value (value) format, and validation behavior when writing metafield values.

Data validation rule details and examples​

choices: Predefined options​

Restricts metafield values to specified options. This rule is suitable for fixed-option scenarios such as size or flavor labels. For example:

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

allowed_domains: Allowed domains​

Restricts url or link metafields to specified domains. This rule is suitable for social links and internal navigation. For example:

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

file_type_options: File types​

Restricts the file types allowed for file reference metafields. For example, you can allow only image or video files:

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

list.min and list.max: List length​

Restricts the number of elements in list metafields. For example:

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

min and max: Boundary values​

Restricts the minimum and maximum values of metafield values. The meaning of min and max depends on the data type of the metafield definition. You can use them to limit text length, date ranges, or numeric ranges. For example:

Text length example​

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

Date range example​

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

Weight range example​

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

max_precision: Decimal precision​

Restricts the number of decimal places for decimal metafields. For example:

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

regex: Regular expression​

Restricts the format of text metafield values. For example:

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

scale_min and scale_max: Rating scale​

Restricts the lower and upper bounds of rating metafields. For example:

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

schema: JSON Schema​

Restricts the format of json metafield values to comply with a specified JSON Schema. For example:

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

metaobject_definition_id: Metaobject reference​

Restricts metaobject reference metafields to reference metaobjects that belong to a specified metaobject definition. The following example passes the global ID (GID) of a metaobject definition to specify the metaobject definition that the metafield can reference:

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

You can also pass the numeric ID of a metaobject definition:

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

Notes​

Before using data validation rules, note the following limitations and effects:

• Data validation rules only constrain the range or format of metafield values. They cannot replace selecting a metafield data type.

• After you modify the data validation rules of a metafield definition, SHOPLINE asynchronously scans existing metafield values. Metafield values that do not meet the rules are marked as invalid and can be viewed in the SHOPLINE Admin.