Metafields

Metafields extend products with custom structured data. Layers supports the standard Shopify metafield types and provides predictable access patterns for using metafield values as searchable, filterable, and sortable attributes. This page covers the core metafield contract. See these related pages for deeper topics:

Metaobjects and reference metafields — metaobject resolution, nested references, and normalized reference shapes.
Automatic sequences from metafields — turn list.product_reference metafields into product sequences.
Available attributes for API requests — the full list of attributes you can request from the Search, Browse, and Blocks APIs.

Supported metafield types

The product schema supports various Shopify metafield data types, ensuring that your product data is handled correctly for display and filtering purposes. The following metafield types are currently supported:

Type	Description	Example
single_line_text_field	A single line of text used for titles, names, or other short descriptions.	`"Limited Edition"`
multi_line_text_field	Multiple lines of text, typically used for long descriptions or instructions.	`"Care instructions: Machine wash cold, tumble dry low."`
boolean	True or false value indicating binary states such as availability or inclusion.	`true`
number_integer	Whole numbers used for inventory counts, order limits, or other quantities.	`150`
number_decimal	Numbers with decimal places, often used for prices, weights, or measurements.	`29.99`
json	JSON objects used to store structured data such as configurations, specifications, or dynamic content.	`{"alias": "SEALLINE SEE POUCH SMALL", "colorway": "BLACK"}`
date	Date values formatted as YYYY-MM-DD, often used for production dates, release dates, or promotional periods.	`"2023-09-30"`
date_time	DateTime values formatted as ISO 8601, used for time-based events like product launches or sales end times.	`"2024-01-01T00:00:00.000Z"`
color	Color values formatted as hexadecimal strings, used for product colors or UI elements.	`"#FF5733"`
file_reference	Links to file assets, including images, PDFs, or other documents that can be referenced in product displays or additional resources.	`"https://cdn.shopify.com/files/myfile.pdf"`
product_reference	Links to other product IDs, allowing cross-referencing of related items.	`"gid://shopify/Product/123456789"`
variant_reference	References to specific product variants, allowing differentiation between product options like size or color.	`"gid://shopify/ProductVariant/987654321"`
collection_reference	References to collections, used for categorization and dynamic grouping of products.	`"gid://shopify/Collection/456789123"`
page_reference	Links to Shopify pages, typically used for additional information or storytelling about a product.	`"gid://shopify/Page/654321987"`
metaobject_reference	References to custom metaobjects that can extend product data with additional attributes or structured information.	`"gid://shopify/Metaobject/321654987"`
url	URLs pointing to external resources, used for additional product details or external documentation.	`"https://example.com/extended-warranty"`

These metafield types allow for greater flexibility and precision when configuring and displaying product data within your search and browse engine. For a complete list of supported metafield types and their properties, refer to the official Shopify Metafield Data Types documentation.

Metafield structure and examples

Metafields are organized by namespace and key in a nested object structure. The namespace groups related metafields together, and each key within a namespace contains the metafield value.

Metafield structure

{
  "metafields": {
    "{namespace}": {
      "{key}": "{value}"
    }
  }
}

Example: custom product metafields

{
  "metafields": {
    "custom": {
      "material": "100% Organic Cotton",
      "care_instructions": "Machine wash cold, tumble dry low",
      "country_of_origin": "USA",
      "weight_kg": 0.25
    },
    "product": {
      "colorway": "Midnight Blue",
      "style_code": "SS24-TSHIRT-001",
      "release_date": "2024-03-15",
      "is_limited_edition": true
    },
    "seo": {
      "meta_title": "Premium Organic Cotton T-Shirt | Brand Name",
      "meta_description": "Shop our premium organic cotton t-shirt..."
    }
  }
}

Accessing metafields in attributes

To create a catalog attribute from a metafield, use dot notation with the full path:

Metafield Path	Attribute Code
`metafields.custom.material`	`metafields.custom.material`
`metafields.product.colorway`	`metafields.product.colorway`
`metafields.seo.meta_title`	`metafields.seo.meta_title`

