---
title: "Data types"

doc_type: static
doc_category: static
doc_version: v20260901
source_url:
  html: 'https://developer.shopline.com/docs/apps/metafields/references/data-types'
  md: 'https://developer.shopline.com/docs/apps/metafields/references/data-types.md'
---
# Data types

[Metafields](https://developer.shopline.com/docs/apps/metafields/overview.md) use data types to define the content that can be stored. Each data type has built-in format validation. Regardless of the data type, metafield values are passed and stored as strings. In theme templates, you can access metafields through the [`metafield`](https://developer.shopline.com/docs/sline/object/metafield.md) object.

---

## Base types

Base type metafields store text, numbers, dates, and measurements with units.

| Type                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Value type  |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- |
| `boolean`                | A boolean value (`true` or `false`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | boolean     |
| `color`                  | A hexadecimal color code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | string      |
| `date`                   | A date in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without a time zone.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | string      |
| `date_time`              | A date and time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without a time zone. Greenwich Mean Time (GMT) is used by default.                                                                                                                                                                                                                                                                                                                                                                                                                | string      |
| `dimension`              | A numeric length value and unit.<br />Valid units are:<ul><li><code>mm</code>: Millimeters</li><li><code>cm</code>: Centimeters</li><li><code>m</code>: Meters</li><li><code>in</code>: Inches</li><li><code>ft</code>: Feet</li><li><code>yd</code>: Yards</li></ul>                                                                                                                                                                                                                                                                                                          | JSON object |
| `json`                   | A JSON-serializable value, which can be an object, array, string, number, boolean value, or `null`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | JSON object |
| `link`                   | A combination of text and a URL for storing link content.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | JSON object |
| `money`                  | A monetary amount with a currency code that matches the store currency.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | JSON object |
| `multi_line_text_field`  | A multiline text field with a maximum size of 65 KB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | string      |
| `number_decimal`         | A decimal number ranging from -9,999,999,999,999.999999999 to 9,999,999,999,999.999999999.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | string      |
| `number_integer`         | An integer ranging from -9,999,999,999,999 to 9,999,999,999,999.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | integer     |
| `rating`                 | A rating within a specified range. The `scale_min` and `scale_max` validation parameters are required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | JSON object |
| `rich_text_field`        | A [rich text field](#rich-text-format) that supports headings, lists, links, bold text, and italic text.                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | JSON object |
| `single_line_text_field` | A single-line text field with a maximum size of 65 KB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | string      |
| `url`                    | A URL that supports the following protocols: `https`, `http`, `mailto`, `sms`, and `tel`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | string      |
| `volume`                 | A numeric volume value and unit.<br />Valid units are:<ul><li><code>ml</code>: Milliliters</li><li><code>cl</code>: Centiliters</li><li><code>l</code>: Liters</li><li><code>m3</code>: Cubic meters</li><li><code>us_fl_oz</code>: US fluid ounces</li><li><code>us_pt</code>: US pints</li><li><code>us_qt</code>: US quarts</li><li><code>us_gal</code>: US gallons</li><li><code>imp_fl_oz</code>: Imperial fluid ounces</li><li><code>imp_pt</code>: Imperial pints</li><li><code>imp_qt</code>: Imperial quarts</li><li><code>imp_gal</code>: Imperial gallons</li></ul> | JSON object |
| `weight`                 | A numeric weight value and unit.<br />Valid units are:<ul><li><code>kg</code>: Kilograms</li><li><code>g</code>: Grams</li><li><code>lb</code>: Pounds</li><li><code>oz</code>: Ounces</li></ul>                                                                                                                                                                                                                                                                                                                                                                               | JSON object |

---

## Base type code examples

The following examples show the expected value format for each base type:

<table>
<thead>
<tr><th>Type</th><th>Example</th></tr>
</thead>
<tbody>
<tr>
<td><code>boolean</code></td>
<td>

```
true
```

</td>
</tr>
<tr>
<td><code>color</code></td>
<td>

```
#e84c3d
```

</td>
</tr>
<tr>
<td><code>date</code></td>
<td>

```
2026-04-24
```

</td>
</tr>
<tr>
<td><code>date_time</code></td>
<td>

```
2026-04-24T12:30:00
```

</td>
</tr>
<tr>
<td><code>dimension</code></td>
<td>

```json
{
  "value": 25.5,
  "unit": "cm"
}
```

</td>
</tr>
<tr>
<td><code>json</code></td>
<td>

```json
{
  "title": "Summer collection",
  "stock": 100
}
```

</td>
</tr>
<tr>
<td><code>link</code></td>
<td>

```json
{
  "text": "Learn more",
  "url": "https://www.shopline.com"
}
```

</td>
</tr>
<tr>
<td><code>money</code></td>
<td>

```json
{
  "amount": "5.99",
  "currency_code": "CNY"
}
```

</td>
</tr>
<tr>
<td><code>multi_line_text_field</code></td>
<td>

```
Ingredients
Flour
Water
Milk
```

</td>
</tr>
<tr>
<td><code>number_decimal</code></td>
<td>

```
9.99
```

</td>
</tr>
<tr>
<td><code>number_integer</code></td>
<td>

```
42
```

</td>
</tr>
<tr>
<td><code>rating</code></td>
<td>

```json
{
  "value": "4.0",
  "scale_min": "1.0",
  "scale_max": "5.0"
}
```

</td>
</tr>
<tr>
<td><code>rich_text_field</code></td>
<td>

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Bold text.",
          "bold": true
        }
      ]
    }
  ]
}
```

</td>
</tr>
<tr>
<td><code>single_line_text_field</code></td>
<td>

```
Express shipping
```

</td>
</tr>
<tr>
<td><code>url</code></td>
<td>

```
https://www.shopline.com
```

</td>
</tr>
<tr>
<td><code>volume</code></td>
<td>

```json
{
  "value": 20.5,
  "unit": "ml"
}
```

</td>
</tr>
<tr>
<td><code>weight</code></td>
<td>

```json
{
  "value": 2.5,
  "unit": "kg"
}
```

</td>
</tr>
</tbody>
</table>

---

## Reference types

Reference type metafields store references to store resources.

| Type                   | Description                          | Value type |
| ---------------------- | ------------------------------------ | ---------- |
| `collection_reference` | A reference to a product collection. | string     |
| `file_reference`       | A reference to a file.               | string     |
| `metaobject_reference` | A reference to a metaobject entry.   | string     |
| `page_reference`       | A reference to a page.               | string     |
| `product_reference`    | A reference to a product.            | string     |
| `variant_reference`    | A reference to a product variant.    | string     |
| `article_reference`    | A reference to an article.           | string     |

---

## Reference type code examples

<table>
<thead>
<tr><th>Type</th><th>Example</th></tr>
</thead>
<tbody>
<tr>
<td><code>collection_reference</code></td>
<td>

```
gid://shopline/collections/1
```

</td>
</tr>
<tr>
<td><code>file_reference</code></td>
<td>

```
gid://shopline/MediaImage/123
```

</td>
</tr>
<tr>
<td><code>metaobject_reference</code></td>
<td>

```
gid://shopline/Metaobject/2
```

</td>
</tr>
<tr>
<td><code>page_reference</code></td>
<td>

```
gid://shopline/Page/1
```

</td>
</tr>
<tr>
<td><code>product_reference</code></td>
<td>

```
gid://shopline/Product/1
```

</td>
</tr>
<tr>
<td><code>variant_reference</code></td>
<td>

```
gid://shopline/ProductVariant/1
```

</td>
</tr>
<tr>
<td><code>article_reference</code></td>
<td>

```
gid://shopline/Article/1
```

</td>
</tr>
</tbody>
</table>

---

## List types

List type metafields store multiple values in a single metafield. Values are represented as JSON arrays. Each list type metafield can contain up to 128 elements.

| Type                          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list.color`                  | A list of hexadecimal color codes.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `list.collection_reference`   | A list of product collection references.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `list.date`                   | A list of dates in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `list.date_time`              | A list of dates and times in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `list.dimension`              | A list of numeric length values and units.<br />Valid units are:<ul><li><code>mm</code>: Millimeters</li><li><code>cm</code>: Centimeters</li><li><code>m</code>: Meters</li><li><code>in</code>: Inches</li><li><code>ft</code>: Feet</li><li><code>yd</code>: Yards</li></ul>                                                                                                                                                                                                                                                                                                          |
| `list.file_reference`         | A list of file references.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `list.link`                   | A list of text and URL combinations for storing multiple links.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `list.metaobject_reference`   | A list of metaobject entry references.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `list.number_decimal`         | A list of decimal numbers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `list.number_integer`         | A list of integers.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `list.page_reference`         | A list of page references.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `list.article_reference`      | A list of article references.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `list.product_reference`      | A list of product references.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `list.rating`                 | A list of ratings within a specified range.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `list.single_line_text_field` | A list of single-line text fields.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `list.url`                    | A list of URLs that support the `https`, `http`, `mailto`, `sms`, and `tel` protocols.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `list.variant_reference`      | A list of product variant references.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `list.volume`                 | A list of numeric volume values and units.<br />Valid units are:<ul><li><code>ml</code>: Milliliters</li><li><code>cl</code>: Centiliters</li><li><code>l</code>: Liters</li><li><code>m3</code>: Cubic meters</li><li><code>us_fl_oz</code>: US fluid ounces</li><li><code>us_pt</code>: US pints</li><li><code>us_qt</code>: US quarts</li><li><code>us_gal</code>: US gallons</li><li><code>imp_fl_oz</code>: Imperial fluid ounces</li><li><code>imp_pt</code>: Imperial pints</li><li><code>imp_qt</code>: Imperial quarts</li><li><code>imp_gal</code>: Imperial gallons</li></ul> |
| `list.weight`                 | A list of numeric weight values and units.<br />Valid units are:<ul><li><code>kg</code>: Kilograms</li><li><code>g</code>: Grams</li><li><code>lb</code>: Pounds</li><li><code>oz</code>: Ounces</li></ul>                                                                                                                                                                                                                                                                                                                                                                               |

