Home › Blog › Shopify brand entity markup for AI agents

Shopify brand entity markup for AI agents: Organization sameAs, Knowledge Graph disambiguation, and the brand property gap

2026-06-13 — ~16 min read — Brand entitysameAsOrganization schemaKnowledge GraphShopify Liquid

When a ChatGPT Shopping query mentions "Patagonia fleece under $100," the AI agent doesn't just match the string "Patagonia" — it resolves that string to a Knowledge Graph entity, then surfaces products from stores whose structured data links to that entity. Without sameAs on your brand markup, your "Patagonia" is an anonymous string. With sameAs, it's a verified entity reference that places your products inside the brand's recognized catalog. Over 89% of Shopify stores output a bare brand.name string with no entity links whatsoever.

Why AI agents resolve brand entities, not brand strings

Large language model-based shopping agents — ChatGPT Shopping, Perplexity Shopping, Google AI Mode, Shopify Global Catalog — don't work with raw strings the way a keyword search engine does. They operate on entities: nodes in a knowledge graph that represent real-world things with known properties and relationships. A brand is an entity: it has a canonical identity, a legal name, a founding date, social profiles, a headquarters address, and so on.

When a shopper query mentions a brand, the AI agent's first step is entity linking: mapping the surface string (e.g., "Patagonia") to its canonical entity in the knowledge graph (e.g., Wikidata item Q672893, the outdoor apparel company founded in 1973 by Yvon Chouinard). The agent then expands that entity to its known properties — official domains, authorized retailer relationships, product categories — and uses those to rank and filter product results.

A Shopify store whose Product JSON-LD says "brand": {"@type": "Brand", "name": "Patagonia"} is giving the AI agent a string to match. That string is ambiguous: there are dozens of entities named "Patagonia" — travel agencies, restaurants, map regions, regional food brands. An AI agent cannot reliably disambiguate from a bare string alone, especially in a multilingual or multi-market context.

A store whose JSON-LD instead says "brand": {"@type": "Brand", "@id": "https://yourstore.com/#brand-patagonia", "name": "Patagonia", "sameAs": ["https://www.wikidata.org/wiki/Q672893", "https://en.wikipedia.org/wiki/Patagonia_(clothing)", "https://www.linkedin.com/company/patagonia"]} is giving the agent a confirmed entity link. The resolution is immediate and unambiguous: your "Patagonia" is the outdoor apparel brand, and the agent can apply all of Patagonia's known properties when evaluating your listing.

Brand vs. Organization: which type to use and when

Schema.org defines two types commonly used for brand markup:

The recommended architecture for a DTC Shopify store:

1. Declare a site-level Organization entity in theme.liquid with @id: "https://yourdomain.com/#organization" and all applicable sameAs links.
2. On each Product JSON-LD block, set brand to a Brand (or Organization) object that references the site entity via @id and repeats the key sameAs values.

This way, the site-level entity is the authoritative definition, and product-level brand properties are lightweight references that inherit entity confidence from the parent declaration.

The site-level Organization entity: @id, sameAs, and the URL pattern

The site-level Organization block belongs in theme.liquid, not in a product template. It should appear on every page of your store and define your business identity once, authoritatively. Here is the complete structure:

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://yourstore.com/#organization",
  "name": "Your Brand Name",
  "legalName": "Your Brand Name, Inc.",
  "url": "https://yourstore.com/",
  "logo": {
    "@type": "ImageObject",
    "url": "https://yourstore.com/assets/logo.svg",
    "width": 200,
    "height": 60
  },
  "description": "One sentence describing what you sell and who you serve.",
  "foundingDate": "2021",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Commerce St",
    "addressLocality": "Austin",
    "addressRegion": "TX",
    "postalCode": "78701",
    "addressCountry": "US"
  },
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer service",
    "email": "support@yourstore.com"
  },
  "sameAs": [
    "https://www.wikidata.org/wiki/Q...",
    "https://en.wikipedia.org/wiki/Your_Brand",
    "https://www.linkedin.com/company/your-brand",
    "https://www.crunchbase.com/organization/your-brand",
    "https://www.facebook.com/yourbrand",
    "https://www.instagram.com/yourbrand",
    "https://twitter.com/yourbrand",
    "https://www.youtube.com/@yourbrand"
  ]
}

Three rules govern the @id convention:

1. Use the homepage URL + a fragment. The conventional form is https://yourdomain.com/#organization. The fragment #organization is not a real anchor — it's a convention borrowed from how Google's structured data guidelines recommend forming entity identifiers within a domain.
2. The @id must be consistent across all pages. If your product JSON-LD references "brand": {"@id": "https://yourstore.com/#organization"}, that exact string must match what's declared in the site-level block. A mismatch — even a trailing slash difference — breaks the entity link.
3. Never use a product page URL or a collection URL as the @id. Those URLs change. The homepage URL is stable and is the canonical authority for your domain's entity identity.

sameAs links that AI agents prioritize

Not all sameAs links carry equal weight. AI agents use these signals to score entity confidence — the more authoritative and cross-referenced the source, the higher the confidence that your brand entity is genuine and correctly identified.

Product brand property: the @id linking pattern

The product-level brand property is where most Shopify stores fail. Dawn themes output this:

{
  "@type": "Product",
  "name": "Trail Running Jacket",
  "brand": {
    "@type": "Brand",
    "name": "Patagonia"
  }
}

This is a floating entity — a Brand with a name and no identity signals. The AI agent sees "Patagonia" and must guess which Patagonia this is from context alone. The correct pattern links to the site-level entity or declares its own sameAs set:

Pattern A — DTC store (your brand = your store entity):

{
  "@type": "Product",
  "name": "Trail Running Jacket",
  "brand": {
    "@type": "Organization",
    "@id": "https://yourstore.com/#organization",
    "name": "Your Brand Name"
  }
}

Here, the @id ties the product-level brand declaration back to the full Organization entity defined in theme.liquid. The AI agent resolves the @id to the entity with all its sameAs links — you don't need to repeat them on every product.

Pattern B — multi-brand retailer (you carry third-party brands):

{
  "@type": "Product",
  "name": "Trail Running Jacket",
  "brand": {
    "@type": "Brand",
    "@id": "https://yourstore.com/#brand-patagonia",
    "name": "Patagonia",
    "url": "https://www.patagonia.com/",
    "sameAs": [
      "https://www.wikidata.org/wiki/Q672893",
      "https://en.wikipedia.org/wiki/Patagonia_(clothing)",
      "https://www.linkedin.com/company/patagonia",
      "https://www.instagram.com/patagonia"
    ]
  }
}

In Pattern B, the @id is a local identifier — it marks this declaration as your store's definition of the Patagonia entity — while sameAs provides the external references that link it to the actual Patagonia corporate entity in external knowledge bases. The url property pointing to Patagonia's official domain adds another disambiguation signal.

The multi-brand scenario: boutiques and marketplace stores

Shopify stores that carry multiple brands — a boutique selling 30 apparel labels, a sporting goods store carrying a dozen equipment brands — face a different problem than DTC stores. They cannot define a single site-level brand entity and reference it from every product. Each product belongs to a different brand entity with different sameAs links.

The practical solution is a brand metafield that stores a JSON array of sameAs URLs per brand. Here's how to structure the metafield:

• Namespace: brand
• Key: same_as
• Type: json
• Value: JSON array of sameAs URL strings, e.g. ["https://www.wikidata.org/wiki/Q672893", "https://www.linkedin.com/company/patagonia"]

Then in your product Liquid template, you serialize this metafield into the sameAs array on the brand object. The full Liquid snippet in the next section handles both the DTC and multi-brand cases.

For multi-brand stores, also maintain a separate brand reference file (a Shopify page or a JSON file in assets/) that lists every brand you carry with its canonical Wikidata/Wikipedia identity. This serves two purposes: it acts as the data source for your metafield population workflow, and it signals to crawlers that you are an authorized retailer of those brands — a trust signal some AI agents use when ranking search results.

What Dawn outputs vs. what it should output

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Trail Running Jacket",
  "brand": {
    "@type": "Brand",
    "name": "Patagonia"
  },
  "offers": {
    "@type": "Offer",
    "price": "149.00",
    "priceCurrency": "USD"
  }
}

/* No @id on brand */
/* No sameAs links */
/* No site-level Organization entity */
/* "Patagonia" is an unresolved string */

/* In theme.liquid (site-wide): */
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://yourstore.com/#organization",
  "name": "Your Brand",
  "url": "https://yourstore.com/",
  "sameAs": [
    "https://www.wikidata.org/wiki/Q...",
    "https://www.linkedin.com/company/your-brand",
    "https://www.instagram.com/yourbrand"
  ]
}

/* In product template: */
{
  "@type": "Product",
  "name": "Trail Running Jacket",
  "brand": {
    "@type": "Organization",
    "@id": "https://yourstore.com/#organization",
    "name": "Your Brand"
  }
}

