structured-data

Name: structured-data
Author: cognyai

github.com/cognyai营销与增长11149 次安装2 周前更新

代码仓库

关于 structured-data

面向开发者和网站运营者的 Schema.org 结构化数据参考技能，提供常见类型的 JSON-LD 示例、富媒体搜索结果指南和验证建议。

主要功能

01常见 Schema 类型的 JSON-LD 示例
02富媒体搜索结果资格指南
03验证工具与错误修复建议
04适用于多种网站平台的实现模式

适用场景

01为页面选择 Schema 类型
02编写产品或文章的 JSON-LD 标记
03检查结构化数据错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cognyai/claude-code-marketing-skills --skill structured-data

安装后在 Claude Code 中输入/structured-data确认已加载。

详细介绍

Schema.org 结构化数据参考

Schema.org 结构化数据标记完整参考：JSON-LD 示例、富媒体搜索结果资格、测试工具、验证，以及适用于静态网站、Next.js、React 和 WordPress 的实现模式。

完整文档：https://cogny.com/docs/structured-data-reference

用法

/structured-data                          # Full reference overview
/structured-data Product                  # Show Product schema example
/structured-data FAQPage                  # Show FAQPage example
/structured-data LocalBusiness            # Show LocalBusiness example
/structured-data validate                 # Testing and validation guide
/structured-data best-practices           # Schema best practices
/structured-data rich-results             # Rich results eligibility table

说明

你是一名 Schema.org 结构化数据专家。请利用此参考帮助用户编写正确的 JSON-LD 标记，为页面选择合适的 schema 类型，验证结构化数据，并在不同平台上实现结构化数据。

用户提问时，请查找下方的相关部分，并提供准确、可操作且可直接使用的 JSON-LD 示例。

如果用户在参数中指定了某个 schema 类型或主题，请聚焦该领域。否则，请提供概览，并帮助用户确定需要哪种 schema 类型。

如果有可用的 Search Console MCP 工具，请使用这些工具：

通过 tool_get_search_analytics 检查哪些页面获得了富媒体搜索结果（按搜索外观筛选）
通过 tool_inspect_url 检查特定 URL 的结构化数据问题
通过 tool_list_properties 列出属性，以确定要审核哪些网站

结构化数据的作用

结构化数据是一种机器可读的标记，可准确告知搜索引擎、语音助手和 AI 系统页面内容的含义。你可以使用 Schema.org 词汇表显式声明这些信息。

优势：

富媒体搜索结果 — Google 搜索中的星级评分、价格、FAQ 折叠栏、操作步骤和活动列表
知识面板 — 面向组织、个人和产品的品牌面板
语音搜索 — Google Assistant 和其他语音界面中的直接答案
AI 引用 — 大模型和 AI 搜索引擎（Google AI Overviews、Bing Copilot、Perplexity）利用结构化数据呈现并注明信息来源

格式

结构化数据有三种格式。Google 明确推荐使用 JSON-LD。

JSON-LD（推荐）

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Corp"
}
</script>

为什么选择 JSON-LD： 与 HTML 解耦，可由 JS 框架注入，易于验证，且不会影响布局。

Microdata

内联 HTML 属性（itemscope、itemtype、itemprop）。仅用于无法添加 <script> 标签的旧系统。

RDFa

内联属性（vocab、typeof、property）。在 Web 上较少见，在 XML/SVG 场景中更常见。

总之： 所有新的实现都应使用 JSON-LD。

Schema 类型及 JSON-LD 示例

Organization

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Cogny AI",
  "url": "https://cogny.com",
  "logo": "https://cogny.com/images/logo.png",
  "sameAs": [
    "https://twitter.com/cognyai",
    "https://linkedin.com/company/cogny",
    "https://github.com/cognyai"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+46-8-123-4567",
    "contactType": "customer service",
    "availableLanguage": ["English", "Swedish"]
  },
  "foundingDate": "2023",
  "numberOfEmployees": {
    "@type": "QuantitativeValue",
    "value": 15
  }
}

必填： name | 推荐： url、logo、sameAs、contactPoint 富媒体搜索结果： 知识面板

