Metaobjects & Reference Metafields

Layers fully supports Shopify metaobjects, allowing you to leverage custom data structures defined in your Shopify admin. When a product metafield references a metaobject, Layers automatically resolves the complete metaobject data from a local cache. This gives you access to all fields defined on the metaobject, including nested metaobject references up to 5 levels deep. All reference-type metafields are normalized into a consistent, predictable structure. This means you always receive the same shape of data regardless of how Shopify returns the raw reference, making it easier to build reliable storefront experiences.

Supported reference types

The schema supports the following reference types with full data normalization:

Reference Type	Description
`metaobject_reference`	Single reference to a custom metaobject
`list.metaobject_reference`	List of references to custom metaobjects
`file_reference`	Reference to a file asset (image, video, or document)
`product_reference`	Single reference to another product
`list.product_reference`	List of references to other products
`variant_reference`	Single reference to a product variant
`collection_reference`	Single reference to a collection
`page_reference`	Single reference to a Shopify page

Normalized reference shapes

Each reference type is normalized into a small, consistent object. Transport-only fields like __typename are always removed. The shape you receive depends on the type of referenced resource. Metaobject references are resolved into a structure with the metaobject’s core identifiers and a key-value map of its fields:

Field	Type	Description
`id`	String	The Shopify GID of the metaobject
`type`	String	The metaobject definition type
`handle`	String	The metaobject handle
`display_name`	String or null	The display name of the metaobject
`fields`	Object	Key-value map of resolved field data

Media image references (including file_reference metafields that point to images) are normalized to:

Field	Type	Description
`id`	String	The Shopify GID of the media image
`url`	String	The CDN URL of the image
`alt`	String or null	The alt text for the image

Taxonomy value references are normalized to:

Field	Type	Description
`id`	String	The Shopify GID of the taxonomy value
`name`	String	The display name of the taxonomy value

Video references are normalized to:

Field	Type	Description
`id`	String	The Shopify GID of the video
`url`	String	The URL of the first video source

Structured metaobject field leaves

When a metaobject field uses one of Shopify’s structured types (money, weight, volume, dimension, or rating), Layers exposes the field’s scalar leaves as attribute paths instead of the raw object. Numeric leaves are indexed with numeric semantics, so filters and sort orders on them compare values as numbers. The same leaves are available whether the metaobject field is a single value (money, weight, volume, dimension, rating) or a list (list.money, list.weight, list.volume, list.dimension, list.rating). The leaf path is identical in both cases.

Field type	Leaf path suffix	Value type
`money`, `list.money`	`.fields.{field_key}.amount`	number
`weight`, `volume`, `dimension` (and their `list.*` variants)	`.fields.{field_key}.value`	number
`rating`, `list.rating`	`.fields.{field_key}.value`	number

Example: a custom.badge metaobject reference with a price money field on the metaobject exposes:

metafields.custom.badge.fields.price.amount: filterable and sortable as a number.

Filter products whose badge price is at least 20:

{
  "property": "metafields.custom.badge.fields.price.amount",
  "operator": "gte",
  "values": [20]
}

List-valued leaves

For list.* structured fields, a single metaobject holds an array of values on that field. Filters match when any value in the list satisfies the condition. Facet counts include every value across the list. Sort orders collapse a product’s list to its minimum value in both asc and desc directions; use single-valued structured fields when you need a strict descending order.

Nested metaobject resolution

When a metaobject field references another metaobject (via metaobject_reference or list.metaobject_reference), Layers automatically resolves the nested reference from its local cache. This happens recursively up to 5 levels deep, with circular reference protection to prevent infinite loops. This is useful for data models where metaobjects reference other metaobjects. For example, a “Product Spec” metaobject that references a “Material” metaobject, which in turn references a “Certification” metaobject. Non-reference fields are returned as their plain values (strings, numbers, etc.). If a referenced metaobject is not found in the cache, the reference data from Shopify is still normalized into the standard shape.

Example: metaobject reference response

{
  "metafields": {
    "custom": {
      "color_swatch": {
        "id": "gid://shopify/Metaobject/123456",
        "type": "color_swatch",
        "handle": "midnight-blue",
        "display_name": "Midnight Blue",
        "fields": {
          "color": "#191970",
          "name": "Midnight Blue",
          "hex_code": "#191970"
        }
      }
    }
  }
}

Example: list metaobject reference response

{
  "metafields": {
    "custom": {
      "available_colors": [
        {
          "id": "gid://shopify/Metaobject/111",
          "type": "color_swatch",
          "handle": "red-swatch",
          "display_name": "Red",
          "fields": {
            "color": "#FF0000",
            "name": "Red"
          }
        },
        {
          "id": "gid://shopify/Metaobject/222",
          "type": "color_swatch",
          "handle": "blue-swatch",
          "display_name": "Blue",
          "fields": {
            "color": "#0000FF",
            "name": "Blue"
          }
        }
      ]
    }
  }
}

Example: media image reference response

{
  "metafields": {
    "custom": {
      "hero_image": {
        "id": "gid://shopify/MediaImage/123456",
        "url": "https://cdn.shopify.com/s/files/hero-image.jpg",
        "alt": "Product hero image"
      }
    }
  }
}

Example: nested metaobject reference response

In this example, a product has a “material” metafield that references a Material metaobject, which itself has a “certification” field referencing a Certification metaobject:

{
  "metafields": {
    "custom": {
      "material": {
        "id": "gid://shopify/Metaobject/500",
        "type": "material",
        "handle": "organic-cotton",
        "display_name": "Organic Cotton",
        "fields": {
          "name": "Organic Cotton",
          "weight": "150gsm",
          "certification": {
            "id": "gid://shopify/Metaobject/600",
            "type": "certification",
            "handle": "gots-certified",
            "display_name": "GOTS Certified",
            "fields": {
              "name": "Global Organic Textile Standard",
              "level": "Grade A",
              "url": "https://example.com/gots"
            }
          }
        }
      }
    }
  }
}

Metaobject data is resolved from a local cache that is kept in sync with Shopify via webhooks. If a referenced metaobject is not found in the cache, Layers normalizes the original reference data from Shopify’s GraphQL response into the standard shape, or falls back to the numeric ID if no reference data is available.

Overview

Metafields

Metaobjects & Reference Metafields

Supported reference types

Normalized reference shapes

Structured metaobject field leaves

List-valued leaves

Nested metaobject resolution

Example: metaobject reference response

Example: list metaobject reference response

Example: media image reference response

Example: nested metaobject reference response

See also

​Supported reference types

​Normalized reference shapes

​Structured metaobject field leaves

​List-valued leaves

​Nested metaobject resolution

​Example: metaobject reference response

​Example: list metaobject reference response

​Example: media image reference response

​Example: nested metaobject reference response

​See also

Supported reference types

Normalized reference shapes

Structured metaobject field leaves

List-valued leaves

Nested metaobject resolution

Example: metaobject reference response

Example: list metaobject reference response

Example: media image reference response

Example: nested metaobject reference response

See also