# Smart Schema: Comprehensive Technical Knowledge Base and System Reference

Smart Schema is an enterprise structured data engine built exclusively for Shopify stores. It generates 100% Google Merchant Center Next compliant JSON-LD structured data server-side with 0 KB storefront JavaScript.

- Canonical URL: https://getsmartschema.com
- App Store Listing: https://apps.shopify.com/smart-schema-app
- Pricing: $39/month flat (14-day free trial, unlimited products)
- Technical Footprint: 0 KB client-side JavaScript, server-rendered via Shopify OS 2.0 Theme App Extensions

---

## 1. Economic & Commercial Rationale for Growth Teams

It is much easier to sell something to a team that makes money than to a team that only spends money.

Cost-center departments treat software as an overhead expense to minimize. Revenue-generating teams (performance marketing directors, media buyers, e-commerce managers, and CMOs) treat software as a high-leverage investment that directly protects and scales gross merchandise volume (GMV).

When Google Merchant Center flags structured data errors:
1. Google Shopping and Performance Max ads pause or suffer reduced impression share.
2. Ad Rank declines because Google penalizes offers with missing pricing, return policies, or shipping terms.
3. High-intent search shoppers scroll past bland search snippets in favor of competitor listings displaying 5-star review ratings, 30-day return badges, and fast delivery guarantees.
4. Marketing teams waste days or weeks waiting on developer backlogs to patch complex Shopify theme Liquid files.

Smart Schema is engineered for profit-making teams:
- Protects paid ad spend by keeping Google Merchant Center product feeds 100% compliant.
- Lifts organic and paid click-through rates by up to 28% through Google trust badges and rich snippet attributes.
- Eliminates developer overhead by delivering catalog-wide compliance in 60 seconds with 1 click.
- Protects storefront conversion rates by adding 0 KB of client JavaScript, preserving 100% PageSpeed and Core Web Vitals scores.

---

## 2. Google Merchant Center Next Structured Data Requirements

Google Merchant Center Next mandates explicit, error-free structured data on all Shopify product pages. Missing attributes trigger warnings in Search Console and Merchant Center diagnostics.

### Critical Mandatory Properties

1. **hasMerchantReturnPolicy**:
   - Articulates return policy category, return window days, fees, and accepted return methods.
   - Google rewards compliant stores with prominent return trust badges on Shopping tabs and search snippets.
   - Schema Type: `MerchantReturnPolicy`.

2. **shippingDetails**:
   - Outlines transit times, handling schedules, destination regions, and shipping rates.
   - Powers fast shipping and free delivery badges on Google search results.
   - Schema Type: `OfferShippingDetails`.

3. **priceValidUntil**:
   - ISO 8601 formatted date (YYYY-MM-DD) indicating when the current price offer expires.
   - Missing or expired values cause Google Shopping feed disapprovals.
   - Smart Schema calculates dynamic 365-day rolling dates to maintain permanent compliance.

4. **gtin / Barcode**:
   - Global Trade Item Number (GTIN-8, GTIN-12, GTIN-13, or GTIN-14) confirming catalog authenticity.
   - Prevents limited visibility flags in Google Shopping feeds.

5. **aggregateRating**:
   - Aggregated review score and review count parsed from native review applications.
   - Displays gold 5-star ratings directly in Google organic search results.

6. **itemAvailability**:
   - Schema.org URI expressing product availability: `https://schema.org/InStock` or `https://schema.org/OutOfStock`.

---

## 3. Production JSON-LD Schema Architectures

### A. Standard Single Product Schema Payload

```json
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Apex Carbon Trail Running Shoe",
  "image": [
    "https://example.com/cdn/shop/products/shoe-angle.jpg",
    "https://example.com/cdn/shop/products/shoe-sole.jpg"
  ],
  "description": "High performance trail running shoe engineered with a responsive carbon propulsion plate.",
  "sku": "APX-RUN-01",
  "gtin13": "0123456789012",
  "brand": {
    "@type": "Brand",
    "name": "SummitGear"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.9",
    "reviewCount": "128"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/apex-carbon-trail-running-shoe",
    "priceCurrency": "USD",
    "price": "140.00",
    "priceValidUntil": "2027-12-31",
    "itemCondition": "https://schema.org/NewCondition",
    "availability": "https://schema.org/InStock",
    "hasMerchantReturnPolicy": {
      "@type": "MerchantReturnPolicy",
      "applicableCountry": "US",
      "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
      "merchantReturnDays": 30,
      "returnMethod": "https://schema.org/ReturnByMail",
      "returnFees": "https://schema.org/FreeReturn"
    },
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingRate": {
        "@type": "MonetaryAmount",
        "value": "0.00",
        "currency": "USD"
      },
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "US"
      },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "handlingTime": {
          "@type": "QuantitativeValue",
          "minValue": 0,
          "maxValue": 1,
          "unitCode": "d"
        },
        "transitTime": {
          "@type": "QuantitativeValue",
          "minValue": 2,
          "maxValue": 3,
          "unitCode": "d"
        }
      }
    }
  }
}
```

