List of data types

Each metafield has a data type that determines what information it can store. All types have built-in validation and Liquid support. Use this page to explore available types and their expected value formats.

Anchor to How it worksHow 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.

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

{
  "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.

Anchor to Metafield type migrationMetafield 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.

Anchor to Basic typesBasic types

Basic types store values like text, numbers, dates, and measurements paired with a unit. See code samples.

Anchor to Basic type code samplesBasic type code samples

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

Anchor to Reference typesReference types

Reference metafields store references to Shopify resources. See code samples.

Anchor to Reference type code samplesReference type code samples

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

Anchor to List typesList types

List metafields store multiple values in a single metafield as a JSON array. See code samples.

You can implement list metafields on the online store using sections and blocks. 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.

Anchor to List type code samplesList type code samples

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

Anchor to Declarative (TOML) type syntaxDeclarative (TOML) type syntax

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

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

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

Anchor to Metaobject field exampleMetaobject field example

The same syntax applies when defining fields on metaobject definitions:

Anchor to Rich text formatting detailsRich text formatting details

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

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

{
  "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
        }
      ]
    }
  ]
}

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

{
  "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"
          }]
        }
      ]
    }
  ]
}

{
  "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."
          }]
        }
      ]

    }
  ]
}

Anchor to Next stepsNext steps

• Learn how to work with metafield values.
• Learn how to work with metafield definitions.
• Learn about standard definitions.
• Learn about validation options.