marketing-skill 仓库 Schema Markup 指南：11 类 JSON-LD 结构化数据完整示例与实战落地

• AI 技能
• 人工智能

本篇技术指南基于GitHub_Trending/mar/marketingskills仓库中 skills/schema/references/schema-examples.md 编写，系统覆盖 Organization、WebSite、Article、Product、SoftwareApplication、FAQPage、HowTo、BreadcrumbList、LocalBusiness、Event 等 10 类常用 schema.org 类型的完整 JSON-LD 示例，并给出多类型组合（@graph）与 Next.js 服务端渲染的落地实现。读者读完可掌握从页面类型评估、JSON-LD 编写、多类型组合到验证上线、排查报错的完整实战链路，直接复制文中代码用于自己的站点。

一、为什么需要 schema markup：从 Rich Results 到 AI 可解析性

在正式进入示例之前，先明确结构化数据在仓库体系中的定位。仓库中 skills/schema/SKILL.md 将其定义为核心目标：实现 schema.org 标记，帮助搜索引擎理解内容并触发搜索结果中的富结果（rich results）。

这一目标在仓库内被多个相邻技能复用与深化：

• seo-audit 技能将 "Missing product schema" 列为电商站点常见问题之一，并在 skills/seo-audit/SKILL.md 中强调一个关键坑：web_fetch和curl无法可靠检测结构化数据——许多 CMS 插件（AIOSEO、Yoast、RankMath）通过客户端 JavaScript 注入 JSON-LD，静态 HTML 中看不到。因此检测 schema 必须用浏览器工具、Google Rich Results Test 或 Screaming Frog（它们会渲染 JavaScript）。
• ai-seo 技能把 schema 视为 "Agent Readiness" 解析层（parseability）的关键要素，见 skills/ai-seo/references/agent-readiness.md，并在 skills/ai-seo/SKILL.md 中给出 "Schema Markup for AI" 映射表：Article/BlogPosting、HowTo、FAQPage、Product、ItemList、Review、Organization 分别帮助 AI 引擎提取哪些信息，并指出带 schema 的内容在非 Google AI 引擎上 AI 可见性可提升约 30-40%。
• programmatic-seo 技能在预发布清单中要求 "Schema markup implemented"，见 skills/programmatic-seo/SKILL.md，用于模板化页面的批量结构化标记。
• site-architecture 技能在面包屑章节中同时给出 BreadcrumbList 的 microdata 与 JSON-LD 两种实现，见 skills/site-architecture/references/navigation-patterns.md。

因此，本文的示例文档不仅是"富结果"的实现手册，也是 AI 搜索可见性与大规模模板页面的基础设施层。

实现前的四条核心原则

按 skills/schema/SKILL.md 的 Core Principles，动手前先确立四条纪律：

1. 准确优先：schema 必须精确反映页面真实内容，不标记不存在的内�容，内容变更后同步更新。
2. 使用 JSON-LD：Google 推荐 JSON-LD 格式，更易实现与维护，可放置于<head>或<body>末尾。
3. 遵循 Google 指南：只使用 Google 支持的标记类型，避免作弊手法，逐条核对富结果资格要求。
4. 全部验证：部署前测试、在 Search Console 中监控、及时修复报错。

二、常用类型速查表与必备属性

开始写代码前，先用 skills/schema/SKILL.md 提供的速查表完成"页面类型 → schema 类型 → 必备属性"的映射：

仓库为该技能配置的评估用例（skills/schema/evals/evals.json）也印证了这套映射：给 SaaS 首页加 Organization 时应同时推荐 WebSite（含 SearchAction）与 SoftwareApplication/Product；电商商品页应包含 Product + Offer + AggregateRating + Review + BreadcrumbList；博客文章应包含 Article + BreadcrumbList。

下面逐一给出每个类型的完整 JSON-LD 示例。

三、10 类核心 schema 的完整 JSON-LD 示例

以下示例全部来自 skills/schema/references/schema-examples.md，保留原始结构并在关键处补充字段说明，可直接复制替换为你的真实数据。

3.1 Organization（公司/品牌组织）

用于公司或品牌首页、关于页，是实体识别的基础信号（ai-seo 技能将其列为 Organization entity recognition 的核心 schema）。