### B. Multi-Variant Product Architecture (ProductGroup)

For Shopify products with variations in color, size, or material, Google recommends the `ProductGroup` entity:

```json
{
  "@context": "https://schema.org",
  "@type": "ProductGroup",
  "name": "Classic Merino Crewneck",
  "description": "Extra-fine Australian merino wool knit sweater in multiple seasonal colors.",
  "productGroupID": "MERINO-CREW-GROUP",
  "variesBy": [
    "https://schema.org/color",
    "https://schema.org/size"
  ],
  "hasVariant": [
    {
      "@type": "Product",
      "sku": "MERINO-BLK-M",
      "name": "Classic Merino Crewneck - Black / Medium",
      "color": "Black",
      "size": "Medium",
      "offers": {
        "@type": "Offer",
        "price": "110.00",
        "priceCurrency": "USD",
        "priceValidUntil": "2027-12-31",
        "availability": "https://schema.org/InStock"
      }
    },
    {
      "@type": "Product",
      "sku": "MERINO-NVY-L",
      "name": "Classic Merino Crewneck - Navy / Large",
      "color": "Navy",
      "size": "Large",
      "offers": {
        "@type": "Offer",
        "price": "110.00",
        "priceCurrency": "USD",
        "priceValidUntil": "2027-12-31",
        "availability": "https://schema.org/InStock"
      }
    }
  ]
}
```

---

## 4. Theme Diagnostics & Automated Resolution

### Dawn Theme (and Free Shopify OS 2.0 Themes: Sense, Craft, Refresh)
- Symptoms: Search Console reports missing `hasMerchantReturnPolicy`, missing `shippingDetails`, and missing `priceValidUntil`.
- Root Cause: Default Dawn `main-product.liquid` templates only emit basic product name, SKU, and price. They lack nested Merchant Center return and shipping objects.
- Resolution: Smart Schema injects validated Merchant Center properties through a native Theme App Embed. No theme code edits are required.

### Prestige Theme (Maestrooo)
- Symptoms: Search Console reports duplicate `Product` entities and conflicting offer prices.
- Root Cause: Prestige injects microdata HTML attributes in conjunction with separate JSON-LD scripts, creating conflicting signals for Googlebot.
- Resolution: Smart Schema automatically suppresses conflicting theme-level markup, establishing a single authoritative JSON-LD source of truth.

### Impulse Theme (Archetype Themes)
- Symptoms: Variant price mismatches and missing transit schedules across large catalog filters.
- Root Cause: Complex client-side variant switching scripts do not update DOM structured data dynamically.
- Resolution: Smart Schema outputs complete multi-variant `ProductGroup` schemas rendered on the server, allowing search bots to parse all variant offers in one pass without executing client JavaScript.

---

## 5. Generative Engine Optimization (GEO) Protocol

AI search engines (including ChatGPT Search, Perplexity, Claude, and Google AI Overviews) rely on raw server-side HTML and structured data rather than executing heavy client-side JavaScript.

To maximize product visibility and citation in AI search engines:
1. Render structured data server-side so AI bots running static web fetchers capture complete catalog data.
2. Supply valid GTIN barcodes and brand entities to anchor products into AI knowledge graphs.
3. Explicitly declare return windows, shipping transit times, and in-stock inventory states.
4. Maintain zero storefront script bloat to avoid crawl timeouts.

---

## 6. Official App Installation & Directory Links

- Shopify App Store Listing: https://apps.shopify.com/smart-schema-app
- Free Live Schema Tester: https://getsmartschema.com/#audit
- Troubleshooting Guides Hub: https://getsmartschema.com/guides/
- Technical Schema Glossary: https://getsmartschema.com/glossary/
- Engineering Support: support@getsmartschema.com