> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselayers.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metafields

> Supported Shopify metafield types in Layers, their structure, namespace conventions, and how to access metafield values as searchable product attributes.

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](/developers/product-schema/metafields/metaobjects-and-references) — metaobject resolution, nested references, and normalized reference shapes.
* [Automatic sequences from metafields](/developers/product-schema/metafields/automatic-sequences) — turn `list.product_reference` metafields into product sequences.
* [Available attributes for API requests](/developers/product-schema/api-attributes) — 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](https://shopify.dev/docs/apps/build/custom-data/metafields/list-of-data-types).

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

```json theme={null}
{
  "metafields": {
    "{namespace}": {
      "{key}": "{value}"
    }
  }
}
```

### Example: custom product metafields

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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

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

### 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](/developers/product-schema/metafields/metaobjects-and-references) 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 |

<Note>
  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.
</Note>

### Example: list-type metafields

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

```json theme={null}
{
  "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

* [Metaobjects and reference metafields](/developers/product-schema/metafields/metaobjects-and-references)
* [Automatic sequences from metafields](/developers/product-schema/metafields/automatic-sequences)
* [Available attributes for API requests](/developers/product-schema/api-attributes)
* [Product Schema](/developers/product-schema)
* [Variant & Option Data](/developers/product-schema/variant-data)
* [Catalog Sync](/shopify-integration/catalog-sync)