Site Name Schema Framework

Site name markup tells Google what to call your site in search results. This framework builds it from the page's own data, and 7 checks can each stop it before anything is printed.

  • Google last changed this documentation .
  • This framework was last updated .
MCP connectorBuild it in a chat

What It Earns

The search result this markup makes a page eligible for, drawn from the framework's own output. Each outlined part is there because of the property listed beside it. Point at a part, or tap it, to see which. Google decides whether to show it.

Search result

Trailhead Outfitters

https://www.example.com

  • The site namename

When To Use It

Add WebSite markup to the home page of the domain or subdomain only; it isn't needed on other pages. Google uses it, together with other home page signals, to choose the site name shown in Search results. Site names are available in all languages where Google Search is available, on mobile and desktop.

Not for: A home page that sits in a subdirectory. Google supports site names for a domain or a subdomain only.

Key Implementation Documentation Highlights

Google's rules for this feature that are not about one property alone, in plain words. Which properties Google requires and recommends, and what it expects of each, is in the Property Reference.

  • Consistency: use the same name in WebSite markup, og:site_name, the <title>, headings and other home page text. Organization markup should use the same name and alternateName; the registered company name belongs in Organization legalName.
  • One WebSite node: avoid duplicate WebSite blocks. If the home page already has WebSite markup, add name and alternateName to it instead of adding a second block.
  • Crawlability: the home page and its duplicates (HTTP and HTTPS, www and non-www) must be accessible to Googlebot, not blocked by robots.txt and not noindex.

Template Approach

The usual starting point: a static template that prints every property, whether or not the page has the data for it. Under the code is what goes wrong with it.

const siteData = {
  siteName: "Trailhead Outfitters",
  shortName: "Trailhead",
  homeUrl: "https://www.example.com/"
};

const staticTemplate = {
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": siteData.siteName,
  "alternateName": siteData.shortName,
  "url": siteData.homeUrl
};

Where It Breaks

What this template printed when it was run with one field of its page data taken away, and what it never asks.

  • With no siteName in the page data, it prints the block without name, which Google requires.
  • With no shortName, it prints the block without alternateName.
  • With no homeUrl, it prints the block without url, which Google requires.
  • It asks nothing before it prints. The framework below asks 7 questions first, such as "Matches the og:site_name and the organization name?" and "Appears in the page title?", and prints nothing when an answer is no.

Conditional-logic Framework

The same markup, built by code. It checks the page and the data first, adds a property only when the data for it exists, and outputs nothing when a check fails. The tabs hold the JavaScript builder, the Python version and the output.

const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2})(?::(\d{2}))?(Z|[+-]\d{2}:\d{2})?)?$/;

