Automatic JSON-LD Schema Injection: FAQPage & Organization Structured Data for AI

What Gets Injected

Legible currently supports two schema.org types. FAQPage schemas are built from your indexed FAQ content items — the questions and answers you have added through the Legible dashboard or that were discovered during content crawling. Organization schemas are built from your site settings — company name, URL, logo, and the elevator pitch you have configured for AI systems.

• FAQPage — Up to 10 question–answer pairs, generated from your FAQ content items.
• Organization — Company name, URL, logo, and description from your site settings.
• Both are wrapped in standard schema.org JSON-LD format with @context and @type.

How It Works — Proxy Mode (Cloudflare)

For sites using Cloudflare proxy mode, the Worker uses HTMLRewriter to inject JSON-LD script blocks into the HTML head before it reaches the browser or crawler. This is server-side, so all crawlers — including those that do not execute JavaScript — will see the structured data.

FAQ data is cached in the Worker's KV store and refreshed during content syncs. The Organization schema is built from Worker environment variables set by the dashboard.

How It Works — JavaScript Snippet

For proxy-free sites, the discover.js snippet fetches schema data from the Legible public API and injects it client-side. The snippet checks for existing JSON-LD blocks before injecting to prevent duplicates.

As with discovery tags, be aware that most AI crawlers do not execute JavaScript. For full coverage, prefer Cloudflare proxy mode or add the JSON-LD manually to your templates.

Existing Schema Detection

Many sites already have JSON-LD structured data — either from their CMS theme, an SEO plugin, or manual additions. Legible detects existing schemas before injecting.

When detection is enabled (the default), the system scans the page's HTML for existing script type="application/ld+json" blocks. If a FAQPage or Organization schema is already present, that type is skipped. This prevents duplicate or conflicting structured data.

• Detection works with both flat JSON-LD and @graph arrays.
• Detection is enabled by default and can be turned off in the dashboard.
• If you disable detection, Legible will always inject — useful if you want to replace an incomplete schema.

Enabling Schema Injection

Navigate to your site's Settings → Discovery tab in the Legible dashboard. Below the HTML Discovery Tags section, you will find the Structured Data (JSON-LD) section. Enable the master toggle, then configure which schema types to inject.

• Toggle FAQPage on or off. Requires at least one FAQ content item to have any effect.
• Toggle Organization on or off. Fill in company details or leave blank to use your site's display name and domain.
• Toggle existing schema detection on or off.
• Save your settings. For Cloudflare proxy sites, changes propagate to the Worker within seconds.

Organization Schema Details

The Organization schema uses these fields: name (from Organization Name or site display name), url (from Organization URL or site domain), logo (from Logo URL if provided), and description (from your site elevator pitch).

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Acme Inc",
  "url": "https://acme.com",
  "logo": "https://acme.com/logo.png",
  "description": "We help businesses do great things."
}

FAQPage Schema Details

The FAQPage schema is auto-generated from your FAQ content items. Each item's title becomes the question, and the excerpt or body text (stripped of Markdown formatting) becomes the answer. Up to 10 items are included, sorted by creation date.

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is GEO?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Generative Engine Optimization is the practice of making your content..."
      }
    }
  ]
}

Troubleshooting

• No FAQ schema appearing: Check that you have FAQ content items in Legible (Content → FAQ tab) and that they are marked as included.
• No Organization schema appearing: Verify your site has either a display name or an Organization Name set in the schema settings.
• Duplicate schemas: Enable the "Detect existing schemas" toggle. If you still see duplicates, your CMS may be injecting schemas after the page loads.
• Schema validation errors: Use Google's Rich Results Test (search.google.com/test/rich-results) to validate the injected JSON-LD. Legible follows the schema.org specification strictly.
• Changes not visible: For Cloudflare sites, allow a few seconds for Worker env propagation. For JS snippet sites, clear your browser cache or open an incognito window.