{ "@context": "https://schema.org", "@type": "Organization", "name": "Example Company", "url": "https://example.com", "logo": "https://example.com/logo.png", "sameAs": [ "https://twitter.com/example", "https://linkedin.com/company/example", "https://facebook.com/example" ], "contactPoint": { "@type": "ContactPoint", "telephone": "+1-555-555-5555", "contactType": "customer service" } }

按 skills/schema/SKILL.md 的 Quick Reference：name、url为必备；logo、sameAs（社交资料）、contactPoint为推荐。sameAs数组用于将不同平台的官方账号与同一实体关联，是知识图谱（Knowledge Panel）构建的重要输入。

3.2 WebSite（含 SearchAction，开启站内搜索框）

用于首页，可触发搜索结果中的站内搜索框（sitelinks search box）。

{ "@context": "https://schema.org", "@type": "WebSite", "name": "Example", "url": "https://example.com", "potentialAction": { "@type": "SearchAction", "target": { "@type": "EntryPoint", "urlTemplate": "https://example.com/search?q={search_term_string}" }, "query-input": "required name=search_term_string" } }

要点说明：

• urlTemplate中的{search_term_string}是占位符，会被用户的搜索词替换。
• query-input的写法固定为required name=search_term_string，其中required表示该参数必填，name必须与urlTemplate中的占位符名一致——两者不一致是常见报错点。

3.3 Article / BlogPosting（文章与博客）

用于博客文章与新闻文章。这是 AI 引擎最常提取的内容类型之一（作者、日期、主题识别）。

{ "@context": "https://schema.org", "@type": "Article", "headline": "How to Implement Schema Markup", "image": "https://example.com/image.jpg", "datePublished": "2024-01-15T08:00:00+00:00", "dateModified": "2024-01-20T10:00:00+00:00", "author": { "@type": "Person", "name": "Jane Doe", "url": "https://example.com/authors/jane" }, "publisher": { "@type": "Organization", "name": "Example Company", "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" } }, "description": "A complete guide to implementing schema markup...", "mainEntityOfPage": { "@type": "WebPage", "@id": "https://example.com/schema-guide" } }

属性说明与最佳实践：

• 必备属性：headline、image、datePublished、author；推荐属性：dateModified、publisher、description（来自 skills/schema/SKILL.md）。
• author建议用Person类型且附url（作者主页），增强 E-E-A-T 信号；ai-seo 技能强调"具名作者 + 资质"可提升被引用率。
• publisher.logo必须是ImageObject，且 Google 要求 logo 宽度不小于 112px 才符合富结果资格（这是常见验证报错来源）。
• datePublished/dateModified必须使用 ISO 8601 时间格式（含时区偏移），如2024-01-15T08:00:00+00:00。
• mainEntityOfPage用于声明该 schema 对应的规范页面 URL。

3.4 Product（商品，电商或 SaaS）

用于商品详情页，可触发搜索结果中的价格、库存、评分展示。

{ "@context": "https://schema.org", "@type": "Product", "name": "Premium Widget", "image": "https://example.com/widget.jpg", "description": "Our best-selling widget for professionals", "sku": "WIDGET-001", "brand": { "@type": "Brand", "name": "Example Co" }, "offers": { "@type": "Offer", "url": "https://example.com/products/widget", "priceCurrency": "USD", "price": "99.99", "availability": "https://schema.org/InStock", "priceValidUntil": "2024-12-31" }, "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.8", "reviewCount": "127" } }

要点：

• 必备：name、image、offers（含price与availability）；推荐：sku、brand、aggregateRating、review。
• priceCurrency使用 ISO 4217 货币代码（USD、EUR、CNY 等）。
• availability是 schema.org 枚举值，必须写完整 URL（如https://schema.org/InStock），不能写裸字符串InStock——枚举值不精确是常见验证错误（SKILL.md 的 Common Errors 明确列出 "enumerations exact"）。
• aggregateRating.ratingValue与reviewCount用字符串数字即可。注意 Google 对评分有额外要求（至少一个真实 Review、评分来自真实用户），仅堆评分有违规风险。
• 电商场景可叠加BreadcrumbList（导航）与Review（单条评论），这是 evals.json 中第 4 个评估用例的明确预期输出。

3.5 SoftwareApplication（SaaS / App 落地页）

用于 SaaS 产品页与应用落地页。SaaS 首页场景下通常与 Organization、WebSite 配合使用。