function isAbsoluteUrl(value) {
  return typeof value === "string" && /^https?:\/\/[^\s/?#]+\.[^\s/?#]+(?:[/?#]\S*)?$/i.test(value);
}

// Returns the ISO 8601 string unchanged (timezone offset kept), or null if unparseable.
function toIsoDateTime(value) {
  if (typeof value !== "string") return null;
  const text = value.trim();
  const m = text.match(ISO_DATE_TIME);
  if (!m) return null;
  const [, y, mo, d, h = "00", mi = "00", s = "00"] = m;
  const date = new Date(Date.UTC(+y, +mo - 1, +d));
  if (date.getUTCMonth() !== +mo - 1 || date.getUTCDate() !== +d) return null;
  if (+h > 23 || +mi > 59 || +s > 59) return null;
  return text;
}

function toIsoDate(value) {
  const iso = toIsoDateTime(value);
  return iso ? iso.slice(0, 10) : null;
}

// Drops null, undefined, "", [] and {} recursively.
function compact(value) {
  if (Array.isArray(value)) {
    const items = value.map(compact).filter((v) => v !== undefined);
    return items.length ? items : undefined;
  }
  if (value && typeof value === "object") {
    const out = {};
    for (const [key, v] of Object.entries(value)) {
      const c = compact(v);
      if (c !== undefined) out[key] = c;
    }
    return Object.keys(out).length ? out : undefined;
  }
  return value === null || value === undefined || value === "" ? undefined : value;
}

function passesPageGates(source) {
  if (source.indexable === false) return false;
  if (source.canonicalUrl && source.url && source.canonicalUrl !== source.url) return false;
  return source.contentVisible !== false;
}


// Legal suffixes belong in Organization legalName, not in the site name ("Google", not "Google, Inc").
const LEGAL_SUFFIX = /(?:,\s*|\s+)(?:inc|llc|ltd|limited|corp|corporation|gmbh|plc)\.?$/i;

function cleanName(value) {
  const text = typeof value === "string" ? value.trim().replace(/\s+/g, " ") : "";
  return text && !LEGAL_SUFFIX.test(text) ? text : null;
}

// The canonical home page of a domain or subdomain: root path, no query or fragment.
function toHomeUrl(value) {
  if (!isAbsoluteUrl(value)) return null;
  const url = new URL(value);
  return url.pathname === "/" && !url.search && !url.hash ? `${url.origin}/` : null;
}

function buildWebSiteSchema(source) {
  // (a) Page gates: indexable, self-canonical, and the home page at the domain or subdomain root.
  //     Subdirectory home pages such as https://example.com/news are not supported.
  if (!passesPageGates(source)) return null;
  const homeUrl = toHomeUrl(source.url);
  if (!homeUrl) return null;

  // (b) Required: name and url. The name must be concise and match og:site_name,
  //     the title and the Organization name; a mismatch is fixed in the source, not shipped.
  const name = cleanName(source.siteName);
  if (!name) return null;
  const otherNames = [source.ogSiteName, source.organizationName].filter(Boolean);
  if (otherNames.some((other) => other.trim() !== name)) return null;
  if (source.title && !source.title.includes(name)) return null;

  // alternateName: in order of preference, deduplicated, never the name itself.
  const alternateName = [...new Set((source.alternateNames || []).map(cleanName))]
    .filter((alt) => alt && alt.toLowerCase() !== name.toLowerCase());

  // (c) Required plus recommended properties; (d) one WebSite node per site: if the page already
  //     has WebSite markup, merge into it. No SearchAction: the sitelinks search box was retired in Nov 2024.
  const schema = {
    "@context": "https://schema.org",
    "@type": "WebSite",
    "@id": `${homeUrl}#website`,
    name,
    alternateName,
    url: homeUrl,
    publisher: isAbsoluteUrl(source.organizationId) ? { "@id": source.organizationId } : null
  };

  // (e) Strip empty values.
  return compact(schema);
}

// Usage:
// const source = {
//   "url": "https://www.example.com/",
//   "canonicalUrl": "https://www.example.com/",
//   "indexable": true,
//   "contentVisible": true,
//   "siteName": "Trailhead Outfitters",
//   "alternateNames": [
//     "Trailhead",
//     "THO"
//   ],
//   "ogSiteName": "Trailhead Outfitters",
//   "organizationName": "Trailhead Outfitters",
//   "title": "Trailhead Outfitters: Hiking Packs, Tents and Trail Apparel"
// };
// const schema = buildWebSiteSchema(source); // null when a gate or required property fails

What It Does Instead

What this framework does that the template cannot.

  • Emits WebSite markup only on the root home page, where a sitewide static template would repeat it on every page and on unsupported subdirectory sites.
  • Refuses to ship a name that disagrees with og:site_name, the title or the Organization name, so the signals Google compares stay aligned.
  • Strips legal suffixes and duplicate alternate names while keeping the order of preference.
  • Keeps the retired SearchAction out of new builds and links the WebSite node to the Organization by @id when one exists.

The Logic As A Flowchart

The same logic as the builder, drawn for readers who do not write code. Every Yes moves down. A No that runs out to the line on the right stops everything, and no schema is output. Each step was run against the builder itself before this page was published: 21 test cases, all passing.

  1. The home page of a site
  2. 1Page indexable?not marked as non-indexableNo: no schema
    Yes
  3. 2Canonical is itself?or no canonical is setNo: no schema
    Yes
  4. 3Content visible?not marked as hiddenNo: no schema
    Yes
  5. 4The home page at the root of the domain?a full URL with no path, query or fragment. A home page in a subdirectory does not countNo: no schema
    Yes
  6. 5Has a clean site name?filled in, with no legal ending such as Inc or LLCNo: no schema
    Yes
  7. 6Matches the og:site_name and the organization name?whichever of the two is given must be the same nameNo: no schema
    Yes
  8. 7Appears in the page title?a title, when given, must contain the site nameNo: no schema
    Yes
  9. Build the restanything optional that is missing or invalid is left out
  10. Output WebSite
    No schema

Put It To Work

What the builder needs, where it runs and how to tell it is working.

What To Feed It

The builder reads one object. The example at the end of the JavaScript tab fills in every field of it. Each row says whether the builder needs that field and what the output loses without it, found by taking the field out of the example and running the builder again.

Whether the builder needs each field of its input, and what it outputs without it
InputNeededWhat happens
urlRequiredWithout it, nothing is output.
siteNameRequiredWithout it, nothing is output.
canonicalUrl, indexable, contentVisible, ogSiteName, organizationNameOptionalWithout them, nothing changes. They are checks: nothing is output when canonicalUrl differs from url, when ogSiteName or organizationName differs from siteName, or when indexable or contentVisible is set to false.
alternateNamesOptionalWithout it, alternateName is left out.
titleOptionalWithout it, nothing changes.

Where To Run It

Run it where the page is built, on the server or in the build step, with that page's own data. Print what it returns as JSON in a <script type="application/ld+json"> tag. When it returns nothing, print no tag.

Build It In A Chat

Add the Schema Frameworks connector to Claude or another assistant that supports MCP and ask it to build this markup. It runs the builder on this page, and when nothing is output it names the check that stopped it.

  • Claude
  • ChatGPT
  • Gemini
  • Grok
  • Perplexity
  • Le Chat
  • Meta Muse
  • Manus
  • Copilot
# Connector address
https://mcp.jakelabate.com/schema-frameworks
# Then ask
Use the Schema Frameworks MCP server and its Site Name framework to build markup for my page. Ask me for the page URL first.

How To Check It

  • After deployment, use URL Inspection to request a recrawl of the home page so Google picks up the new name.
  • Test the page as it is served, not the template. A build step or client-side rendering can change what is printed.
  • Log every page where the builder returns nothing. Each one was stopped by one of the 7 checks in the flowchart, which is not the same as a builder that failed.

The Output As An Entity Graph

The conditional-logic output, parsed in your browser and drawn as the graph a crawler builds from it. Every nested object is a node and the property that holds it is the edge. Tap a node to inspect its properties, or drag to rearrange.

Property Reference

What Google's Site name documentation requires and recommends, property by property. These are the same rules the SchemaCDN validator checks. Each name links to its schema.org definition. The rules that are not about one property are in Key Implementation Documentation Highlights.

Site name properties in Google's documentation
PropertyGoogleExpectsNotes
nameRequiredTextThe name of the website. Choose a unique, accurate, concise and commonly recognized name: "Google", not "Google, Inc". Avoid generic names unless they are a well-known brand.
urlRequiredURLThe URL of the home page of the site.
alternateNameRecommendedText, can repeatAn alternate name of the website, for example a recognized acronym or shorter name. List them in order of preference, most important first. Alternate names follow the same guidelines as name.

Explore Other Schema Framework Pages

Retired Sitelinks Search Box Use on sites with a functioning internal search endpoint that can accept URL query parameters. WebSite Open Software App (Beta) Use for software product pages that describe platform support and application category clearly. SoftwareApplication Open Limited Speakable Use for news-style pages where specific text segments are appropriate for text-to-speech playback. SpeakableSpecification Open Subscription and Paywalled Content Use for pages with restricted sections so Google can distinguish free previews from protected content. CreativeWork Open Limited Vacation Rental Use for rental property detail pages where booking-relevant amenities and location signals are explicit. VacationRental Open Retired Vehicle Listing Use for inventory pages selling vehicles with standardized listing fields and offer information. Car Open Video Use for pages where a primary video is embedded and key media metadata is visible on-page. VideoObject Open Article Use for editorial pages where the visible content is a complete article with a clear byline and publication timestamps. Article Open Limited Book Actions Use when your page helps users read, preview, or purchase books through clearly described actions. Book Open Breadcrumb Use on pages that belong to a clear hierarchy and display navigational trail links users can follow. BreadcrumbList Open Carousel Use when a page lists multiple related entities in a scannable sequence that can be surfaced as cards. ItemList Open Course Use for educational offerings where curriculum details, provider identity, and delivery context are explicit. Course Open Dataset Use for dataset landing pages so datasets are discoverable in Google Dataset Search with license, creator and download details. Dataset Open Discussion Forum Use for forum and community threads where a primary post and subsequent replies are publicly visible. DiscussionForumPosting Open Limited Education Q&A Use for educational question-answer pages where a single canonical answer and supporting context are visible. Quiz Open Employer Aggregate Rating Use on pages that publish employer rating aggregates from a clear and policy-compliant review source. EmployerAggregateRating Open Retired Estimated Salary Use for compensation insight pages that present transparent salary ranges for specific occupations and locations. Occupation Open Event Use for upcoming events with a real-world or virtual occurrence, schedule, and location context. Event Open Retired Fact Check Use for fact-checking pages that evaluate a specific claim with a transparent rating methodology. ClaimReview Open Retired Home Activities Use for virtual classes and activities where participation details and timing are clearly listed. Event Open Retired How-To Use for instructional content that teaches a process through ordered steps and actionable detail. HowTo Open Image Metadata Use on image pages and image hosts that expose ownership and licensing information to search engines. ImageObject Open Job Posting Use for active job listings that include role details, hiring entity, and location/salary context. JobPosting Open Retired Learning Video Use for educational videos where the learning objective and pedagogical structure are explicit. LearningResource Open Local Business Use for physical businesses serving local customers with publicly verifiable contact and location details. LocalBusiness Open Loyalty Program Use to publish a loyalty program and its tiers once at the organization level, so member prices and member shipping can reference them. MemberProgram Open Math Solvers Use for pages that solve mathematical expressions and present step-by-step computational guidance. MathSolver Open Merchant Listing Use on pages where a product can be bought, with price, availability, shipping and return details. Product Open Limited Movie Use for movie detail pages with canonical film information and transparent metadata attribution. Movie Open Organization Use for official organization pages to clarify brand identity and authoritative entity signals. Organization Open Retired Practice Problems Use for educational practice content that presents solvable problems and answer validation structure. Quiz Open Product Snippet Use for product pages where pricing, availability, and product identity are visible to users. Product Open Product Variants Use when one product comes in variants such as size or color, grouped with ProductGroup. ProductGroup Open Profile Page Use for creator or contributor profile pages where identity attributes and ownership are explicit. ProfilePage Open Q&A Use for pages where users submit questions and community or editorial answers are displayed. QAPage Open Recipe Use for recipe pages with complete ingredients, instructions, and preparation details. Recipe Open Return Policy Use to publish a merchant return policy once at the organization level, with offer-level overrides. MerchantReturnPolicy Open Review Snippet Use when a page publishes genuine reviews tied to a clearly identified product, service, or entity. Review Open Shipping Policy Use to publish shipping rates, delivery times and destinations once at the organization level. ShippingService Open

Implement Site Name Schema Frameworks Correctly

Get implementation support for conditional schema architecture, validation, and deployment governance.