LocalBusiness

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Nordic Coffee Roasters",
  "image": "https://example.com/photos/storefront.jpg",
  "url": "https://nordiccoffee.se",
  "telephone": "+46-8-765-4321",
  "priceRange": "$$",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "Drottninggatan 45",
    "addressLocality": "Stockholm",
    "addressRegion": "Stockholm",
    "postalCode": "111 21",
    "addressCountry": "SE"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 59.3293,
    "longitude": 18.0686
  },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "07:00",
      "closes": "18:00"
    },
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Saturday", "Sunday"],
      "opens": "09:00",
      "closes": "16:00"
    }
  ]
}

必填： name、address | 推荐： geo、openingHoursSpecification、telephone、priceRange、image 富媒体搜索结果： 本地商家列表、包含地图／营业时间／电话的知识面板

Product

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Noise-Cancelling Headphones",
  "image": [
    "https://example.com/photos/headphones-front.jpg",
    "https://example.com/photos/headphones-side.jpg"
  ],
  "description": "Premium wireless headphones with active noise cancellation, 30-hour battery life, and multipoint Bluetooth connectivity.",
  "sku": "WH-1000XM5",
  "brand": {
    "@type": "Brand",
    "name": "AudioTech"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/headphones-wh1000xm5",
    "priceCurrency": "USD",
    "price": "349.99",
    "priceValidUntil": "2025-12-31",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "seller": {
      "@type": "Organization",
      "name": "AudioTech Store"
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "bestRating": "5",
    "reviewCount": "2847"
  }
}

获得富媒体搜索结果的必填项： name、image、offers（包含 price、priceCurrency、availability） 推荐： sku、brand、aggregateRating、description 富媒体搜索结果： 显示价格、库存情况和星级评分的产品摘要

FAQPage

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is structured data?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Structured data is machine-readable markup added to HTML pages that helps search engines understand your content. It uses the Schema.org vocabulary and is typically implemented in JSON-LD format."
      }
    },
    {
      "@type": "Question",
      "name": "Does structured data improve SEO rankings?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Structured data does not directly affect rankings. However, it enables rich results that significantly improve click-through rates, which can indirectly improve performance through higher engagement signals."
      }
    }
  ]
}

必填： 包含 Question 项目的 mainEntity 数组，每个项目都包含 acceptedAnswer 富媒体搜索结果： 可展开的 FAQ 折叠栏（最多 10 个问题）

HowTo

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Implement JSON-LD Structured Data",
  "description": "A step-by-step guide to adding Schema.org JSON-LD structured data to your website.",
  "totalTime": "PT15M",
  "estimatedCost": {
    "@type": "MonetaryAmount",
    "currency": "USD",
    "value": "0"
  },
  "tool": [
    { "@type": "HowToTool", "name": "Text editor or CMS" },
    { "@type": "HowToTool", "name": "Google Rich Results Test" }
  ],
  "step": [
    {
      "@type": "HowToStep",
      "name": "Choose your schema type",
      "text": "Identify the primary content type of your page and look up the required properties at schema.org.",
      "url": "https://example.com/guide#step1",
      "image": "https://example.com/images/step1.png"
    },
    {
      "@type": "HowToStep",
      "name": "Write the JSON-LD block",
      "text": "Create a JSON-LD script block with @context, @type, and all required properties.",
      "url": "https://example.com/guide#step2",
      "image": "https://example.com/images/step2.png"
    },
    {
      "@type": "HowToStep",
      "name": "Insert into your page",
      "text": "Place the script tag in the head or body of your HTML document.",
      "url": "https://example.com/guide#step3",
      "image": "https://example.com/images/step3.png"
    },
    {
      "@type": "HowToStep",
      "name": "Validate with testing tools",
      "text": "Run your page through the Google Rich Results Test and Schema Markup Validator.",
      "url": "https://example.com/guide#step4",
      "image": "https://example.com/images/step4.png"
    }
  ]
}

必填： name、step（每个步骤都包含 text） | 推荐： 每个步骤的 image、totalTime、tool 富媒体搜索结果： 带图片的编号分步说明

Article / BlogPosting

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Complete Guide to Schema.org Structured Data",
  "description": "Learn how to implement structured data markup to earn rich results in Google Search.",
  "image": [
    "https://example.com/images/guide-16x9.jpg",
    "https://example.com/images/guide-4x3.jpg",
    "https://example.com/images/guide-1x1.jpg"
  ],
  "author": {
    "@type": "Person",
    "name": "Anna Lindqvist",
    "url": "https://example.com/authors/anna-lindqvist"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example Publishing",
    "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" }
  },
  "datePublished": "2025-01-15",
  "dateModified": "2025-02-10",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://example.com/guides/structured-data"
  }
}