Accessing nested metafield object keys

When a metafield value is a JSON object, you can create attributes that access nested object keys using dot notation. The namespace and key portions must follow standard naming conventions (alphanumeric and underscores), but object keys can contain spaces and special characters. Format: metafields.{namespace}.{key}.{object_key} Example metafield value:

{
  "metafields": {
    "custom": {
      "color_family": {
        "dark orange": "orange",
        "light blue": "blue",
        "forest green": "green"
      }
    }
  }
}

Attribute codes for nested object keys:

Object Key	Attribute Code
`dark orange`	`metafields.custom.color_family.dark orange`
`light blue`	`metafields.custom.color_family.light blue`
`forest green`	`metafields.custom.color_family.forest green`

Use cases:

Filtering: Create filterable attributes for nested metafield values to enable faceted navigation (e.g., filter by color family values)
Faceting: Display facet counts for nested object values in browse and search results
Sorting: Sort products by nested metafield object values
Merchandising: Use nested metafield values in collection rules and merchandising logic

This feature supports both metafields and variant_metafields with the same syntax. Variant metafield example: variant_metafields.custom.size_details.extra large

Attribute paths for reference metafields

When a metafield is a reference type (such as metaobject_reference, file_reference, or taxonomy), Layers discovers curated nested attribute paths instead of the base metafield code. This gives you access to the specific values within the normalized reference structure that are useful for filtering, sorting, and display. See Metaobjects and reference metafields for the full normalized shapes and every supported attribute path. Metaobject reference attributes: For metaobject references, the available attribute paths target the display name and individual fields:

Attribute Path	Description
`metafields.{namespace}.{key}.display_name`	The display name of the metaobject
`metafields.{namespace}.{key}.fields.{field_key}`	A specific field value within the metaobject

Example: If you have a custom.specification metaobject reference with fields material and finish, Layers discovers these attribute codes:

metafields.custom.specification.display_name
metafields.custom.specification.fields.material
metafields.custom.specification.fields.finish

Media and file reference attributes: For image and file references, the available paths are:

Attribute Path	Description
`metafields.{namespace}.{key}.url`	The CDN URL of the referenced file
`metafields.{namespace}.{key}.alt`	The alt text of the referenced image

Taxonomy reference attributes: For taxonomy value references, the available path is:

Attribute Path	Description
`metafields.{namespace}.{key}.name`	The display name of the taxonomy value

The base metafield code (e.g., metafields.custom.specification) is not available as an attribute for reference-type metafields. You must use one of the nested paths listed above. Transport-only paths such as __typename, .type, and .handle on nested references are also excluded from attribute creation.

Example: list-type metafields

List metafields (e.g., list.single_line_text_field, list.product_reference) are stored as arrays:

{
  "metafields": {
    "custom": {
      "related_colors": ["Red", "Blue", "Green"],
      "compatible_products": [7003338965178, 7003338965179, 7003338965180],
      "size_chart": [
        {"size": "S", "chest": 36, "length": 27},
        {"size": "M", "chest": 38, "length": 28},
        {"size": "L", "chest": 40, "length": 29}
      ]
    }
  }
}

Overview

Metafields

Supported metafield types

Metafield structure and examples

Metafield structure

Example: custom product metafields

Accessing metafields in attributes

Accessing nested metafield object keys

Attribute paths for reference metafields

Example: list-type metafields

See also

​Supported metafield types

​Metafield structure and examples

​Metafield structure

​Example: custom product metafields

​Accessing metafields in attributes

​Accessing nested metafield object keys

​Attribute paths for reference metafields

​Example: list-type metafields

​See also

Supported metafield types

Metafield structure and examples

Metafield structure

Example: custom product metafields

Accessing metafields in attributes

Accessing nested metafield object keys

Attribute paths for reference metafields

Example: list-type metafields

See also