# SW SEO Schema (JSON-LD) — AI Agent Documentation **Asset type:** Theme partial (`templateType: none`) — not a drag-and-drop module **Partial path:** `smithworks-2025/sw-partials/sw-seo-schema.html` (smithworks portal); source of truth in master `SW-Dev/sw-master/sw-partials/sw-seo-schema.html` **Included from:** `templates/header.html` immediately after `{{ standard_header_includes }}` **Reference:** `docs/PROCESS-SEO-SCHEMA-ROLLDOWN.md`, HubL `company_domain` ([developers.hubspot.com/docs/cms/reference/hubl/variables](https://developers.hubspot.com/docs/cms/reference/hubl/variables)) **Last updated:** 2026.03.23 --- ## 1. Overview The partial outputs **Schema.org JSON-LD** in the page ``: a **`@graph`** with **`WebSite`** (always, when URL + site name resolve) and **`Organization`** when the marketing email footer includes a **company name**. It supports **Google Rich Results** expectations for **Organization** (name, url, logo, **PostalAddress** with **ISO 3166-1 alpha-2** `addressCountry`) and **WebSite**. - **Organization `url` and `@id`:** Use the **canonical site origin** from HubSpot (`company_domain` / logo link), **not** the current page URL. That is correct: the organization entity is the company’s main site, even when the script runs on `/blog` or a blog post. - **Uses `request.scheme` / `request.domain`** when `company_domain` is empty — may interact with HubSpot page caching/prerendering; see partial header comment. --- ## 2. Required HubSpot settings (marketing user paths) ### 2a. Email footer — company name, address, country (same as SW Simple Footer / CAN-SPAM) **Used for:** `Organization.name`, `PostalAddress` (street, city, region, postal code), **`addressCountry`** (mapped to ISO2, e.g. `US`). **Where (current HubSpot UI):** 1. **Settings** (gear) → **Marketing** → **Email** 2. **Configuration** tab → **Footer addresses** 3. **Create email footer** or edit existing → fill **Company name**, address lines, city, state/province, zip/postal code, **Country** **Required fields** follow HubSpot’s email footer form (fields marked required in the UI). **Country → `US`:** The partial normalizes the country string (lowercase, spaces/dots/hyphens removed) and maps values including **United States**, **United States of America**, **USA**, **The United States**, etc., to **`US`**. If country is missing or unmapped, Rich Results may warn about missing **`addressCountry`**. **Also feeds:** `site_settings.company_name` for SW Simple Footer copyright when the footer module leaves Company Name blank — **not** Account defaults → Company information. **Help:** [Edit office location information in email footers](https://knowledge.hubspot.com/marketing-email/edit-office-location-information-in-email-footers) ### 2b. Brand Kit — logo link / primary site URL (`company_domain`) **Used for:** `Organization.url`, `@id` (`{origin}#organization`), **`WebSite.url`**, and graph consistency. **Where (current HubSpot UI — not the old Settings path):** 1. Main menu → **Content** → **Brand** (Brand Identity) 2. **Brand Kit** → **Logos** → open the **default** logo 3. **Logo URL** — “This URL is where the logo will link to when clicked.” Set a **full homepage URL** (e.g. `https://www.example.com` or `https://example.com`). HubL variable **`company_domain`** is documented as coming from the legacy **Website → Pages → Branding → Logo link**; in the **new UI** that value is configured here (**Logo URL** on the default logo), not under old **Settings → Website → Pages → Branding** (often redirects to Content → Brand). **Troubleshooting bad URLs in Rich Results:** If **`Organization.url`** shows as `https:///` or **`@id`** is `https://#organization`, the **Logo URL** is often wrong (e.g. `/`, or `https://` with no host). Fix **Logo URL** to a real origin; do not rely only on **Brand Overview → Website Crawl** (that crawl URL is for brand/AI context, not a substitute for **Logo URL**). **Help:** [Edit your brand's logo, favicon, brand colors, fonts, and theme](https://knowledge.hubspot.com/settings/customize-branding-for-your-hubspot-content) ### 2c. Logo image **Used for:** `Organization.logo` (**ImageObject**) from **Brand Kit** primary logo (same resolution pattern as SW Simple Footer). --- ## 3. Developer notes - **Do not** replace a client’s entire `header.html` from master when adding this partial — **surgical merge:** one `{% include '../sw-partials/sw-seo-schema.html' %}` after `{{ standard_header_includes }}` per `docs/PROCESS-SEO-SCHEMA-ROLLDOWN.md`. - **Changelog** pointer in partial header: theme root `../CHANGELOG.md` (smithworks-2025) or `../sw-modules/CHANGELOG.md` on sw-master — match the file that exists for that theme. --- ## 4. Related - **SW Simple Footer** — same **`site_settings.company_*`** source for company name and address; see **SW-Simple-Footer.txt** and SW AI Documentation **1b. Marketing: Email footer**. --- ## 5. Document version **2026-03-23:** Initial AI doc for SW SEO Schema partial; email footer path (Marketing → Email → Configuration → Footer addresses); Brand **Content → Brand → Logos → Logo URL** for `company_domain` / canonical site (new UI vs old Website → Pages → Branding); US country string variants; Organization URL = site home not current page.