---

## List type code examples

<table>
<thead>
<tr><th>Type</th><th>Example</th></tr>
</thead>
<tbody>
<tr>
<td><code>list.color</code></td>
<td>

```json
["#e84c3d", "#3498db", "#2ecc71"]
```

</td>
</tr>
<tr>
<td><code>list.collection_reference</code></td>
<td>

```json
["gid://shopline/collections/1", "gid://shopline/collections/2"]
```

</td>
</tr>
<tr>
<td><code>list.date</code></td>
<td>

```json
["2026-01-01", "2026-05-01"]
```

</td>
</tr>
<tr>
<td><code>list.date_time</code></td>
<td>

```json
["2026-01-01T12:30:00", "2026-05-01T12:30:00"]
```

</td>
</tr>
<tr>
<td><code>list.dimension</code></td>
<td>

```json
[
  {
    "value": 25.5,
    "unit": "cm"
  },
  {
    "value": 35.5,
    "unit": "cm"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.file_reference</code></td>
<td>

```json
["gid://shopline/MediaImage/123", "gid://shopline/GenericFile/456", "gid://shopline/video/789"]
```

</td>
</tr>
<tr>
<td><code>list.link</code></td>
<td>

```json
[
  {
    "text": "Get started",
    "url": "https://shopline.com"
  },
  {
    "text": "View documentation",
    "url": "https://developer.shopline.com/docs"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.metaobject_reference</code></td>
<td>

```json
["gid://shopline/Metaobject/123", "gid://shopline/Metaobject/456"]
```

</td>
</tr>
<tr>
<td><code>list.number_decimal</code></td>
<td>

```json
["9.99", "19.9", "99.0"]
```

</td>
</tr>
<tr>
<td><code>list.number_integer</code></td>
<td>

```json
["1", "5", "42"]
```

</td>
</tr>
<tr>
<td><code>list.page_reference</code></td>
<td>

```json
["gid://shopline/Page/1", "gid://shopline/Page/2"]
```

</td>
</tr>
<tr>
<td><code>list.article_reference</code></td>
<td>

```json
["gid://shopline/Article/1", "gid://shopline/Article/2"]
```

</td>
</tr>
<tr>
<td><code>list.product_reference</code></td>
<td>

```json
["gid://shopline/Product/1", "gid://shopline/Product/2"]
```

</td>
</tr>
<tr>
<td><code>list.rating</code></td>
<td>

```json
[
  {
    "value": "4.0",
    "scale_min": "1.0",
    "scale_max": "5.0"
  },
  {
    "value": "2.5",
    "scale_min": "1.0",
    "scale_max": "5.0"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.single_line_text_field</code></td>
<td>

```json
["Express shipping", "Standard shipping"]
```

</td>
</tr>
<tr>
<td><code>list.url</code></td>
<td>

```json
["https://www.shopline.com", "https://developer.shopline.com"]
```

</td>
</tr>
<tr>
<td><code>list.variant_reference</code></td>
<td>

```json
["gid://shopline/ProductVariant/1", "gid://shopline/ProductVariant/2"]
```

</td>
</tr>
<tr>
<td><code>list.volume</code></td>
<td>

```json
[
  {
    "value": 20.5,
    "unit": "ml"
  },
  {
    "value": 40.5,
    "unit": "ml"
  }
]
```

</td>
</tr>
<tr>
<td><code>list.weight</code></td>
<td>

```json
[
  {
    "value": 2.5,
    "unit": "kg"
  },
  {
    "value": 4.5,
    "unit": "kg"
  }
]
```

</td>
</tr>
</tbody>
</table>

---

## Rich text format

The `rich_text_field` type accepts JSON objects with the following structure:

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This is regular text.",
          "bold": true,
          "italic": true
        },
        {
          "type": "link",
          "url": "https://example.com",
          "title": "Example link",
          "children": [
            {
              "type": "text",
              "value": "Learn more",
              "bold": true
            }
          ]
        }
      ]
    }
  ]
}
```

### Bold and italic

Text nodes use `bold` and `italic` to set text styles. The fields are described as follows:

| Field    | Required | Description                                               |
| -------- | -------- | --------------------------------------------------------- |
| `type`   | Yes      | Fixed as `text`.                                          |
| `value`  | Yes      | The content of the text node.                             |
| `bold`   | No       | Whether the text is bold. The default value is `false`.   |
| `italic` | No       | Whether the text is italic. The default value is `false`. |

#### Example

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This text is bold and italic.",
          "bold": true,
          "italic": true
        }
      ]
    }
  ]
}
```

### Headings

The fields of a heading node are described as follows:

| Field      | Required | Description                                                |
| ---------- | -------- | ---------------------------------------------------------- |
| `type`     | Yes      | Fixed as `heading`.                                        |
| `level`    | Yes      | The heading level. Supported values range from `1` to `6`. |
| `children` | Yes      | An array of `text` nodes.                                  |

#### Example

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "heading",
      "level": 2,
      "children": [
        {
          "type": "text",
          "value": "This is a level 2 heading"
        }
      ]
    }
  ]
}
```