新闻使用 Article，博客使用 BlogPosting，Google 新闻发布者使用 NewsArticle。

必填： headline、image、datePublished、author 富媒体搜索结果： 文章轮播、头条新闻（NewsArticle），以及搜索结果中的作者／日期信息

BreadcrumbList

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
    { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://example.com/docs" },
    { "@type": "ListItem", "position": 3, "name": "Structured Data", "item": "https://example.com/docs/structured-data" }
  ]
}

必填： 包含 position、name、item 的 itemListElement 富媒体搜索结果： 搜索结果中的 URL 会替换为面包屑导航

Review / AggregateRating

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Cloud Analytics Platform",
  "review": [
    {
      "@type": "Review",
      "reviewRating": { "@type": "Rating", "ratingValue": "5", "bestRating": "5" },
      "author": { "@type": "Person", "name": "Erik Johansson" },
      "reviewBody": "Transformed our data pipeline. The BigQuery integration is seamless.",
      "datePublished": "2025-01-20"
    }
  ],
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "bestRating": "5",
    "ratingCount": "312",
    "reviewCount": "189"
  }
}

评论必须嵌套在其所评论的项目中——没有上下文的独立 Review 标记不会生成富媒体搜索结果。

必需： ratingValue、bestRating、author（Review）；ratingValue、ratingCount（AggregateRating） 富媒体搜索结果： 星级评分摘要

Event

{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Nordic Growth Marketing Summit 2025",
  "description": "Two-day conference on performance marketing and AI-driven analytics.",
  "startDate": "2025-09-15T09:00:00+02:00",
  "endDate": "2025-09-16T17:00:00+02:00",
  "eventStatus": "https://schema.org/EventScheduled",
  "eventAttendanceMode": "https://schema.org/OfflineEventAttendanceMode",
  "location": {
    "@type": "Place",
    "name": "Stockholm Waterfront Congress Centre",
    "address": {
      "@type": "PostalAddress",
      "streetAddress": "Nils Ericsons Plan 4",
      "addressLocality": "Stockholm",
      "postalCode": "111 64",
      "addressCountry": "SE"
    }
  },
  "performer": { "@type": "Organization", "name": "Cogny AI" },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/tickets",
    "price": "4999",
    "priceCurrency": "SEK",
    "availability": "https://schema.org/InStock",
    "validFrom": "2025-03-01T00:00:00+01:00"
  },
  "organizer": { "@type": "Organization", "name": "Growth Hackers Stockholm", "url": "https://growthhackers.se" },
  "image": "https://example.com/images/summit-2025.jpg"
}

必需： name、startDate、location | 建议： endDate、offers、performer、eventStatus、image 富媒体搜索结果： 显示日期、地点和门票的活动列表；SERP 中的活动信息包

VideoObject

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Set Up GA4 BigQuery Export",
  "description": "Step-by-step tutorial for connecting GA4 to BigQuery.",
  "thumbnailUrl": "https://example.com/thumbnails/ga4-setup.jpg",
  "uploadDate": "2025-01-10",
  "duration": "PT12M30S",
  "contentUrl": "https://example.com/videos/ga4-setup.mp4",
  "embedUrl": "https://youtube.com/embed/abc123",
  "interactionStatistic": {
    "@type": "InteractionCounter",
    "interactionType": { "@type": "WatchAction" },
    "userInteractionCount": 15420
  }
}

必需： name、thumbnailUrl、uploadDate | 建议： description、duration、contentUrl 或 embedUrl 富媒体搜索结果： 视频轮播；搜索结果中的视频缩略图

SoftwareApplication

{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Cogny Analytics Platform",
  "operatingSystem": "Web",
  "applicationCategory": "BusinessApplication",
  "description": "AI-powered analytics platform for automated growth insights.",
  "offers": { "@type": "Offer", "price": "99", "priceCurrency": "USD" },
  "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.8", "ratingCount": "156" },
  "screenshot": "https://example.com/images/dashboard.png"
}

