LLM Best Practices

Schema Markup Deep Dive

5 min read

View markdown source

Overview

The five baseline schemas (WebSite, Organization, BreadcrumbList, Article, Person) cover most pages. The next tier (HowTo, FAQPage, Product, Course, VideoObject, DefinedTerm) earns specialized rich results when the page genuinely is that thing. Shipping the wrong schema or marking up invisible content triggers manual actions; ship only what matches what a human sees on the page. For the one-page type-to-required-field reference, see schema-org-types; for the static-site embed walkthrough, see add-jsonld-to-static-site.

HowTo: step-by-step instructions with named outcomes

HowTo schema earns step-by-step rich results in mobile search. It applies to procedural content with a clear outcome.

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Install Postgres on Ubuntu 24.04",
  "totalTime": "PT10M",
  "supply": [{ "@type": "HowToSupply", "name": "Ubuntu 24.04 server" }],
  "tool": [{ "@type": "HowToTool", "name": "apt" }],
  "step": [
    { "@type": "HowToStep", "name": "Update apt", "text": "Run sudo apt update." },
    { "@type": "HowToStep", "name": "Install Postgres", "text": "Run sudo apt install postgresql-16." }
  ]
}
  • Every step has a name and a text. Add image for visual steps.
  • totalTime uses ISO 8601 duration format: PT10M is ten minutes, PT1H30M is 90 minutes.
  • Apply only when the page is a real procedural guide. Marking up a generic article as HowTo is a guideline violation.

FAQPage: real questions with non-promotional answers

FAQPage earns FAQ accordions in search (currently limited to government and health sites, but ship anyway for AI agents and future eligibility).

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is Postgres?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Postgres is an open-source relational database."
      }
    }
  ]
}
  • The page must visibly contain the same questions and answers. Hidden FAQs trigger manual actions.
  • Each question has exactly one accepted answer. Multiple acceptedAnswer entries are invalid.
  • Answers contain real information, not “contact us for details.” Promotional answers disqualify the markup.

Product: e-commerce schema with offers and reviews

Product schema earns shopping rich results, the price-and-stars annotations under organic results.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Mechanical Keyboard",
  "image": "https://example.com/keyboard.jpg",
  "sku": "KB-001",
  "brand": { "@type": "Brand", "name": "Example Brand" },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/keyboard",
    "priceCurrency": "USD",
    "price": "149.00",
    "availability": "https://schema.org/InStock"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.7",
    "reviewCount": "127"
  }
}
  • The price in the JSON-LD must match the price on the page. Drift here triggers a Merchant policy violation.
  • aggregateRating requires real reviews on the same page. Pulling ratings from external sources is a violation.
  • Use Product only on product detail pages. Category and listing pages use ItemList instead.

Course: structured education content

Course schema earns course-card rich results in education searches.

{
  "@context": "https://schema.org",
  "@type": "Course",
  "name": "Intro to Postgres",
  "description": "A 4-week intro course covering Postgres fundamentals.",
  "provider": {
    "@type": "Organization",
    "name": "Example University",
    "url": "https://example.com"
  }
}
  • Required: name, description, provider. Recommended: hasCourseInstance with courseMode, startDate, and endDate.
  • For online courses, set courseMode to "online" or "blended".
  • Apply only to actual courses; do not mark a blog series as a course unless it has enrollment and completion semantics.

VideoObject: embedded video metadata

VideoObject schema earns video thumbnails in search results.

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Postgres Backup Tutorial",
  "description": "A 12-minute walkthrough of pg_dump.",
  "thumbnailUrl": "https://example.com/thumb.jpg",
  "uploadDate": "2026-05-14",
  "duration": "PT12M",
  "contentUrl": "https://example.com/video.mp4",
  "embedUrl": "https://example.com/embed/video"
}
  • Required: name, description, thumbnailUrl, uploadDate. Recommended: duration, contentUrl or embedUrl.
  • The video must be embedded or playable on the page. Marking up a link to YouTube on a different domain is a violation.
  • For YouTube embeds, the schema lives on the embedding page; YouTube already declares its own.

DefinedTerm: glossary and term pages

DefinedTerm and DefinedTermSet schema markup glossary pages and individual term definitions. Useful for AI-agent consumption even where rich results do not exist.

{
  "@context": "https://schema.org",
  "@type": "DefinedTerm",
  "name": "Crawl Budget",
  "description": "The number of URLs a search engine will fetch from a site within a window.",
  "inDefinedTermSet": {
    "@type": "DefinedTermSet",
    "name": "SEO Glossary",
    "url": "https://example.com/glossary/"
  }
}
  • Use on dedicated definition pages and glossary entries.
  • Pair with Article schema on the surrounding page if the page also has editorial body content.

Validate with the Rich Results Test and the Schema Validator

Two validators, both required.

  • Google Rich Results Test (https://search.google.com/test/rich-results): confirms eligibility for specific rich result types Google currently surfaces.
  • Schema.org Validator (https://validator.schema.org): confirms the JSON-LD parses and conforms to the vocabulary.

Run both pre-deploy on the top 20 URLs from the sitemap. Failures block the deploy. See the validation rules in structured-data.

Never mark up invisible content

The cardinal rule, repeated. Schema markup must match what a human sees on the page.

  • A FAQPage schema with questions that do not appear in the visible HTML is a Google guideline violation.
  • A Product schema on a page without product details is a violation.
  • A HowTo schema with steps that are not visible is a violation.
  • Recovery from a structured-data manual action takes 2 to 6 weeks; do not risk it for a rich result.

Graph View

Backlinks