{ "@context": "https://schema.org", "@type": "SoftwareApplication", "name": "Example App", "applicationCategory": "BusinessApplication", "operatingSystem": "Web, iOS, Android", "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" }, "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.6", "ratingCount": "1250" } }

要点：

• 必备：name、offers。
• applicationCategory应使用 schema.org 预定义的枚举值（如BusinessApplication、GameApplication、MultimediaApplication），同样要求精确枚举。
• operatingSystem是自由文本，可列出支持的平台；price为"0"表示免费应用。

3.6 FAQPage（常见问题页）

用于包含常见问题的页面，可触发搜索结果中直接展示问答的富结果。

{ "@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [ { "@type": "Question", "name": "What is schema markup?", "acceptedAnswer": { "@type": "Answer", "text": "Schema markup is a structured data vocabulary that helps search engines understand your content..." } }, { "@type": "Question", "name": "How do I implement schema?", "acceptedAnswer": { "@type": "Answer", "text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..." } } ] }

要点：

• 必备：mainEntity（Question/Answer 对数组），结构为 FAQPage → Question → Answer 三层嵌套。
• 按 evals.json 第 2 个评估用例，实现时须注意 Google 对 FAQ schema 的指南：答案应是事实性的，而非促销性内容；促销型 FAQ 不满足富结果资格。
• FAQ 块同时也是 ai-seo 技能中 "Direct Q&A extraction" 的核心结构，对非 Google 的 AI 引擎尤其有效。
• 若页面有 20 个问题，可全部列出或抽取 2-3 个代表性示例并说明完整结构，但页面主体应真实包含这些问答内容（准确优先原则）。

3.7 HowTo（教程步骤）

用于教学类内容与教程，结构化步骤便于搜索引擎与 AI 引擎提取过程信息。

{ "@context": "https://schema.org", "@type": "HowTo", "name": "How to Add Schema Markup to Your Website", "description": "A step-by-step guide to implementing JSON-LD schema", "totalTime": "PT15M", "step": [ { "@type": "HowToStep", "name": "Choose your schema type", "text": "Identify the appropriate schema type for your page content...", "url": "https://example.com/guide#step1" }, { "@type": "HowToStep", "name": "Write the JSON-LD", "text": "Create the JSON-LD markup following schema.org specifications...", "url": "https://example.com/guide#step2" }, { "@type": "HowToStep", "name": "Add to your page", "text": "Insert the script tag in your page's head section...", "url": "https://example.com/guide#step3" } ] }

要点：

• 必备：name、step。
• totalTime使用 ISO 8601 时长格式（PT15M表示 15 分钟，PT1H30M表示 1 小时 30 分）。
• 每一步用HowToStep类型，url可指向页内锚点（#step1）。步骤式结构对应 ai-seo 技能中的 "Step extraction for process queries"。

3.8 BreadcrumbList（面包屑导航）

用于任何带面包屑导航的页面，为搜索引擎提供页面层级结构信号。site-architecture 技能在 skills/site-architecture/references/navigation-patterns.md 中也强调"面包屑应配合 schema markup 实现"，并提供 microdata 与 JSON-LD 两种写法，这里给出 JSON-LD 版本：

{ "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com" }, { "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog" }, { "@type": "ListItem", "position": 3, "name": "SEO Guide", "item": "https://example.com/blog/seo-guide" } ] }

要点：

• 必备：itemListElement（含position、name、item的数组）。
• position从 1 开始连续递增。
• 面包屑层级必须与实际 URL 结构一致——site-architecture 技能将 "Breadcrumbs that don't match URLs" 列为反模式（breadcrumb 显示 "Products > Widget" 但 URL 是/shop/widget-pro）。
• 与 programmatic-seo 的索引策略呼应：批量模板页都应配套 BreadcrumbList，避免孤立页面（orphan pages）。

3.9 LocalBusiness（本地商户）

用于本地商户门店页，可触发本地富结果。地址、营业时间、经纬度都是关键字段。

{ "@context": "https://schema.org", "@type": "LocalBusiness", "name": "Example Coffee Shop", "image": "https://example.com/shop.jpg", "address": { "@type": "PostalAddress", "streetAddress": "123 Main Street", "addressLocality": "San Francisco", "addressRegion": "CA", "postalCode": "94102", "addressCountry": "US" }, "geo": { "@type": "GeoCoordinates", "latitude": "37.7749", "longitude": "-122.4194" }, "telephone": "+1-555-555-5555", "openingHoursSpecification": [ { "@type": "OpeningHoursSpecification", "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"], "opens": "08:00", "closes": "18:00" } ], "priceRange": "$$" }