必需： name、offers（包含 price、priceCurrency） | 建议： operatingSystem、applicationCategory、aggregateRating 富媒体搜索结果： 显示评分和价格的软件摘要

Course

{
  "@context": "https://schema.org",
  "@type": "Course",
  "name": "Advanced BigQuery for Marketing Analytics",
  "description": "Learn to write efficient BigQuery SQL for GA4 data, build attribution models, and create automated reporting.",
  "provider": { "@type": "Organization", "name": "Cogny Academy", "sameAs": "https://cogny.com/academy" },
  "courseCode": "BQ-301",
  "hasCourseInstance": {
    "@type": "CourseInstance",
    "courseMode": "online",
    "courseSchedule": {
      "@type": "Schedule",
      "repeatFrequency": "P1W",
      "startDate": "2025-03-01",
      "endDate": "2025-04-15"
    }
  },
  "offers": { "@type": "Offer", "price": "499", "priceCurrency": "USD", "category": "Paid" }
}

必需： name、description、provider | 建议： offers、hasCourseInstance 富媒体搜索结果： 显示提供方和报名信息的课程列表

JobPosting

{
  "@context": "https://schema.org",
  "@type": "JobPosting",
  "title": "Senior Growth Engineer",
  "description": "Build and optimize marketing analytics infrastructure including BigQuery pipelines, A/B testing, and automated reporting.",
  "datePosted": "2025-02-01",
  "validThrough": "2025-04-01T23:59:59+01:00",
  "employmentType": "FULL_TIME",
  "hiringOrganization": {
    "@type": "Organization",
    "name": "Cogny AI",
    "sameAs": "https://cogny.com",
    "logo": "https://cogny.com/images/logo.png"
  },
  "jobLocation": {
    "@type": "Place",
    "address": {
      "@type": "PostalAddress",
      "addressLocality": "Stockholm",
      "addressRegion": "Stockholm",
      "addressCountry": "SE"
    }
  },
  "jobLocationType": "TELECOMMUTE",
  "baseSalary": {
    "@type": "MonetaryAmount",
    "currency": "SEK",
    "value": { "@type": "QuantitativeValue", "minValue": 55000, "maxValue": 75000, "unitText": "MONTH" }
  },
  "applicantLocationRequirements": { "@type": "Country", "name": "Sweden" }
}

必需： title、description、datePosted、hiringOrganization、jobLocation 建议： validThrough、employmentType、baseSalary、jobLocationType 富媒体搜索结果： 显示薪资、地点和申请按钮的 Google Jobs 列表

测试与验证

Google 富媒体搜索结果测试

网址： https://search.google.com/test/rich-results

测试单个页面或代码片段是否符合富媒体搜索结果的展示条件。可查看检测到的类型、验证错误和警告。

Schema 标记验证工具

网址： https://validator.schema.org

依据完整的 Schema.org 规范进行验证，可发现富媒体搜索结果测试可能遗漏的结构错误。

Google Search Console 富媒体搜索结果报告

位置： Search Console > 增强功能 > [具体富媒体搜索结果类型]

汇总整个网站的数据：有效页面数、错误数及具体错误类型。每日更新。

常见验证错误

错误	原因	修复方法
`Missing field "image"`	Product/Article 缺少图片	添加 `image`，并使用有效且可抓取的网址
`Invalid URL in field "url"`	使用了相对网址	使用完整网址（`https://...`）
`Missing field "author"`	Article/Review 缺少作者	添加 `author`，将其设为包含 `name` 的 Person 或 Organization
`Invalid value in field "price"`	价格中包含货币符号	只使用数值（`"349.99"`，不要使用 `"$349.99"`）
`Invalid enum for "availability"`	使用了纯文本，而非网址	使用 `https://schema.org/InStock`，不要使用 `"In Stock"`
`Array expected, single value`	使用了单张图片，而非数组	用数组封装：`"image": ["https://..."]`
`datePublished is in the future`	日期设为未来的发布日期	设置为实际发布日期

最佳实践

每页使用一种主要 Schema 类型

根据页面用途匹配主要 Schema 类型。产品页面使用 Product，博客文章使用 BlogPosting，常见问题页面使用 FAQPage。可搭配 BreadcrumbList 作为补充类型。

嵌套与 @graph

存在父子关系时（Product > Offer）使用嵌套。同一页面上的独立实体使用 @graph：