### Links

The fields of a link node are described as follows:

| Field      | Required | Description                                                                               |
| ---------- | -------- | ----------------------------------------------------------------------------------------- |
| `type`     | Yes      | Fixed as `link`.                                                                          |
| `url`      | Yes      | The destination URL of the link.                                                          |
| `title`    | No       | The link title, which can be used for accessibility and search engine optimization (SEO). |
| `target`   | No       | The target for opening the link. For example, `_blank` opens the link in a new tab.       |
| `children` | Yes      | An array of `text` nodes.                                                                 |

#### Example

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "link",
          "url": "https://example.com",
          "title": "Link to example.com",
          "target": "_blank",
          "children": [
            {
              "type": "text",
              "value": "View details"
            }
          ]
        }
      ]
    }
  ]
}
```

### Lists

The fields of list nodes and list item nodes are described as follows.

List node:

| Field      | Required | Description                                                    |
| ---------- | -------- | -------------------------------------------------------------- |
| `type`     | Yes      | Fixed as `list`.                                               |
| `listType` | Yes      | The list type. Supported values are `ordered` and `unordered`. |
| `children` | Yes      | An array of nodes with `type` set to `list-item`.              |

List item node:

| Field      | Required | Description               |
| ---------- | -------- | ------------------------- |
| `type`     | Yes      | Fixed as `list-item`.     |
| `children` | Yes      | An array of `text` nodes. |

#### Example

```jsonc
{
  "type": "root",
  "children": [
    {
      "type": "list",
      "listType": "unordered",
      "children": [
        {
          "type": "list-item",
          "children": [
            {
              "type": "text",
              "value": "First item"
            }
          ]
        },
        {
          "type": "list-item",
          "children": [
            {
              "type": "text",
              "value": "Second item"
            }
          ]
        }
      ]
    }
  ]
}
```
