Mock R · Metaobjects & metafields — Phase 1 data layer

Ten metaobjects, three intent clusters.

Six previously specified in the original schema docs, four newly identified through working the data-to-design mapping. The newly-identified four (product_video, faq_item, glossary_term, distributor) are specified in full below — same level of detail as the originals.

Phase 1 ceiling is ten metaobject types. Phase 2 brings four more: company_stat, company_milestone, finder_intent_path / finder_step, learn_category. v1 ships those as hardcoded section blocks; promotion to metaobjects is a refactor, not new work.

The metafield bindings, by owner.

Every metaobject reaches the storefront through a metafield attached to a Shopify primitive — product, variant, collection, article, or shop. This is the exhaustive list of metafields the theme needs to read. Each is namespaced under theme so they're scoped to this theme and don't collide with anything else the merchant has installed.

Creating these in Shopify — GraphQL mutations.

Every metaobject and metafield gets defined via a single Admin API mutation, run once per environment. The full create script is a Node script that posts these mutations sequentially with retries. Below is the pattern for one metaobject definition and the corresponding metafield definition; the full script applies the same shape to all ten metaobject types and all twenty-plus metafield definitions.

1. Create the metaobject definition

mutation CreateProductDocumentDefinition {
  metaobjectDefinitionCreate(definition: {
    type: "product_document"
    name: "Product document"
    description: "A PDF or document attached to a product."
    fieldDefinitions: [
      {
        key: "title"
        name: "Title"
        type: "single_line_text_field"
        required: true
      },
      {
        key: "document_type"
        name: "Document type"
        type: "single_line_text_field"
        required: true
        validations: [
          {
            name: "choices"
            value: "[\"manual\",\"datasheet\",\"drawing\",\"install_guide\",\"troubleshooting\",\"warranty\",\"sds\",\"certification\",\"calibration_cert\",\"spec_sheet\",\"case_study\",\"white_paper\",\"catalog\",\"regulatory\"]"
          }
        ]
      }
      /* ... remaining 10 field definitions ... */
    ]
    access: { storefront: PUBLIC_READ }
    displayNameKey: "title"
  }) {
    metaobjectDefinition { id type }
    userErrors { field message }
  }
}

2. Create the metafield definition that binds the metaobject to products:

mutation CreateProductDocumentsMetafield {
  metafieldDefinitionCreate(definition: {
    name: "Documents"
    namespace: "theme"
    key: "documents"
    description: "Manuals, datasheets, drawings attached to this product."
    type: "list.metaobject_reference"
    ownerType: PRODUCT
    validations: [
      {
        name: "metaobject_definition_id"
        value: "gid://shopify/MetaobjectDefinition/123456789"
        // the ID returned by the metaobjectDefinitionCreate mutation above
      }
    ]
    access: { admin: MERCHANT_READ_WRITE, storefront: PUBLIC_READ }
  }) {
    createdDefinition { id key }
    userErrors { field message }
  }
}

3. Wire-up sequence for the full data layer — order matters because some metaobjects reference others:

// Stage 1 — base metaobjects (no inter-references)
1.  product_spec_group       // seeded with 6 entries after creation
2.  product_document
3.  product_video
4.  glossary_term            // self-reference allowed, no other deps
5.  distributor
6.  ai_policy                // single-entry · seed 1 entry after
7.  ai_crawler_policy        // seeded with 12 entries

// Stage 2 — metaobjects with references to Stage 1
8.  product_spec_row         // references product_spec_group
9.  product_relationship     // references product, variant
10. faq_item                 // references glossary_term

// Stage 3 — metafield definitions (after all metaobjects exist)
11. product.theme.{documents, specs, related_products,
                  fits_products, videos, faqs, overview_rich}
12. variant.theme.{documents, specs, videos}
13. collection.theme.{faqs, fyf_banner, featured_filters}
14. article.{editorial.standfirst, editorial.reviewer,
             related.products, related.terms}
15. shop.theme.{ai_policy, ai_crawler_policies, shop_documents,
                faq_items, featured_product, featured_install_videos,
                featured_learn_article, popular_parts_models,
                brand_tagline, hero_*, about_*, warranty_*, contact_*}