/blog-schema

name: blog-schema
description: >
  Generate complete JSON-LD schema markup for blog posts with Article/BlogPosting,
  Person, Organization, BreadcrumbList, ImageObject, and optional FAQPage. Validates
  against Google requirements and warns about deprecated types. Use when user
  says "schema", "blog schema", "json-ld", "structured data", "schema markup",
  "generate schema".
user-invokable: true
argument-hint: "<file-path>"
license: MIT

Blog Schema: JSON-LD Structured Data Generation

Generates complete, validated JSON-LD schema markup for blog posts using the @graph pattern. Combines multiple schema types into a single script tag with stable @id references for entity linking.

Workflow

Step 1: Read Content

Read the blog post and extract all schema-relevant data:

• **Title** (headline)
• **Author** (name, job title, social links, credentials)
• **Dates** (datePublished, dateModified / lastUpdated)
• **Description** (meta description)
• **FAQ section** (question and answer pairs)
• **Images** (cover image URL, dimensions, alt text; inline images)
• **Organization info** (site name, URL, logo)
• **Word count** (approximate from content length)
• **Tags/categories** (for BreadcrumbList category)
• **Slug** (from filename or frontmatter)

Step 2: Generate BlogPosting Schema

Complete BlogPosting with recommended properties when applicable:

{
  "@type": "BlogPosting",
  "@id": "{siteUrl}/blog/{slug}#article",
  "headline": "Concise post title",
  "description": "Concise page-specific meta description",
  "datePublished": "YYYY-MM-DD",
  "dateModified": "YYYY-MM-DD",
  "author": { "@id": "{siteUrl}/author/{author-slug}#person" },
  "publisher": { "@id": "{siteUrl}#organization" },
  "image": { "@id": "{siteUrl}/blog/{slug}#primaryimage" },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "{siteUrl}/blog/{slug}"
  },
  "wordCount": 2400,
  "articleBody": "First 200 characters of content as excerpt..."
}

Google's Article structured data docs do not define required Article properties. Include `headline`, `datePublished`, `author`, `publisher`, and `image` when applicable, validate with the Rich Results Test, and treat missing fields as warnings unless the target surface requires them. Recommended properties: description, dateModified, mainEntityOfPage, wordCount, articleBody (excerpt).

Step 3: Generate Person Schema

Author schema with stable @id for cross-referencing:

{
  "@type": "Person",
  "@id": "{siteUrl}/author/{author-slug}#person",
  "name": "Author Name",
  "jobTitle": "Role or Title",
  "url": "{siteUrl}/author/{author-slug}",
  "sameAs": [
    "https://twitter.com/handle",
    "https://linkedin.com/in/handle",
    "https://github.com/handle"
  ]
}

Optional properties (include when available):

• `alumniOf` - Educational institution (Organization type)
• `worksFor` - Employer (reference to Organization @id if same entity)

Step 4: Generate Organization Schema

Blog's parent organization entity:

{
  "@type": "Organization",
  "@id": "{siteUrl}#organization",
  "name": "Organization Name",
  "url": "{siteUrl}",
  "logo": {
    "@type": "ImageObject",
    "url": "{siteUrl}/logo.png",
    "width": 600,
    "height": 60
  },
  "sameAs": [
    "https://twitter.com/org",
    "https://linkedin.com/company/org",
    "https://github.com/org"
  ]
}

Logo requirements: use a valid crawlable image URL and follow the active Organization and Article documentation for the target surface. Do not invent hard logo dimensions unless the project or current docs require them.

Step 5: Generate BreadcrumbList

Navigation breadcrumb schema showing content hierarchy:

{
  "@type": "BreadcrumbList",
  "@id": "{siteUrl}/blog/{slug}#breadcrumb",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "{siteUrl}"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Category Name",
      "item": "{siteUrl}/blog/category/{category-slug}"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Post Title",
      "item": "{siteUrl}/blog/{slug}"
    }
  ]
}

If no category is available, use "Blog" as the second breadcrumb item with `{siteUrl}/blog` as the URL.

Step 6: Generate FAQPage Entity Schema (Optional)

Extract Q&A pairs from the blog post's FAQ section:

{
  "@type": "FAQPage",
  "@id": "{siteUrl}/blog/{slug}#faq",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is the question?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "The complete visible answer text."
      }
    }
  ]
}

Google retired FAQ rich results for all sites on 2026-05-07. FAQPage is not a Google rich-result or generative-AI optimization path, and it earns no SEO or AI-readiness credit. Only emit it when a visible FAQ genuinely helps readers, with at least one valid `Question` and matching visible answer. Do not pad an answer to a target length or add an FAQ solely for markup.

Do not substitute QAPage. Google supports QAPage for a page focused on one question where users can submit answers. Editorial FAQs, support FAQs, and blog Q&A sections do not meet that model.

Step 7: Generate VideoObject (if videos present)

For each YouTube video embedded in the post, generate a VideoObject schema:

{
  "@type": "VideoObject",
  "@id": "{siteUrl}/blog/{slug}#video-{index}",
  "name": "Video title",
  "description": "Video description excerpt (first 200 chars)",
  "thumbnailUrl": "https://img.youtube.com/vi/{videoId}/hqdefault.jpg",
  "uploadDate": "{ISO 8601 date}",
  "contentUrl": "https://www.youtube.com/watch?v={videoId}",
  "embedUrl": "https://www.youtube.com/embed/{videoId}",
  "duration": "PT{M}M{S}S",
  "interactionStatistic": {
    "@type": "InteractionCounter",
    "interactionType": { "@type": "WatchAction" },
    "userInteractionCount": {viewCount}
  }
}

Add each