Schema Markup Playbook (JSON-LD)

Deploy valid JSON-LD structured data — Organization, Article, Product, FAQ, LocalBusiness, and Person templates with validation steps and common fixes.

This page is the operator playbook — use the templates below today. Interactive UI lands next. Check your AI search readiness meanwhile.

What this is

Schema markup (structured data) tells search engines and AI systems what your page represents — a company, article, product, FAQ, or local business — using a shared vocabulary (schema.org).

JSON-LD is the recommended format: a <script type="application/ld+json"> block in your HTML, usually built server-side so it ships in the first response.

An interactive generator UI is shipping on this page later. Today, this playbook is the tool: copy the JSON-LD template for your page type, fill placeholders, validate, and deploy.

When to use it

Launching a new site and need baseline Organization + WebSite entity signals.
Publishing articles, tools, or products that qualify for rich results (FAQ, product, article enhancements).
Local businesses needing NAP (name, address, phone) consistency in machine-readable form.
Fixing Search Console "structured data" errors after a template change.
Improving AI citation accuracy — clear entity graphs reduce ambiguous brand mentions.

Step-by-step deployment

Pick the primary type for the page (one main entity; supporting nodes go in @graph).
Copy the matching template below and replace all {placeholders}.
Use absolute URLs — https://yourdomain.com/path, not relative paths.
Inject server-side (Next.js JsonLd component, layout, or CMS custom field) — avoid client-only rendering for SEO-critical schema.
Validate:
- Google Rich Results Test
- Schema Markup Validator
Deploy and request indexing in Search Console for high-value URLs.
Monitor Search Console → Enhancements for regressions after deploys.

Organization (sitewide baseline)

Use on homepage or global layout. Pair with WebSite for sitelinks search box eligibility.

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://yourdomain.com/#organization",
      "name": "Your Company Name",
      "url": "https://yourdomain.com",
      "logo": {
        "@type": "ImageObject",
        "url": "https://yourdomain.com/logo.png",
        "width": 512,
        "height": 512
      },
      "description": "One-sentence company description aligned with meta description.",
      "email": "hello@yourdomain.com",
      "sameAs": [
        "https://linkedin.com/company/your-company",
        "https://github.com/your-org"
      ]
    },
    {
      "@type": "WebSite",
      "@id": "https://yourdomain.com/#website",
      "url": "https://yourdomain.com",
      "name": "Your Company Name",
      "publisher": { "@id": "https://yourdomain.com/#organization" },
      "potentialAction": {
        "@type": "SearchAction",
        "target": "https://yourdomain.com/search?q={search_term_string}",
        "query-input": "required name=search_term_string"
      }
    }
  ]
}

Remove potentialAction if your site has no search route — invalid SearchAction causes warnings.

LocalBusiness

For location-based services. Match NAP exactly to Google Business Profile and footer.

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "@id": "https://yourdomain.com/#localbusiness",
  "name": "Your Business Name",
  "image": "https://yourdomain.com/storefront.jpg",
  "url": "https://yourdomain.com",
  "telephone": "+1-555-0100",
  "priceRange": "$$",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "Austin",
    "addressRegion": "TX",
    "postalCode": "78701",
    "addressCountry": "US"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": 30.2672,
    "longitude": -97.7431
  },
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "09:00",
      "closes": "17:00"
    }
  ]
}

Article (blog posts and guides)

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Article Title — Match Visible H1",
  "description": "Meta description or excerpt.",
  "image": ["https://yourdomain.com/content/blog/your-slug/hero.webp"],
  "datePublished": "2026-07-15",
  "dateModified": "2026-07-15",
  "author": {
    "@type": "Person",
    "name": "Author Full Name",
    "url": "https://yourdomain.com/about#author"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Your Company Name",
    "logo": {
      "@type": "ImageObject",
      "url": "https://yourdomain.com/logo.png"
    }
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://yourdomain.com/blog/your-slug"
  }
}

Product (SaaS or physical)

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product Name",
  "description": "What the product does in one or two sentences.",
  "image": "https://yourdomain.com/product-image.jpg",
  "brand": {
    "@type": "Brand",
    "name": "Your Company Name"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://yourdomain.com/pricing",
    "priceCurrency": "USD",
    "price": "49.00",
    "availability": "https://schema.org/InStock",
    "priceValidUntil": "2026-12-31"
  }
}

For subscription SaaS, some teams use SoftwareApplication instead — pick the type that best matches how you sell.

FAQPage

Only mark up FAQs visible on the page. Hidden FAQ schema violates Google guidelines.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is JSON-LD schema markup?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "JSON-LD is a script block that describes page entities in a format search engines can parse without affecting visible layout."
      }
    },
    {
      "@type": "Question",
      "name": "Does schema markup guarantee rich results?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "No. Valid schema is eligibility, not a promise. Google decides whether to show enhanced results based on quality and policy."
      }
    }
  ]
}

Person (author or founder pages)

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Jane Operator",
  "url": "https://yourdomain.com/about/jane",
  "jobTitle": "Head of Automation",
  "worksFor": {
    "@type": "Organization",
    "name": "Your Company Name",
    "url": "https://yourdomain.com"
  },
  "sameAs": [
    "https://linkedin.com/in/jane-operator"
  ]
}

SoftwareApplication (free tools)

Ideal for /tools/* pages on this site.

{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Robots.txt Playbook",
  "applicationCategory": "BusinessApplication",
  "operatingSystem": "Web",
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "USD"
  },
  "description": "Operator guide with copy-paste robots.txt templates for AI crawlers and search bots.",
  "url": "https://yourdomain.com/tools/robots-txt-generator"
}

Pre-flight checklist

JSON parses without trailing commas or comments (strict JSON).
@id and url fields use HTTPS absolute URLs.
dateModified updates when content changes materially.
Images meet minimum size guidelines (often 1200px wide for Article).
FAQ questions match visible on-page copy word-for-word or close paraphrase.
No more than one conflicting @type for the same entity on one page.
Validated in Rich Results Test before production deploy.
Organization schema matches llms.txt brand name and description.

Common mistakes

Client-only injection. Schema added via useEffect may not appear in crawlers' first pass. Render in Server Components or static HTML.

Marking up invisible content. FAQ, review, and product schema must reflect what users see. Penalties and rich-result loss follow abuse.

Stale dates. dateModified left at launch date on heavily edited articles sends mixed freshness signals.

Relative URLs in @id. Use canonical absolute URLs consistent with <link rel="canonical">.

Schema spam. Listing 50 products on a homepage with Product schema when only three show is worse than no schema.

Duplicate Organization blocks. One @graph per page beats five separate Organization scripts fighting each other.

Next steps

Structured data works best alongside the rest of your GEO stack:

Meta description playbook — human-facing snippets aligned with schema description.
llms.txt playbook — narrative site map for AI citation.
Robots.txt playbook — ensure crawlers can fetch your JSON-LD.
Free operator guides — content worth marking up with Article schema.
GEO readiness scan — holistic view of AI search visibility.

Explore more on the tools hub.

Back home Free GEO Scan Free Library