---
title: " Data validation rules"

doc_type: static
doc_category: static
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/docs/apps/metafields/references/data-validation-rules'
  md: 'https://developer.shopline.com/docs/apps/metafields/references/data-validation-rules.md'
---
# 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.

| **Parameter** | **Type** | **Description**                                                                                                                                         |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string   | The name of the data validation rule. Valid values are predefined. Only rule names listed in the [Data validation rule overview](#data-validation-rule-overview) are supported. |
| `value`       | string   | The value of the data validation rule.                                                                                                                  |

For example:

```json
[
  {"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](https://developer.shopline.com/docs/admin-rest-api/shopline-metafields/metafield-definition/update-a-metafield-definition.md) 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](#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`.

```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"
      }
    }
  }'
```

#### 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`.

```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"
      }
    }
  }'
```

***

## 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.

> **TIP**
>
> General constraints:
> 
> - For [list types](https://developer.shopline.com/docs/apps/metafields/references/data-types.md#list-types) (`list.*`), `list.min` and `list.max` limit the number of array elements. Other validation rules validate each nonempty element.
> - Starting with version `v20260901`, metafield values cannot be empty.
> - `min` must be less than or equal to `max`, `list.min` must be less than or equal to `list.max`, and `scale_min` must be less than or equal to `scale_max`.

| **Rule name**              | **Meaning**                         | **Supported data types**                                                                                                                                                                                                                                                                                | **Rule value format**                                                                                                                                                                                                                                                                               | **Validation behavior**                                                                                                                           |
| -------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `choices`                  | Predefined option list              | `single_line_text_field`, `list.single_line_text_field`                                                                                                                                                                                                                                                 | A nonempty JSON array of strings. Duplicate values and newline characters are not allowed.  <br /> Maximum size: 128 <br />  Maximum length: 300,000                                                                                                                                                            | The metafield value must be in the option list.   For list types (`list.*`), each nonempty element is validated.                                  |
| `allowed_domains`          | Allowed URL domains                 | `url`, `list.url`, `link`, `list.link`                                                                                                                                                                                                                                                                  | A nonempty JSON array of strings. Each element must be a complete URL with an allowed protocol. Bare domain names are not supported.  <br /> Maximum size: 100                                                                                                                                            | Validates `url` types directly. For `link` types, validates the `url` field.                                                                      |
| `file_type_options`        | Allowed file types                  | `file_reference`, `list.file_reference`                                                                                                                                                                                                                                                                 | A JSON array of strings. An empty array means that file types are not restricted.   For example, `[\"Image\",\"Video\"]` allows only image or video files, including JPEG, JPG, PNG, WEBP, SVG, GIF, and MP4 files.                                                                                 | Validates against the configured file types.                                                                                                      |
| `list.min`                 | Minimum number of list elements     | All [list types](https://developer.shopline.com/docs/apps/metafields/references/data-types.md#list-types) (`list.*`)                                                                                                                                                                                                            | A nonnegative integer string with a maximum value of `128`.                                                                                                                                                                                                                                         | The number of array elements must not be less than this value.                                                                                    |
| `list.max`                 | Maximum number of list elements     | All [list types](https://developer.shopline.com/docs/apps/metafields/references/data-types.md#list-types) (`list.*`)                                                                                                                                                                                                            | A nonnegative integer string with a maximum value of `128`.                                                                                                                                                                                                                                         | The number of array elements must not be greater than this value.                                                                                 |
| `min`                      | Minimum boundary                    | `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` | The format depends on the data type:<br /> **•** `date` and `date_time` use the corresponding [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.<br /> **•** `number_decimal` and `list.number_decimal` support negative values. Other numeric types support nonnegative values only. | The metafield value must not be less than the boundary. For list types, each nonempty element is validated.                                       |
| `max`                      | Maximum boundary                    | Same as `min`.                                                                                                                                                                                                                                                                                          | Same as `min`.                                                                                                                                                                                                                                                                                      | The metafield value must not be greater than the boundary. For list types, each nonempty element is validated.                                    |
| `max_precision`            | Maximum decimal precision           | `number_decimal`, `list.number_decimal`                                                                                                                                                                                                                                                                 | A nonnegative integer string with a maximum value of `9`.                                                                                                                                                                                                                                           | The number of decimal places must not exceed this value. For list types, each nonempty element is validated.                                      |
| `regex`                    | Regular expression                  | `single_line_text_field`, `multi_line_text_field`, `list.single_line_text_field`                                                                                                                                                                                                                        | A regular expression string.                                                                                                                                                                                                                                                                        | The metafield value must match the regular expression configured in the metafield definition. For list types, each nonempty element is validated. |
| `scale_min`                | Minimum rating scale                | `rating`, `list.rating`                                                                                                                                                                                                                                                                                 | A decimal string. Must be configured with `scale_max` and must not be greater than `scale_max`.                                                                                                                                                                                                     | The metafield value must be greater than or equal to `scale_min`.                                                                                 |
| `scale_max`                | Maximum rating scale                | `rating`, `list.rating`                                                                                                                                                                                                                                                                                 | A decimal string. Must be configured with `scale_min` and must not be less than `scale_min`.                                                                                                                                                                                                        | The metafield value must be less than or equal to `scale_max`.                                                                                    |
| `schema`                   | JSON Schema specification           | `json`                                                                                                                                                                                                                                                                                                  | A [JSON Schema specification](https://json-schema.org/specification) string.                                                                                                                                                                                                                        | The metafield value must comply with the JSON Schema specification.                                                                               |
| `metaobject_definition_id` | Referenced metaobject definition ID | `metaobject_reference`, `list.metaobject_reference`                                                                                                                                                                                                                                                     | A numeric ID or global ID (GID), for example, `gid://shopline/MetaobjectDefinition/{id}`.                                                                                                                                                                                                           | Validates whether the referenced metaobject definition exists.                                                                                    |

***

## 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:

```json
"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:

```json
"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:

```json
"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:

```json
"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

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

#### Date range example

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

#### Weight range example

```json
"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:

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

### `regex`: Regular expression

Restricts the format of text metafield values. For example:

```json
"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:

```json
"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:

```json
"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:

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

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

```json
"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.
