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:
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" |
{
"metafields": {
"{namespace}": {
"{key}": "{value}"
}
}
}
{
"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..."
}
}
}
| Metafield Path | Attribute Code |
|---|
metafields.custom.material | metafields.custom.material |
metafields.product.colorway | metafields.product.colorway |
metafields.seo.meta_title | metafields.seo.meta_title |
metafields.{namespace}.{key}.{object_key}
Example metafield value:
{
"metafields": {
"custom": {
"color_family": {
"dark orange": "orange",
"light blue": "blue",
"forest green": "green"
}
}
}
}
| 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 |
- 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
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 |
custom.specification metaobject reference with fields material and finish, Layers discovers these attribute codes:
metafields.custom.specification.display_namemetafields.custom.specification.fields.materialmetafields.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 |
| 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.
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}
]
}
}
}
See also