要点：

• 必备：name、address。
• address使用PostalAddress子类型，addressCountry用 ISO 3166-1 alpha-2 国家代码（US、CN、JP 等）。
• geo使用GeoCoordinates，经纬度为十进制数字字符串。
• openingHoursSpecification的dayOfWeek是星期枚举数组，opens/closes用 24 小时制 HH:MM。
• 本地商户还应注意 NAP（Name-Address-Phone）一致性：seo-audit 技能将 "Inconsistent NAP" 和 "Missing local schema" 列为本地商户常见问题，schema 中的信息应与页面可见内容、Google Business Profile 保持一致。

3.10 Event（活动、网络研讨会、会议）

用于活动页、网络研讨会、行业会议，可触发活动富结果。仓库的 skills/events 技能体系（webinar-funnel、speaking、sponsorship-roi 等）对应的落地页均可套用此模板。

{ "@context": "https://schema.org", "@type": "Event", "name": "Annual Marketing Conference", "startDate": "2024-06-15T09:00:00-07:00", "endDate": "2024-06-15T17:00:00-07:00", "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode", "eventStatus": "https://schema.org/EventScheduled", "location": { "@type": "VirtualLocation", "url": "https://example.com/conference" }, "image": "https://example.com/conference.jpg", "description": "Join us for our annual marketing conference...", "offers": { "@type": "Offer", "url": "https://example.com/conference/tickets", "price": "199", "priceCurrency": "USD", "availability": "https://schema.org/InStock", "validFrom": "2024-01-01" }, "performer": { "@type": "Organization", "name": "Example Company" }, "organizer": { "@type": "Organization", "name": "Example Company", "url": "https://example.com" } }

要点：

• 必备：name、startDate、location。
• 线上活动用VirtualLocation（含url）配合eventAttendanceMode的枚举 URLhttps://schema.org/OnlineEventAttendanceMode；线下活动则用Place加地址。
• eventStatus使用 schema.org 枚举（EventScheduled、EventPostponed、EventCancelled等），同样写完整 URL。
• 时间格式为 ISO 8601 且含时区偏移（-07:00），跨时区活动尤其要写清。

四、多类型组合：用 @graph 在一页挂载多个 schema

一个页面往往同时承载多个实体（公司 + 站点 + 面包屑 + 文章）。推荐用@graph在一个 JSON-LD 脚本块中组合多个类型，避免页面堆叠大量<script>标签。

{ "@context": "https://schema.org", "@graph": [ { "@type": "Organization", "@id": "https://example.com/#organization", "name": "Example Company", "url": "https://example.com" }, { "@type": "WebSite", "@id": "https://example.com/#website", "url": "https://example.com", "name": "Example", "publisher": { "@id": "https://example.com/#organization" } }, { "@type": "BreadcrumbList", "itemListElement": [...] } ] }

关键技巧：@id建立实体间引用。上例中WebSite.publisher通过@id指向Organization，两个类型在同一图中被关联为同一实体，而非两个孤立对象。这是 evals.json 第 1 个评估用例的明确要求（"Should use @graph for multiple schema types on one page"），也是 SaaS 首页的标准组合方式：Organization + WebSite（含 SearchAction）+ SoftwareApplication/Product。

五、验证与测试：上线前必须做的检查

schema 写完之后，按 skills/schema/SKILL.md 的 Validation and Testing 章节完成验证闭环。

验证工具

• Google Rich Results Test：最常用，会渲染 JavaScript（可捕获 JS 注入的 JSON-LD），能直接看到可触发的富结果预览与报错。
• Schema.org Validator：官方校验器，做语法与结构检查。
• Search Console：Enhancements（增强）报告，监控已上线页面的结构化数据状态与错误。

seo-audit 技能特别提醒：web_fetch与curl会剥离<script>标签、无法看到 JS 注入的 schema，因此不要仅凭抓取结果就判定"页面没有 schema"，这会产生虚假审计结论。

三类高频错误（SKILL.md 原文）

