---
title: List of data types
description: This page lists all the types supported by metafields.
source_url:
  html: 'https://shopify.dev/docs/apps/build/metafields/list-of-data-types'
  md: 'https://shopify.dev/docs/apps/build/metafields/list-of-data-types.md'
---

# List of data types

Each [metafield](https://shopify.dev/docs/apps/build/metafields) has a data type that determines what information it can store. All types have built-in validation and [Liquid](https://shopify.dev/docs/api/liquid/objects/metafield) support. Use this page to explore available types and their expected value formats.

**Note:**

[Metaobjects](https://shopify.dev/docs/apps/build/metaobjects) use the same data types.

***

## How it works

When you create a metafield definition, the type applies to every instance of that resource. For example, if you create a definition called "Ingredients" with type `multi_line_text_field` for products, then every product enforces that type for its "Ingredients" metafield.

## shopify.app.toml

##### TOML

```toml
[product.metafields.app.ingredients]
name = "Ingredients"
type = "multi_line_text_field"
```

##### GraphQL Admin API response

```json
{
  "data": {
    "product": {
      "metafield": {
        "namespace": "$app",
        "key": "ingredients",
        "value": "oat milk,\nsugar,\nchia seeds",
        "type": "multi_line_text_field",
        "definition": {
          "name": "Ingredients",
          "ownerType": "PRODUCT"
        }
      }
    }
  }
}
```

When using the GraphQL Admin API to read and write metafields, the value is always entered and stored as a string, regardless of type.

For information about limits for each metafield type, refer to [metafield limits](https://shopify.dev/docs/apps/build/metafields/metafield-limits).

***

## Metafield type migration

You can change the type of a metafield, with some important considerations:

* Metafields cannot be migrated to type `id`.
* When migrating a metafield between incompatible types (for example, from `date_time` to `money`), the existing values become invalid. To fix this, use the Shopify admin to clear the invalid value, or use the API to clear the value or change the invalid definition to a compatible one.

***

## Basic types

Basic types store values like text, numbers, dates, and measurements paired with a unit. See [code samples](#basic-type-code-samples).

| Type | Description | Value type | [Translatable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
| - | - | - | - | - |
| `antenna_gain` | A value and a unit of antenna gain. Valid unit values: `decibels_isotropic`, `decibels_dipole` | JSON object | no | no |
| `area` | A value and a unit of area. Valid unit values: `square_centimeters`, `square_feet`, `square_inches`, `square_meters`, `square_yards` | JSON object | no | no |
| `battery_charge_capacity` | A value and a unit of battery charge capacity. Valid unit values: `milliamp_hours` | JSON object | no | no |
| `battery_energy_capacity` | A value and a unit of battery energy capacity. Valid unit values: `watt_hours` | JSON object | no | no |
| `boolean` | A true or false value. | boolean | no | no |
| `capacitance` | A value and a unit of capacitance. Valid unit values: `picofarads`, `nanofarads`, `microfarads`, `farads` | JSON object | no | no |
| `color` | The hexadecimal code for a color. | string | no | no |
| `concentration` | A value and a unit of concentration. Valid unit values: `milligrams_per_gram`, `milligrams_per_milliliter` | JSON object | no | no |
| `data_storage_capacity` | A value and a unit of data storage capacity. Valid unit values: `bytes`, `kilobytes`, `megabytes`, `gigabytes`, `terabytes` | JSON object | no | no |
| `data_transfer_rate` | A value and a unit of data transfer rate. Valid unit values: `bits_per_second`, `kilobits_per_second`, `megabits_per_second`, `gigabits_per_second` | JSON object | no | no |
| `date` | A date in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without a presumed timezone. | string | no | no |
| `date_time` | A date and time in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without a presumed timezone. Defaults to Greenwich Mean Time (GMT). | string | no | no |
| `dimension` | A value and a unit of length. Valid unit values: `inches`, `feet`, `yards`, `millimeters`, `centimeters`, `meters` | JSON object | no | no |
| `display_density` | A value and a unit of display density. Valid unit values: `pixels_per_inch`, `dots_per_inch` | JSON object | no | no |
| `distance` | A value and a unit of distance. Valid unit values: `kilometers`, `miles` | JSON object | no | no |
| `duration` | A value and a unit of time duration. Valid unit values: `nanoseconds`, `microseconds`, `milliseconds`, `seconds`, `minutes`, `hours`, `days`, `months`, `years` | JSON object | no | no |
| `electric_current` | A value and a unit of electric current. Valid unit values: `milliamperes`, `amperes`, `kiloamperes` | JSON object | no | no |
| `electrical_resistance` | A value and a unit of electrical resistance. Valid unit values: `ohms`, `kiloohms` | JSON object | no | no |
| `energy` | A value and a unit of energy. Valid unit values: `joules`, `calories`, `kilojoules`, `kilocalories` | JSON object | no | no |
| `frequency` | A value and a unit of frequency. Valid unit values: `hertz`, `kilohertz`, `megahertz`, `gigahertz` | JSON object | no | no |
| `id` | A unique single-line text field. You can add [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) for `min`, `max`, and `regex`. | string | no | no |
| `illuminance` | A value and a unit of illuminance. Valid unit values: `lux`, `foot_candles` | JSON object | no | no |
| `inductance` | A value and a unit of inductance. Valid unit values: `microhenries`, `millihenries`, `henries` | JSON object | no | no |
| `json` | A JSON-serializable value. This can be an object, an array, a string, a number, a boolean, or a null value. | JSON data | yes | no |
| `link` | A text and URL pairing that can be used to store link content. | JSON data | yes | no |
| `luminous_flux` | A value and a unit of luminous flux. Valid unit values: `lumens` | JSON object | no | no |
| `mass_flow_rate` | A value and a unit of mass flow rate. Valid unit values: `grams_per_day`, `grams_per_hour`, `grams_per_minute`, `grams_per_second`, `ounces_per_day`, `ounces_per_hour`, `ounces_per_minute`, `ounces_per_second`, `pounds_per_day`, `pounds_per_hour`, `pounds_per_minute`, `pounds_per_second`, `kilograms_per_day`, `kilograms_per_hour`, `kilograms_per_minute`, `kilograms_per_second`, `tons_per_day`, `tons_per_hour`, `tons_per_minute`, `tons_per_second`, `tonnes_per_day`, `tonnes_per_hour`, `tonnes_per_minute`, `tonnes_per_second` | JSON object | no | no |
| `money` | A numeric amount, with a currency code that matches the store's currency. You can [localize money metafields to a market](https://help.shopify.com/manual/markets/languages/translate-adapt-app#create-custom-content-for-a-market), but you can't translate them to a different language or locale. | JSON object | no | yes |
| `multi_line_text_field` | A multi-line text field. | string | yes | no |
| `number_decimal` | A number with decimal places in the range of +/-9999999999999.999999999. | string | no | no |
| `number_integer` | A whole number in the range of +/-9,007,199,254,740,991. | integer | no | no |
| `power` | A value and a unit of power. Valid unit values: `milliwatts`, `watts`, `horsepower`, `kilowatts` | JSON object | no | no |
| `pressure` | A value and a unit of pressure. Valid unit values: `pounds_per_square_inch`, `bars` | JSON object | no | no |
| `rating` | A rating measured on a specified scale. [Validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) are required for ratings and support `min` and `max`. | JSON object | no | no |
| `resolution` | A value and a unit of resolution. Valid unit values: `pixels`, `megapixels` | JSON object | no | no |
| `rich_text_field` | A rich text field supporting headings, lists, links, bold, and italics. Learn more about [rich text formatting](#rich-text-formatting-details). | JSON object | yes | no |
| `rotational_speed` | A value and a unit of rotational speed. Valid unit values: `revolutions_per_minute` | JSON object | no | no |
| `single_line_text_field` | A single-line text field. | string | yes | no |
| `sound_level` | A value and a unit of sound level. Valid unit values: `decibels` | JSON object | no | no |
| `speed` | A value and a unit of speed. Valid unit values: `kilometers_per_hour`, `feet_per_second`, `miles_per_hour`, `meters_per_second` | JSON object | no | no |
| `temperature` | A value and a unit of temperature. Valid unit values: `celsius`, `fahrenheit`, `kelvin` | JSON object | no | no |
| `thermal_power` | A value and a unit of thermal power. Valid unit values: `british_thermal_units_per_hour`, `kilowatts`, `tons_of_refrigeration` | JSON object | no | no |
| `url` | A URL with one of the allowed schemes: `https`, `http`, `mailto`, `sms`, `tel`. | string | yes | no |
| `voltage` | A value and a unit of voltage. Valid unit values: `volts` | JSON object | no | no |
| `volume` | A value and a unit of volume. Valid unit values: `milliliters`, `centiliters`, `liters`, `cubic_meters`, `us_fluid_ounces`, `us_pints`, `us_quarts`, `us_gallons`, `imperial_fluid_ounces`, `imperial_pints`, `imperial_quarts`, `imperial_gallons`. | JSON object | no | no |
| `volumetric_flow_rate` | A value and a unit of volumetric flow rate. Valid unit values: `liters_per_hour`, `liters_per_minute`, `liters_per_second`, `gallons_per_hour`, `gallons_per_minute`, `gallons_per_second`, `cubic_feet_per_hour`, `cubic_feet_per_minute`, `cubic_feet_per_second`, `cubic_meters_per_hour`, `cubic_meters_per_minute`, `cubic_meters_per_second` | JSON object | no | no |
| `weight` | A value and a unit of weight. Valid unit values: `ounces`, `pounds`, `grams`, `kilograms` | JSON object | no | no |

***

## Basic type code samples

The following examples demonstrate the expected value format for each basic type:

| Type | Sample |
| - | - |
| `antenna_gain` | ```json
{
  "value": 5.0,
  "unit": "decibels_isotropic"
}
``` |
| `area` | ```json
{
  "value": 100.0,
  "unit": "square_meters"
}
``` |
| `battery_charge_capacity` | ```json
{
  "value": 3000.0,
  "unit": "milliamp_hours"
}
``` |
| `battery_energy_capacity` | ```json
{
  "value": 50.0,
  "unit": "watt_hours"
}
``` |
| `boolean` | ```text
true
``` |
| `capacitance` | ```json
{
  "value": 100.0,
  "unit": "microfarads"
}
``` |
| `color` | ```text
#fff123
``` |
| `concentration` | ```json
{
  "value": 5.0,
  "unit": "milligrams_per_milliliter"
}
``` |
| `data_storage_capacity` | ```json
{
  "value": 256.0,
  "unit": "gigabytes"
}
``` |
| `data_transfer_rate` | ```json
{
  "value": 100.0,
  "unit": "megabits_per_second"
}
``` |
| `date` | ```text
2022-02-02
``` |
| `date_time` | ```text
2024-01-01T12:30:00
``` |
| `dimension` | ```json
{
  "value": 25.0,
  "unit": "centimeters"
}
``` |
| `display_density` | ```json
{
  "value": 326.0,
  "unit": "pixels_per_inch"
}
``` |
| `distance` | ```json
{
  "value": 42.0,
  "unit": "kilometers"
}
``` |
| `duration` | ```json
{
  "value": 30.0,
  "unit": "seconds"
}
``` |
| `electric_current` | ```json
{
  "value": 2.5,
  "unit": "amperes"
}
``` |
| `electrical_resistance` | ```json
{
  "value": 100.0,
  "unit": "ohms"
}
``` |
| `energy` | ```json
{
  "value": 250.0,
  "unit": "kilocalories"
}
``` |
| `frequency` | ```json
{
  "value": 2.4,
  "unit": "gigahertz"
}
``` |
| `id` | ```text
1234
``` |
| `illuminance` | ```json
{
  "value": 500.0,
  "unit": "lux"
}
``` |
| `inductance` | ```json
{
  "value": 10.0,
  "unit": "millihenries"
}
``` |
| `json` | ```json
{
  "ingredient": "flour",
  "amount": 0.3
}
``` |
| `link` | ```json
{
  "text": "Learn more",
  "url": "https://shopify.com"
}
``` |
| `luminous_flux` | ```json
{
  "value": 800.0,
  "unit": "lumens"
}
``` |
| `mass_flow_rate` | ```json
{
  "value": 5.0,
  "unit": "kilograms_per_hour"
}
``` |
| `money` | ```json
{
  "amount": "5.99",
  "currency_code": "CAD"
}
``` |
| `multi_line_text_field` | IngredientsFlourWaterMilkEggs |
| `number_decimal` | ```text
10.4
``` |
| `number_integer` | ```text
10
``` |
| `power` | ```json
{
  "value": 100.0,
  "unit": "watts"
}
``` |
| `pressure` | ```json
{
  "value": 14.7,
  "unit": "pounds_per_square_inch"
}
``` |
| `rating` | ```json
{
  "value": "3.5",
  "scale_min": "1.0",
  "scale_max": "5.0"
}
``` |
| `resolution` | ```json
{
  "value": 12.0,
  "unit": "megapixels"
}
``` |
| `rich_text_field` | ```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "Bold text.",
          "bold": true
        }
      ]
    }
  ]
}
``` |
| `rotational_speed` | ```json
{
  "value": 3000.0,
  "unit": "revolutions_per_minute"
}
``` |
| `single_line_text_field` | ```text
VIP shipping method
``` |
| `sound_level` | ```json
{
  "value": 85.0,
  "unit": "decibels"
}
``` |
| `speed` | ```json
{
  "value": 60.0,
  "unit": "kilometers_per_hour"
}
``` |
| `temperature` | ```json
{
  "value": 22.5,
  "unit": "celsius"
}
``` |
| `thermal_power` | ```json
{
  "value": 12000.0,
  "unit": "british_thermal_units_per_hour"
}
``` |
| `url` | ```text
https://www.shopify.com
``` |
| `voltage` | ```json
{
  "value": 120.0,
  "unit": "volts"
}
``` |
| `volume` | ```json
{
  "value": 20.0,
  "unit": "milliliters"
}
``` |
| `volumetric_flow_rate` | ```json
{
  "value": 5.0,
  "unit": "liters_per_minute"
}
``` |
| `weight` | ```json
{
  "value": 2.5,
  "unit": "kilograms"
}
``` |

***

## Reference types

Reference metafields store references to Shopify resources. See [code samples](#reference-type-code-samples).

| Type | Description | Value type | [Translatable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
| - | - | - | - | - |
| `article_reference` | A reference to a [blog post](https://help.shopify.com/en/manual/online-store/blogs). | string | no | yes |
| `collection_reference` | A reference to a collection. | string | no | yes |
| `company_reference` | A reference to a company. | string | no | no |
| `customer_reference` | A reference to a customer. | string | no | no |
| `file_reference` | A reference to a file. The default value is `GenericFile`. You can use [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to add other file types (for example, `Image`). | string | yes | no |
| `metaobject_reference` | A reference to a metaobject entry. You can use [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to set which metaobject definition the metaobject must be. In TOML, use the [type shorthand](#declarative-toml-type-syntax): `type = "metaobject_reference<$app:author>"`. | string | no | yes |
| `mixed_reference` | A reference that can point to metaobjects from different definitions, unlike `metaobject_reference` which only allows metaobjects from one definition. In TOML, use the [type shorthand](#declarative-toml-type-syntax): `type = "mixed_reference<$app:author, $app:publisher>"`. | string | no | no |
| `page_reference` | A reference to a page. | string | no | yes |
| `product_reference` | A reference to a product. | string | no | yes |
| `product_taxonomy_value_reference` | A reference to a product taxonomy value. You can add [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to limit which taxonomy values can be selected. Refer to [Shopify Standard Product Taxonomy](https://shopify.github.io/product-taxonomy) for available values. | string | no | no |
| `variant_reference` | A reference to a product variant. | string | no | yes |

***

## Reference type code samples

The following examples demonstrate the expected value format for each reference type:

| Type | Sample |
| - | - |
| `article_reference` | ```text
gid://shopify/Article/1
``` |
| `collection_reference` | ```text
gid://shopify/Collection/1
``` |
| `company_reference` | ```text
gid://shopify/Company/1
``` |
| `customer_reference` | ```text
gid://shopify/Customer/1
``` |
| `file_reference` | ```text
gid://shopify/MediaImage/123
``` |
| `metaobject_reference` | ```text
gid://shopify/Metaobject/123
``` |
| `mixed_reference` | ```text
gid://shopify/Metaobject/123
``` |
| `page_reference` | ```text
gid://shopify/Page/1
``` |
| `product_reference` | ```text
gid://shopify/Product/1
``` |
| `product_taxonomy_value_reference` | ```text
gid://shopify/TaxonomyValue/1
``` |
| `variant_reference` | ```text
gid://shopify/ProductVariant/1
``` |

***

## List types

List metafields store multiple values in a single metafield as a JSON array. See [code samples](#list-type-code-samples).

You can implement list metafields on the online store [using sections and blocks](https://shopify.dev/docs/storefronts/themes/best-practices/templates-sections-blocks#metafields). The type of list determines the implementation. For example, you could add a list of product references as a dynamic source to a custom block, or you could add a list of single line text fields to a text or rich text section.

**Info:**

If you delete a product or variant from a store, then the product or variant is automatically removed from all list metafields that reference it.

| Type | Description | [Translatable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/translationsRegister) | [Market localizable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/marketLocalizationsRegister) |
| - | - | - | - |
| `list.antenna_gain` | A list of values and a unit of antenna gain. Valid unit values: `decibels_isotropic`, `decibels_dipole` | no | no |
| `list.area` | A list of values and a unit of area. Valid unit values: `square_centimeters`, `square_feet`, `square_inches`, `square_meters`, `square_yards` | no | no |
| `list.article_reference` | A list of references to [blog posts](https://help.shopify.com/en/manual/online-store/blogs). | no | no |
| `list.battery_charge_capacity` | A list of values and a unit of battery charge capacity. Valid unit values: `milliamp_hours` | no | no |
| `list.battery_energy_capacity` | A list of values and a unit of battery energy capacity. Valid unit values: `watt_hours` | no | no |
| `list.capacitance` | A list of values and a unit of capacitance. Valid unit values: `picofarads`, `nanofarads`, `microfarads`, `farads` | no | no |
| `list.collection_reference` | A list of collection references. | no | no |
| `list.color` | A list of hexadecimal color codes. | no | no |
| `list.concentration` | A list of values and a unit of concentration. Valid unit values: `milligrams_per_gram`, `milligrams_per_milliliter` | no | no |
| `list.customer_reference` | A list of references to customers. | no | no |
| `list.data_storage_capacity` | A list of values and a unit of data storage capacity. Valid unit values: `bytes`, `kilobytes`, `megabytes`, `gigabytes`, `terabytes` | no | no |
| `list.data_transfer_rate` | A list of values and a unit of data transfer rate. Valid unit values: `bits_per_second`, `kilobits_per_second`, `megabits_per_second`, `gigabits_per_second` | no | no |
| `list.date` | A list of dates in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without presumed timezones. | no | no |
| `list.date_time` | A list of dates and times in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) format without presumed timezones. Defaults to Greenwich Mean Time (GMT). | no | no |
| `list.dimension` | A list of values and a unit of length. Valid unit values: `inches`, `feet`, `yards`, `millimeters`, `centimeters`, `meters`. | no | no |
| `list.display_density` | A list of values and a unit of display density. Valid unit values: `pixels_per_inch`, `dots_per_inch` | no | no |
| `list.distance` | A list of values and a unit of distance. Valid unit values: `kilometers`, `miles` | no | no |
| `list.duration` | A list of values and a unit of time duration. Valid unit values: `nanoseconds`, `microseconds`, `milliseconds`, `seconds`, `minutes`, `hours`, `days`, `months`, `years` | no | no |
| `list.electric_current` | A list of values and a unit of electric current. Valid unit values: `milliamperes`, `amperes`, `kiloamperes` | no | no |
| `list.electrical_resistance` | A list of values and a unit of electrical resistance. Valid unit values: `ohms`, `kiloohms` | no | no |
| `list.energy` | A list of values and a unit of energy. Valid unit values: `joules`, `calories`, `kilojoules`, `kilocalories` | no | no |
| `list.file_reference` | A list of references to files. The default value is `GenericFile`. You can use [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to add other file types (for example, `Image`). | yes | no |
| `list.frequency` | A list of values and a unit of frequency. Valid unit values: `hertz`, `kilohertz`, `megahertz`, `gigahertz` | no | no |
| `list.id` | A list of unique single-line text fields. You can add [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) for `min`, `max`, and `regex`. | no | no |
| `list.illuminance` | A list of values and a unit of illuminance. Valid unit values: `lux`, `foot_candles` | no | no |
| `list.inductance` | A list of values and a unit of inductance. Valid unit values: `microhenries`, `millihenries`, `henries` | no | no |
| `list.link` | A list of text and URL pairings that can be used to store a collection of links. | yes | no |
| `list.luminous_flux` | A list of values and a unit of luminous flux. Valid unit values: `lumens` | no | no |
| `list.mass_flow_rate` | A list of values and a unit of mass flow rate. Valid unit values: `grams_per_day`, `grams_per_hour`, `grams_per_minute`, `grams_per_second`, `ounces_per_day`, `ounces_per_hour`, `ounces_per_minute`, `ounces_per_second`, `pounds_per_day`, `pounds_per_hour`, `pounds_per_minute`, `pounds_per_second`, `kilograms_per_day`, `kilograms_per_hour`, `kilograms_per_minute`, `kilograms_per_second`, `tons_per_day`, `tons_per_hour`, `tons_per_minute`, `tons_per_second`, `tonnes_per_day`, `tonnes_per_hour`, `tonnes_per_minute`, `tonnes_per_second` | no | no |
| `list.metaobject_reference` | A list reference to one or more metaobject entries that belong to a single metaobject definition. Unlike `list.mixed_reference`, all metaobject entries referenced must be of the same definition. In TOML, use the [type shorthand](#declarative-toml-type-syntax): `type = "list.metaobject_reference<$app:author>"`. | no | no |
| `list.mixed_reference` | A list reference to one or more metaobject entries that may belong to different metaobject definitions. In TOML, use the [type shorthand](#declarative-toml-type-syntax): `type = "list.mixed_reference<$app:author, $app:publisher>"`. | no | no |
| `list.number_decimal` | A list of numbers with decimal places in the range of +/-9999999999999.999999999. | no | no |
| `list.number_integer` | A list of whole numbers in the range of +/-9,007,199,254,740,991. | no | no |
| `list.page_reference` | A list of references to pages. | no | no |
| `list.power` | A list of values and a unit of power. Valid unit values: `milliwatts`, `watts`, `horsepower`, `kilowatts` | no | no |
| `list.pressure` | A list of values and a unit of pressure. Valid unit values: `pounds_per_square_inch`, `bars` | no | no |
| `list.product_reference` | A list of product references. | no | no |
| `list.product_taxonomy_value_reference` | A list of references to product taxonomy values. You can add [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) to limit which taxonomy values can be selected. Refer to [Shopify Standard Product Taxonomy](https://shopify.github.io/product-taxonomy) for available values. | no | no |
| `list.rating` | A list of ratings measured on a specified scale. [Validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) are required for ratings and support `min` and `max`. | no | no |
| `list.resolution` | A list of values and a unit of resolution. Valid unit values: `pixels`, `megapixels` | no | no |
| `list.rotational_speed` | A list of values and a unit of rotational speed. Valid unit values: `revolutions_per_minute` | no | no |
| `list.single_line_text_field` | A list of single-line text fields. | yes | no |
| `list.sound_level` | A list of values and a unit of sound level. Valid unit values: `decibels` | no | no |
| `list.speed` | A list of values and a unit of speed. Valid unit values: `kilometers_per_hour`, `feet_per_second`, `miles_per_hour`, `meters_per_second` | no | no |
| `list.temperature` | A list of values and a unit of temperature. Valid unit values: `celsius`, `fahrenheit`, `kelvin` | no | no |
| `list.thermal_power` | A list of values and a unit of thermal power. Valid unit values: `british_thermal_units_per_hour`, `kilowatts`, `tons_of_refrigeration` | no | no |
| `list.url` | A list of URLs with one of the allowed schemes: `https`, `http`, `mailto`, `sms`, `tel`. | yes | no |
| `list.variant_reference` | A list of references to product variants. | no | no |
| `list.voltage` | A list of values and a unit of voltage. Valid unit values: `volts` | no | no |
| `list.volume` | A list of values and a unit of volume. Valid unit values: `milliliters`, `centiliters`, `liters`, `cubic_meters`, `us_fluid_ounces`, `us_pints`, `us_quarts`, `us_gallons`, `imperial_fluid_ounces`, `imperial_pints`, `imperial_quarts`, `imperial_gallons`. | no | no |
| `list.volumetric_flow_rate` | A list of values and a unit of volumetric flow rate. Valid unit values: `liters_per_hour`, `liters_per_minute`, `liters_per_second`, `gallons_per_hour`, `gallons_per_minute`, `gallons_per_second`, `cubic_feet_per_hour`, `cubic_feet_per_minute`, `cubic_feet_per_second`, `cubic_meters_per_hour`, `cubic_meters_per_minute`, `cubic_meters_per_second` | no | no |
| `list.weight` | A list of values and a unit of weight. Valid unit values: `ounces`, `pounds`, `grams`, `kilograms` | no | no |

***

## List type code samples

The following examples demonstrate the expected value format for each list type:

| Type | Sample |
| - | - |
| `list.antenna_gain` | ```json
[
  {"value": 5.0, "unit": "decibels_isotropic"},
  {"value": 3.0, "unit": "decibels_isotropic"}
]
``` |
| `list.area` | ```json
[
  {"value": 100.0, "unit": "square_meters"},
  {"value": 200.0, "unit": "square_meters"}
]
``` |
| `list.article_reference` | ```json
[
  "gid://shopify/Article/1",
  "gid://shopify/Article/2"
]
``` |
| `list.battery_charge_capacity` | ```json
[
  {"value": 3000.0, "unit": "milliamp_hours"},
  {"value": 5000.0, "unit": "milliamp_hours"}
]
``` |
| `list.battery_energy_capacity` | ```json
[
  {"value": 50.0, "unit": "watt_hours"},
  {"value": 100.0, "unit": "watt_hours"}
]
``` |
| `list.capacitance` | ```json
[
  {"value": 100.0, "unit": "microfarads"},
  {"value": 220.0, "unit": "microfarads"}
]
``` |
| `list.collection_reference` | ```json
[
  "gid://shopify/Collection/1",
  "gid://shopify/Collection/2"
]
``` |
| `list.color` | ```json
[
  "#FFF123",
  "#E6E6FA",
  "#00FF00"
]
``` |
| `list.concentration` | ```json
[
  {"value": 5.0, "unit": "milligrams_per_milliliter"},
  {"value": 10.0, "unit": "milligrams_per_milliliter"}
]
``` |
| `list.customer_reference` | ```json
[
  "gid://shopify/Customer/1",
  "gid://shopify/Customer/2"
]
``` |
| `list.data_storage_capacity` | ```json
[
  {"value": 256.0, "unit": "gigabytes"},
  {"value": 512.0, "unit": "gigabytes"}
]
``` |
| `list.data_transfer_rate` | ```json
[
  {"value": 100.0, "unit": "megabits_per_second"},
  {"value": 1000.0, "unit": "megabits_per_second"}
]
``` |
| `list.date` | ```json
[
  "2022-01-01",
  "2022-05-05"
]
``` |
| `list.date_time` | ```json
[
  "2024-01-01T12:30:00",
  "2024-05-01T12:30:00"
]
``` |
| `list.dimension` | ```json
[
  {"value": 25.0, "unit": "centimeters"},
  {"value": 35.0, "unit": "centimeters"}
]
``` |
| `list.display_density` | ```json
[
  {"value": 326.0, "unit": "pixels_per_inch"},
  {"value": 458.0, "unit": "pixels_per_inch"}
]
``` |
| `list.distance` | ```json
[
  {"value": 42.0, "unit": "kilometers"},
  {"value": 100.0, "unit": "kilometers"}
]
``` |
| `list.duration` | ```json
[
  {"value": 30.0, "unit": "seconds"},
  {"value": 60.0, "unit": "seconds"}
]
``` |
| `list.electric_current` | ```json
[
  {"value": 2.5, "unit": "amperes"},
  {"value": 5.0, "unit": "amperes"}
]
``` |
| `list.electrical_resistance` | ```json
[
  {"value": 100.0, "unit": "ohms"},
  {"value": 470.0, "unit": "ohms"}
]
``` |
| `list.energy` | ```json
[
  {"value": 250.0, "unit": "kilocalories"},
  {"value": 500.0, "unit": "kilocalories"}
]
``` |
| `list.file_reference` | ```json
[
  "gid://shopify/MediaImage/123",
  "gid://shopify/MediaImage/456"
]
``` |
| `list.frequency` | ```json
[
  {"value": 2.4, "unit": "gigahertz"},
  {"value": 5.0, "unit": "gigahertz"}
]
``` |
| `list.id` | ```json
[
  "1234",
  "5678"
]
``` |
| `list.illuminance` | ```json
[
  {"value": 500.0, "unit": "lux"},
  {"value": 1000.0, "unit": "lux"}
]
``` |
| `list.inductance` | ```json
[
  {"value": 10.0, "unit": "millihenries"},
  {"value": 47.0, "unit": "millihenries"}
]
``` |
| `list.link` | ```json
[
  {"text": "Start a business", "url": "https://shopify.com"},
  {"text": "Read the docs", "url": "https://shopify.dev/docs"}
]
``` |
| `list.luminous_flux` | ```json
[
  {"value": 800.0, "unit": "lumens"},
  {"value": 1600.0, "unit": "lumens"}
]
``` |
| `list.mass_flow_rate` | ```json
[
  {"value": 5.0, "unit": "kilograms_per_hour"},
  {"value": 10.0, "unit": "kilograms_per_hour"}
]
``` |
| `list.metaobject_reference` | ```json
[
  "gid://shopify/Metaobject/123",
  "gid://shopify/Metaobject/456"
]
``` |
| `list.mixed_reference` | ```json
[
  "gid://shopify/Metaobject/123",
  "gid://shopify/Metaobject/456"
]
``` |
| `list.number_decimal` | ```json
[
  "10.4",
  "20.5",
  "30.6"
]
``` |
| `list.number_integer` | ```json
[
  "10",
  "20",
  "30"
]
``` |
| `list.page_reference` | ```json
[
  "gid://shopify/Page/1",
  "gid://shopify/Page/2"
]
``` |
| `list.power` | ```json
[
  {"value": 100.0, "unit": "watts"},
  {"value": 200.0, "unit": "watts"}
]
``` |
| `list.pressure` | ```json
[
  {"value": 14.7, "unit": "pounds_per_square_inch"},
  {"value": 30.0, "unit": "pounds_per_square_inch"}
]
``` |
| `list.product_reference` | ```json
[
  "gid://shopify/Product/1",
  "gid://shopify/Product/2"
]
``` |
| `list.product_taxonomy_value_reference` | ```json
[
  "gid://shopify/TaxonomyValue/1",
  "gid://shopify/TaxonomyValue/2"
]
``` |
| `list.rating` | ```json
[
  {"value": "3.5", "scale_min": "1.0", "scale_max": "5.0"},
  {"value": "4.5", "scale_min": "1.0", "scale_max": "5.0"}
]
``` |
| `list.resolution` | ```json
[
  {"value": 12.0, "unit": "megapixels"},
  {"value": 48.0, "unit": "megapixels"}
]
``` |
| `list.rotational_speed` | ```json
[
  {"value": 3000.0, "unit": "revolutions_per_minute"},
  {"value": 6000.0, "unit": "revolutions_per_minute"}
]
``` |
| `list.single_line_text_field` | ```json
[
  "VIP shipping method",
  "Standard shipping method"
]
``` |
| `list.sound_level` | ```json
[
  {"value": 85.0, "unit": "decibels"},
  {"value": 100.0, "unit": "decibels"}
]
``` |
| `list.speed` | ```json
[
  {"value": 60.0, "unit": "kilometers_per_hour"},
  {"value": 120.0, "unit": "kilometers_per_hour"}
]
``` |
| `list.temperature` | ```json
[
  {"value": 22.5, "unit": "celsius"},
  {"value": 37.0, "unit": "celsius"}
]
``` |
| `list.thermal_power` | ```json
[
  {"value": 12000.0, "unit": "british_thermal_units_per_hour"},
  {"value": 24000.0, "unit": "british_thermal_units_per_hour"}
]
``` |
| `list.url` | ```json
[
  "https://www.shopify.com",
  "https://www.shopify.dev"
]
``` |
| `list.variant_reference` | ```json
[
  "gid://shopify/ProductVariant/1",
  "gid://shopify/ProductVariant/2"
]
``` |
| `list.voltage` | ```json
[
  {"value": 120.0, "unit": "volts"},
  {"value": 240.0, "unit": "volts"}
]
``` |
| `list.volume` | ```json
[
  {"value": 20.0, "unit": "milliliters"},
  {"value": 40.0, "unit": "milliliters"}
]
``` |
| `list.volumetric_flow_rate` | ```json
[
  {"value": 5.0, "unit": "liters_per_minute"},
  {"value": 10.0, "unit": "liters_per_minute"}
]
``` |
| `list.weight` | ```json
[
  {"value": 2.5, "unit": "kilograms"},
  {"value": 4.5, "unit": "kilograms"}
]
``` |

***

## Declarative (TOML) type syntax

When defining metafields or metaobject fields in `shopify.app.toml`, most types use the type name directly:

```toml
[product.metafields.app.ingredients]
type = "multi_line_text_field"
```

However, reference types that point to metaobjects require a special shorthand syntax that embeds the target definition in the type. This replaces the `metaobject_definition_id` and `metaobject_definition_ids` [validations](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options) used in the GraphQL Admin API.

* **`metaobject_reference` and `list.metaobject_reference`**: Use angle brackets to specify which metaobject definition the reference must point to:

Use angle brackets to specify which metaobject definition the reference must point to:

```toml
[product.metafields.app.author]
type = "metaobject_reference<$app:author>"


[product.metafields.app.related_authors]
type = "list.metaobject_reference<$app:author>"
```

* **`mixed_reference` and `list.mixed_reference`**: Use a comma-separated list inside the angle brackets to specify which metaobject definitions are allowed:

Use a comma-separated list inside the angle brackets to specify which metaobject definitions are allowed:

```toml
[product.metafields.app.content_block]
type = "mixed_reference<$app:author, $app:publisher>"


[product.metafields.app.content_blocks]
type = "list.mixed_reference<$app:author, $app:publisher>"
```

### Metaobject field example

The same syntax applies when defining fields on metaobject definitions:

```toml
[metaobjects.app.book.fields.author]
type = "metaobject_reference<$app:author>"


[metaobjects.app.book.fields.related_content]
type = "list.mixed_reference<$app:author, $app:publisher>"
```

**Info:**

You don't need to add `metaobject_definition_id` or `metaobject_definition_ids` validations in TOML. The type shorthand syntax above handles this automatically.

***

## Rich text formatting details

The `rich_text_field` metafield type accepts a JSON object that uses the following general structure:

```json
{
  "type": "root",
  // The root holds an array of paragraphs and lists. Each paragraph represents a section of text that's separated by a line break.
  "children": [
    {
      "type": "paragraph",
      // A paragraph holds an array of formatted text objects and URL objects, where the objects are concatenated to form the text within the paragraph.
      "children": [
        // Formatted text object
        {
          "type": "text",
          "value": "This is italicized text and ",
          "italic": true
        },
        // URL object
        {
          "url": "https://example.com",
          "title": "Link to example.com",
          "type": "link",
          "children": [
            // Formatted text object that's embedded in the URL object.
            {
              "type": "text",
              "value": "a bolded hyperlink",
              "bold": true
            }
          ]
        }
      ]
    }
  ]
}
```

![The rich text editor, showing the words](https://shopify.dev/assets/assets/images/apps/custom-data/example-rich-text-formatting-CV5Rivu5.png)

Refer to the following code samples for examples of the objects that can be used to represent fragments of rich text:

##### Bold and italics

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "text",
          "value": "This text is bolded and italicized.",
          // To bold or italicize the text, set the "bold" or "italic" values to true. The default value is false.
          "bold": true,
          "italic": true
        }
      ]
    }
  ]
}
```

##### Heading

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "type": "heading",
          "children": [{
            "type": "text",
            "value": "This is an H1 heading"
          }],
          // The heading level
          "level": 1
        }
      ]
    }
  ]
}
```

##### Hyperlink

```json
{
  "type": "root",
  "children": [
    {
      "type": "paragraph",
      "children": [
        {
          "url": "https://example.com",
          // The URL title is used for accessibility and SEO purposes.
          "title": "Link to example.com",
          "type": "link",
          // The following array of formatted text represents the text that's visible to the user.
          "children": [{
            "type": "text",
            "value": "This is a hyperlink"
          }]
        }
      ]
    }
  ]
}
```

##### Lists

```json
{
  "type": "root",
  "children": [
    {
      // The listType accepts "ordered" or "unordered".
      "listType": "ordered",
      "type": "list",
      "children": [
        {
          "type": "list-item",
          // Each list item holds an array of formatted text.
          "children": [{
            "type": "text",
            "value": "This is the first list item."
          }]
        },
        {
          "type": "list-item",
          "children": [{
            "type": "text",
            "value": "This is the second list item."
          }]
        }
      ]

    }
  ]
}
```

***

## Next steps

* Learn how to [work with metafield values](https://shopify.dev/docs/apps/build/metafields/manage-metafields).
* Learn how to [work with metafield definitions](https://shopify.dev/docs/apps/build/metafields/definitions).
* Learn about [standard definitions](https://shopify.dev/docs/apps/build/metafields/list-of-standard-definitions).
* Learn about [validation options](https://shopify.dev/docs/apps/build/metafields/list-of-validation-options).

***