The left side is what 89% of Shopify stores ship. The right side is what resolves entity identity for AI agents. The gap is not a complex schema.org feature — it's two additions: a site-level entity block in theme.liquid, and an @id reference on the product-level brand property.

Liquid implementation for Dawn themes

The implementation has two files: theme.liquid for the site-level Organization, and snippets/product-brand-schema.liquid for the product-level brand property. Split into a snippet so you can call it from main-product.liquid and any other templates that output Product JSON-LD.

Step 1 — Site-level Organization entity in theme.liquid

Add this block inside the <head> section of theme.liquid, after your existing JSON-LD blocks. Replace all placeholder values with your real data.

{% comment %} Site-level Organization entity for brand disambiguation {% endcomment %}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": {{ shop.url | append: "/#organization" | json }},
  "name": {{ shop.name | json }},
  "url": {{ shop.url | append: "/" | json }},
  "logo": {
    "@type": "ImageObject",
    "url": {{ shop.url | append: "/assets/logo.svg" | json }}
  },
  "description": {{ shop.description | json }},
  "email": {{ shop.email | json }},
  "sameAs": [
    {% comment %}
      Replace these with your actual sameAs URLs.
      Store them in a global metafield or hardcode them here.
      Minimum viable set: LinkedIn + one social profile.
      Priority set: Wikidata + Wikipedia + LinkedIn + Instagram.
    {% endcomment %}
    "https://www.linkedin.com/company/{{ shop.handle }}",
    "https://www.instagram.com/{{ shop.handle }}",
    "https://www.facebook.com/{{ shop.handle }}"
  ]
}
</script>

Step 2 — Product brand snippet (snippets/product-brand-schema.liquid)

Create a new file at snippets/product-brand-schema.liquid. This snippet outputs the brand property object for use inside Product JSON-LD. It handles both the DTC case (brand = your store) and the multi-brand case (brand = third-party brand with its own sameAs).

{% comment %}
  snippets/product-brand-schema.liquid
  Outputs brand entity JSON for Product JSON-LD.
  Usage: {% render 'product-brand-schema', product: product %}

  Supports two patterns:
  A) DTC — brand is your own Organization: brand.same_as metafield is blank.
     Output: @id reference to site Organization entity.
  B) Multi-brand — brand.same_as metafield is a JSON array of URLs.
     Output: Brand object with its own @id and sameAs links.
{% endcomment %}

{%- liquid
  assign brand_name = product.vendor
  assign brand_same_as = product.metafields.brand.same_as.value
  assign org_id = shop.url | append: "/#organization"
-%}

{%- if brand_same_as != blank -%}
  {%- comment %} Multi-brand pattern: third-party brand with its own sameAs {% endcomment -%}
  {%- assign brand_slug = brand_name | handleize -%}
  {%- assign brand_local_id = shop.url | append: "/#brand-" | append: brand_slug -%}
  "brand": {
    "@type": "Brand",
    "@id": {{ brand_local_id | json }},
    "name": {{ brand_name | json }},
    "sameAs": {{ brand_same_as | json }}
  }
{%- else -%}
  {%- comment %} DTC pattern: brand is the store Organization entity {% endcomment -%}
  "brand": {
    "@type": "Organization",
    "@id": {{ org_id | json }},
    "name": {{ brand_name | json }}
  }
{%- endif -%}

Step 3 — Reference the snippet in main-product.liquid

Inside the Product JSON-LD block in sections/main-product.liquid, replace the existing brand block with a render call to your new snippet:

{% comment %} Find your existing brand output — looks like this: {% endcomment %}
"brand": {
  "@type": "Brand",
  "name": {{ product.vendor | json }}
},

{% comment %} Replace it with: {% endcomment %}
{% render 'product-brand-schema', product: product %},

After adding these two changes, validate with Google's Rich Results Test and Schema.org's validator. The product JSON-LD should show an @id on the brand object and either a sameAs array (multi-brand) or a reference to the site Organization entity (DTC).

Step 4 — Populate the brand.same_as metafield for multi-brand stores

For multi-brand retailers, you need to populate the brand.same_as metafield for each product. Options:

1. Shopify admin bulk editor — navigate to Products → any product → Metafields → add brand.same_as (JSON type) → paste the sameAs array. Repeat per brand. Best for stores with <20 brands.
2. Shopify import CSV — add a metafield column Metafield: brand.same_as [json_string] to your product CSV and bulk import. Best for 20-200 brands with a clean product export.
3. Admin API bulk update — POST /admin/api/2025-01/graphql.json with productUpdate and the metafields input. Best for large catalogs with a developer-managed brand registry.

Five common mistakes that break brand entity markup

FAQ