1. 缺少必备属性（Missing required properties）：对照 Google 官方文档核对必备字段（如 Article 必须有author）。
2. 非法值（Invalid values）：日期必须是 ISO 8601 格式；URL 必须是完整限定地址；枚举值必须精确匹配 schema.org 的枚举 URL，不能写缩写。
3. 与页面内容不一致（Mismatch with page content）：schema 标记了页面上不存在的内�容（如评分、FAQ 问答），违反"准确优先"原则，也是 Google 反作弊的重点。

上线清单（SKILL.md Testing Checklist）

• 在 Rich Results Test 中验证通过
• 无错误（errors）且无警告（warnings）
• 与页面可见内容一致
• 所有必备属性均已包含

一个容易被误解的事实

验证通过 ≠ 必然展示富结果。Google 会自行决定是否以及何时展示富结果——schema 合法只是资格条件，不保证出现。这一认知在 evals.json 第 5 个评估用例中被明确要求：排查富结果不出现时应先区分"警告 vs 错误"、"有资格 vs 已展示"，并在 Search Console 的结构化数据报告中持续观察。

六、实现落地：从静态站到 Next.js 动态渲染

静态站点

直接将 JSON-LD 写入 HTML 模板。多个页面复用的 schema（如 Organization、WebSite）应抽成 include/partial，避免每个页面复制粘贴导致维护失控。

动态站点（React / Next.js）

用组件渲染 schema，并确保服务端渲染（SSR），因为 Googlebot 对纯客户端渲染内容无法稳定读取。以 skills/schema/references/schema-examples.md 结尾的 Next.js 示例为骨架：

export default function ProductPage({ product }) { const schema = { "@context": "https://schema.org", "@type": "Product", name: product.name, // ... other properties }; return ( <> <Head> <script type="application/ld+json" dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }} /> </Head> {/* Page content */} </> ); }

实践要点：

• <script>的type必须是application/ld+json。
• dangerouslySetInnerHTML用于把 JSON 字符串注入脚本块；JSON.stringify(schema)负责序列化对象。
• 动态字段（product.name、日期、作者、价格）从 CMS 或数据层注入，保证 schema 与页面内容永远同步——这正对应 evals.json 第 3 个评估用例中"address how to populate dynamic fields from the CMS"的要求。
• 在大规模模板页（programmatic-seo 场景）中，同一组件可驱动成百上千个页面，配合@graph组合 Organization/WebSite/BreadcrumbList，实现结构化数据层面的"模板化"。

CMS / WordPress

使用插件（Yoast、Rank Math、Schema Pro）或主题修改 + 自定义字段映射到结构化数据。注意插件注入的 JSON-LD 多为客户端 JS 渲染，验证时需用会渲染 JS 的工具。

七、与仓库其他技能的协作边界

最后给出仓库内的技能分工，方便读者按需调用（来自 skills/schema/SKILL.md 的 Related Skills 及 skills/seo-audit/SKILL.md 的调度规则）：

• seo-audit：整体 SEO 审计（含 schema 审查）；若用户的问题是"流量下降、排名丢失"这类整体诊断，应优先走 seo-audit 而非 schema（evals.json 第 6 个用例明确了这一边界）。
• ai-seo：AI 搜索优化——schema 帮助 AI 理解内容，是 "Parseability" 解析层的一部分。
• programmatic-seo：模板化批量页面的 schema 输出（如每页一套 BreadcrumbList + Organization）。
• site-architecture：面包屑结构与导航 schema 规划。

延伸阅读

• skills/schema/SKILL.md：schema 技能的完整方法论、速查表、验证清单
• skills/schema/evals/evals.json：6 个评估用例，覆盖 SaaS 首页、FAQ、博客、电商、排错、边界分流
• skills/ai-seo/references/agent-readiness.md：结构化数据在 Agent 可解析性中的定位
• skills/programmatic-seo/references/playbooks.md：12 种批量页面模式及 schema 配套
• skills/site-architecture/references/navigation-patterns.md：面包屑的 microdata 与 JSON-LD 双写法

将本文 10 类示例与 @graph 组合、Next.js 组件化方案配合使用，即可为从公司首页、博客、电商商品页到本地商户、活动页的几乎所有页面类型，交付一套可验证、可维护、对搜索与 AI 引擎都友好的结构化数据方案。

• AI 技能
• 人工智能