Shopify metafields for SEO: structured product details without an app

What is a metafield, and what is a metaobject?

Shopify's custom data overview splits the idea in two and gives a rule for choosing. A metafield is an extra field on an existing Shopify resource. A metaobject is a new record type that you define. Use a metafield when the data describes a product, order or customer. Use a metaobject when it does not belong to any one of them: the overview's examples are a size chart, a store location, an ingredient.

A metafield is a key-value pair with three parts, according to the metafields reference. An identifier made of a namespace and a key (custom.warranty_info is the example it gives), a value, and a type that says how the value is read: text, number, date, a reference to another object. Merchant-owned metafields use a namespace such as custom, and every installed app can read them.

A metaobject carries several fields at once. The metaobjects reference describes it as a standalone entry that can be referenced from many places: an author with a name, a biography and a photo, stored once. One definition describes the shape, and each entry is an instance of it.

Most stores need both, and the overview says so: a metaobject defines the record, and a metafield attaches it to the products it applies to. A size chart is the usual case. The chart is one metaobject, and each product that uses it carries a metafield pointing at it. Edit the chart once and every product page changes.

Why do metafields matter for search?

They matter for one reason: they move product facts out of the description box and into fields. A description is a paragraph that a person reads. A field is a labelled fact that your theme can place, format and repeat consistently on every product, and that a structured data block can quote.

Three things follow from that.

• Consistency. Material, care instructions or origin appear in the same place on every product page, with the same wording pattern, instead of wherever someone remembered to type them.
• Editability. Shopify's overview says a defined field gets a typed editor in the admin, so a merchant fills in a date picker or a number box instead of free text.
• Reuse. The same value can sit in the visible specification table and in the markup, because both read the same field. The two cannot drift apart.

The last point is the one that connects to search. Google's introduction to structured data is plain about it: do not add structured data about information that is not visible to the user, even if the information is accurate. Markup that repeats a field the page already shows meets that rule by construction. Markup typed separately from the page is where the mismatches start.

Why define the field before you fill it?

Because the definition is what makes it a field. Shopify's overview states that both metafields and metaobjects start with a definition (a name, a namespace, a type and validation rules), and that an undefined metafield is stored as a plain string that merchants cannot search or validate.

In the Shopify admin you add a definition for products in the Custom data settings. Choose the type deliberately. A material is single_line_text_field. A care guide longer than a line is multi_line_text_field or rich_text_field. A weight is weight, not text with "g" typed on the end, because the Liquid reference lists weight, volume, dimension and rating as types that return a measurement or rating object rather than a string. A date is a date. A shared size chart is a reference.

Shopify also ships standard definitions for common cases such as ISBN numbers, ingredients and care instructions. The reference says using them helps interoperability across the Shopify ecosystem. Check that list before inventing a namespace, because apps and themes that follow the standard will read your data without any glue.

How do you show a metafield in Liquid?

The Liquid reference gives the access path as resource.metafields.namespace.key, and the field's content is on .value. Its own example reads product.metafields.information.directions.value. For the custom namespace and a material field, a product page snippet is:

{%- assign material = product.metafields.custom.material -%}
{%- if material != blank -%}
  <p class="product-spec">
    <span class="product-spec__label">Material</span>
    {{ material.value }}
  </p>
{%- endif -%}

Four details from the reference save time.

1. You cannot create metafields in Liquid. The reference says they can only be created in the Shopify admin or through an app. Liquid reads them.
2. A key named size, first or last needs square brackets, as in product.metafields.custom["size"]. Those are also built-in Liquid filters, and with dot notation a missing metafield can return the namespace's count instead of an empty value.
3. The type decides what .value returns. A json field returns an object you can walk by property name, a list field returns an array you loop over, and a product_reference returns the product itself.
4. Wrap the output in a blank check. A product without the field should render nothing, not an empty label.

How do metafields feed structured data?

Shopify's structured_data filter produces the standard Product block from the product object. Our product schema guide shows what that default contains and what it leaves out, and why a rating that lives in a metafield never reaches it. The same logic applies to every other field you add: the filter will not read it. A metafield reaches your markup only if a snippet you control reads it.

Material is on Google's recommended list for merchant listings, as that guide sets out. If you replace the default block with a single snippet, as the guide describes, the line to add inside the Product node is:

{%- if product.metafields.custom.material != blank %}
  "material": {{ product.metafields.custom.material.value | json }},
{%- endif %}

The json filter escapes quotes and line breaks, so a stray apostrophe in a material name does not break the whole block. The conditional matters as much: a missing field must produce no property rather than an empty string.

Then apply Google's rule. The same field must be visible on the page, which is why the specification snippet above and this line read the same metafield. If you ever hide the specification table in a tab or remove it from the design, remove the markup line as well.

Do not stretch this beyond what Google documents. Its introduction says an object must include all of its required properties to be eligible for enhanced display, so an extra property on a page that lacks them changes nothing. Treat metafield-driven markup as keeping your data accurate and complete, not as a ranking lever on its own.

Where do metafields stop working?

Shopify publishes limits, and a catalogue that plans to use many fields should read them first.

• Each merchant can create up to 256 metafield definitions per resource type, and each installed app can create the same number.
• A value is capped at 2MB in total. Most types are limited to 64KB, and json to 128KB.
• A list type holds at most 128 items, except metaobject references, which allow 1,024.
• Single line text choices on a definition are capped at 128 values.

None of that is tight for editorial content. It matters for two habits: storing whole articles in a json field, which is what a metaobject or a page is for, and treating metafields as a database for data that varies by variant, where the limits and the editing effort both grow quickly.

There is a second boundary: crawlers read what the page renders. A metafield only helps search if its value ends up in the HTML the server returns. Open the product page, view source, and search for the value. If it is injected later by a script, Google may still see it, but the plain HTML is the safer place for a fact you want indexed.

What should you do first?

1. List the five product facts that customers ask about most and that today live in the description: material, dimensions, care, origin, compatibility. Pick the one you can fill for every product.
2. Create the product definition in the admin's Custom data settings with the right type, and fill it for your top ten products by revenue.
3. Add the Liquid snippet to the product template, check that it renders nothing when the field is empty, and view source on a product to confirm the value is in the HTML.
4. If you control the product markup, add the matching property inside your single Product node and test one product in the Rich Results Test.
5. Roll the field out across the catalogue in bulk, then repeat for the next fact.

One field, one snippet and one markup line is an afternoon. A multi-field section driven by metafields is closer to a day, which is the same estimate we give in the theme customisation versus apps guide, and it replaces an app that would otherwise load its own script on every page.

If you would rather have the whole product page audited for what it states, what it marks up and where the two disagree, that is the Store Teardown, and the services page shows how we build this into a theme.