Structured Data and Visible Content Parity

Definition

When you want search engines and answer engines to cite your page’s FAQ, pricing, or product descriptions, machine-readable markup (structured data) must match what people can actually read in HTML.

Structured data is JSON-LD and similar formats that describe page meaning using the schema.org vocabulary. Visible content is body copy, headings, and FAQ rendered in the browser so users (or crawlers via DOM/text) can see it. Parity means every claim in markup (question, answer, price) has corresponding text on screen. Putting Q&A only in FAQPage markup with nothing on screen is the opposite of this idea.

Why It Matters

Without structured data, machines guess unstable relationships for price and FAQ. Conversely, rich markup with a thin visible page is treated like hidden markup or spam under search policies, and users cannot find cited answers on the page. Even with login walls or preview-lock UI, put real H1, description, and FAQ in the overlay to secure visible text, and derive that text and JSON-LD from the same data source.

How It Works

1. Put FAQ, plans, and product copy in one array/module such as faqContent.ts.
2. UI components map that array to draw accordions or lists.
3. A JSON-LD builder uses the same array to build FAQPage / Offer nodes.
4. Tie conditional rendering (e.g. show FAQ only for anonymous users) and graph inclusion with the same condition — remove the FAQPage node when FAQ disappears from the screen.
5. Before deploy, compare application/ld+json strings in HTML source with body text.

// Pseudocode: single source
const FAQS = [{ q: "…", a: "…" }];
function FaqUi() {
  return FAQS.map((f) => <details key={f.q}>…</details>);
}
function faqJsonLd() {
  return {
    "@type": "FAQPage",
    mainEntity: FAQS.map((f) => ({
      "@type": "Question",
      name: f.q,
      acceptedAnswer: { "@type": "Answer", text: f.a },
    })),
  };
}

Practical Application

• Public home/landing: even with lock/blur UI, put H1, short description, and FAQ in the overlay.
• Pricing pages: derive Offer from actual pricing-table functions rather than hard-coded numbers to prevent drift from the UI.
• i18n: use locale-specific FAQ arrays, and each locale page’s JSON-LD uses that locale’s array.
• Prefer putting content on the canonical home rather than splitting authority across a separate /landing.

Trade-offs

When Not to Use

• Putting internal FAQ in JSON-LD only, never exposed on screen.
• Faking “visible” with CSS display:none or 0px font size.
• Putting login-only answers in anonymous-page FAQPage (condition mismatch).

Common Mistakes

• Removing FAQ from the UI in a refactor but leaving JSON-LD unchanged.
• Misdiagnosing grep hreflang returning 0 as a bug — confusing with React outputting hrefLang casing (separate issue, but verify with case-insensitive source search).
• Trusting mock E2E only and missing real-environment thin content or 401 redirects.

Related Concepts

• json-ld-structured-data — Pattern for injecting JSON-LD script on the server
• single-source-of-truth-content-metadata — Single source for meta and body
• auth-resolution-gated-data-fetching — Gate so public home does not bounce on 401