{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "BreadcrumbList", "itemListElement": [...] },
    { "@type": "Product", "name": "Widget", "offers": {...} }
  ]
}

必需属性与建议属性

富媒体搜索结果要显示，必须包含必需属性。建议属性可提升质量和展示效果。始终同时包含这两类属性。

避免垃圾标记

不要伪造评论或评分
Schema 属性必须与页面上可见的内容一致
不要为隐藏内容添加 Schema
Schema 类型必须与页面用途相符
缺少真实第三方数据的自我服务型评论会触发人工处置

Google 对结构化数据垃圾内容采取的人工处置可能会移除整个域名的所有富媒体搜索结果。

保持 Schema 同步

从与页面内容相同的数据源生成结构化数据。将 Schema 更新纳入 CMS 发布工作流。每季度或网站发生重大变更后进行审核。

富媒体搜索结果资格

Schema 类型	富媒体搜索结果	搜索结果页外观
`Product`	产品摘要	价格、库存情况、星级
`FAQPage`	FAQ 折叠面板	搜索结果中的可展开问答
`HowTo`	操作步骤	带图片的编号步骤
`Article` / `BlogPosting`	文章结果	作者、日期、缩略图
`NewsArticle`	热门新闻	搜索结果顶部的轮播
`BreadcrumbList`	面包屑导航	用导航路径替代 URL
`Review` / `AggregateRating`	评价摘要	列表下方的星级评分
`Event`	活动列表	日期、地点、门票
`VideoObject`	视频结果	缩略图、时长
`LocalBusiness`	本地商家信息包	地图、营业时间、电话
`JobPosting`	Google Jobs	薪资、地点、申请
`SoftwareApplication`	软件结果	评分、价格
`Course`	课程列表	提供方、注册人数
`Organization`	知识面板	徽标、社交链接

实现模式

静态 HTML

<head>
  <script type="application/ld+json">
  { "@context": "https://schema.org", "@type": "Product", ... }
  </script>
</head>

Next.js（App Router）

export default function ProductPage({ product }) {
  const jsonLd = {
    "@context": "https://schema.org",
    "@type": "Product",
    name: product.name,
    image: product.images,
    offers: {
      "@type": "Offer",
      price: product.price,
      priceCurrency: product.currency,
      availability: product.inStock
        ? "https://schema.org/InStock"
        : "https://schema.org/OutOfStock",
    },
  };
  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      {/* content */}
    </>
  );
}

WordPress

使用 Yoast SEO、Rank Math 或 Schema Pro 插件。自定义实现方式：

add_action('wp_head', function() {
    if (is_singular('product')) {
        $product = get_post();
        $price = get_post_meta($product->ID, '_price', true);
        $schema = [
            '@context' => 'https://schema.org',
            '@type' => 'Product',
            'name' => $product->post_title,
            'offers' => [
                '@type' => 'Offer',
                'price' => $price,
                'priceCurrency' => 'USD',
                'availability' => 'https://schema.org/InStock',
            ],
        ];
        echo '<script type="application/ld+json">' . json_encode($schema) . '</script>';
    }
});

动态 CMS 模式

function generateProductSchema(cmsData: CMSProduct): object {
  return {
    "@context": "https://schema.org",
    "@type": "Product",
    name: cmsData.title,
    image: cmsData.media.map(m => m.url),
    offers: {
      "@type": "Offer",
      price: cmsData.variants[0].price.toString(),
      priceCurrency: cmsData.currency,
      availability: cmsData.inStock
        ? "https://schema.org/InStock"
        : "https://schema.org/OutOfStock",
    },
  };
}

核心原则：从填充页面的同一数据源生成结构化数据，绝不要单独硬编码。

资源

Schema.org 完整词汇表： https://schema.org/docs/full.html
Google 富媒体搜索结果图库： https://developers.google.com/search/docs/appearance/structured-data/search-gallery
Google 富媒体搜索结果测试： https://search.google.com/test/rich-results
Schema 标记验证工具： https://validator.schema.org
完整 Cogny 文档： https://cogny.com/docs/structured-data-reference

支持 Markdown

登录后评论

基本信息

作者: cognyai
仓库: cognyai/claude-code-marketing-skills
分类: 营销与增长
安装次数: 49
GitHub Stars: 111

报告问题