Metafields & Metaobjects for Shopify Theme Developers

Theme settings (config/settings_schema.json) are global: one logo, one accent color, one announcement bar message. Product-specific data like fabric composition, care instructions, size-guide URLs, or designer bios does not belong in global settings. Metafields attach typed key-value data to Shopify resources: products, variants, collections, customers, orders, pages, blogs, and the shop itself.

Each metafield has a namespace, key, and type (single_line_text_field, rich_text_field, file_reference, list.product_reference, and dozens more). Merchants edit metafields in the admin product page or through Metaobject-powered entry forms. Theme developers read them in Liquid without redeploying code when content changes. That separation, structure in metafields, presentation in Liquid, is the foundation of maintainable OS 2.0 themes.

On a product template, metafields live on product.metafields and variant.metafields. Access a known definition with the bracket syntax: {{ product.metafields.custom.care_instructions }}. For file references, chain .value and image filters: {{ product.metafields.custom.size_chart.value | image_url: width: 800 | image_tag }}.

When the namespace or key is dynamic, use the metafield_tag filter or loop metafields: {% for metafield in product.metafields.custom %} ... {% endfor %}. Always guard with {% if product.metafields.custom.care_instructions != blank %} so empty definitions do not render broken layout shells.

Variant metafields override or supplement product-level data. A common pattern: product.metafields.custom.material for shared copy, variant.metafields.custom.swatch_hex for color-specific UI. In JSON templates, expose metafields to sections via the product object passed automatically on product templates, or through {% render %} with explicit arguments.

Metaobjects are merchant-defined content types: Author, Store Location, Ingredient, FAQ Item, or Lookbook Slide. You create a definition in Settings > Custom data > Metaobjects with fields (name, types, validations). Each entry is a standalone record merchants manage like lightweight CMS documents.

Definitions receive a type string such as author. In Liquid, fetch entries via shop.metaobjects.author.values or a single handle: shop.metaobjects.author['jane-doe']. Fields on the entry mirror metafield types: entry.name, entry.bio, entry.photo.value.

Connect metaobjects to products with metafields of type metaobject_reference or list.metaobject_reference. A product can point at one Size Guide metaobject; your section reads product.metafields.custom.size_guide.value and renders tabs from the metaobject fields. This pattern scales better than duplicating rich text across hundreds of SKUs.

Online Store 2.0 sections declare settings in {% schema %} with types like text, image_picker, and product. Dynamic sources let merchants bind a setting to a metafield: a 'Subtitle' text setting can connect to product.metafields.descriptors.subtitle so the section auto-populates on every product page without per-product JSON template edits.

Enable dynamic sources by using compatible setting types and adding compatible metafield definitions (via Shopify admin or shopify.app.toml in apps). In the theme editor, merchants click the 'Connect dynamic source' icon next to a setting and pick from available metafields on the current resource.

Theme developers should design sections with sensible defaults in settings while allowing dynamic overrides. Document which metafield keys your theme expects in README or the section preset label. ADSPOC themes ship metafield definition JSON so merchants get one-click setup instead of guessing namespace.key conventions.

Metafield and metaobject definitions can be created manually in admin or declared in TOML for version control. Theme app extensions and standalone apps use shopify.app.toml [[product.metafields]] blocks so definitions deploy with the app. Pure theme projects often bundle a metafields JSON import or setup guide because themes alone cannot create definitions programmatically without an app.

Use GraphQL Admin API (metafieldDefinitionCreate, metaobjectDefinitionCreate) in migration scripts when onboarding enterprise catalogs. Store handles, not numeric IDs, in your Liquid lookups where possible; handles survive exports better than GIDs in hardcoded theme code.

Performance note: deep loops over shop.metaobjects.*.values on every page load are expensive. Prefer referencing only the entries needed via product metafields, or paginate metaobject lists in dedicated templates. Cache-heavy pages (collection grids) should not call unrestricted metaobject iteration inside hot loops.