Quick answer
Use JSON-LD to describe facts already present on the page: an article's title and author, a visible breadcrumb trail, or a product's documented identity. Choose a supported type appropriate to the content, keep dates and URLs accurate, and serialize safely into the HTML. Valid markup does not guarantee a rich result or a ranking improvement.
Do not add fabricated ratings, reviews, prices, availability, or expertise claims to fill optional fields. A browser extension listing can describe a SoftwareApplication without proving that it qualifies for a particular Google search enhancement. Distinguish general schema vocabulary from Google's feature-specific requirements.
Practical implementation steps
Match entities to visible content
Inventory the page's real entities and select a small graph: author or organization, page or article, and breadcrumbs when present. Use stable IDs to refer to the same entity across routes. Avoid generating multiple contradictory objects for one article from separate components. Keep the graph based on the same content record used for the heading and body.
Preserve dates and language identity
datePublished describes original publication, while dateModified should reflect meaningful changes. Do not reset publication dates to make old content appear new. A translated article should describe its visible language and canonical URL while inheriting appropriate source lifecycle. Ensure author URLs and referenced images are reachable and identify the intended entity rather than a random home-page link.
Serialize as data
JSON.stringify creates JSON, but raw strings containing a closing script sequence can still affect the surrounding HTML. Escape less-than characters in the serialized output before inserting it in a script element. Validate user-controlled fields and allowed URLs independently. The repository's JsonLd component already applies this escaping; that is a concrete implementation example, not a full guarantee against unsafe values elsewhere.
Validate syntax and feature eligibility
Inspect the rendered source and parse the emitted JSON. Use Google's Rich Results Test for supported features and the corresponding documentation for required and recommended properties. A syntax pass cannot prove that a claim is true or visible. After deployment, check Search Console reports for observed issues without assuming every valid page will receive enhanced presentation.
Implementation example
This reusable component follows the Next.js serialization pattern. Keep the JSON-LD object in server-controlled content and validate any externally supplied fields before passing them. The code matches the repository's essential escaping behavior.
export function JsonLd({ data }: { data: Record<string, unknown> }) {
const serialized = JSON.stringify(data).replace(/</g, "\u003c");
return (
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: serialized }}
/>
);
}
For an article, construct headline, author, URL, dates, language, and representative images from verified content. Leave unknown properties out. If a review or rating is not genuinely supported by the page's content and applicable feature policy, omit it rather than inventing a plausible number.
Tradeoffs and alternatives
A centralized helper reduces serialization mistakes and inconsistent author references, while page-level construction preserves content-specific meaning. Avoid a universal graph that assigns every schema type to every route. A modest accurate graph is easier to maintain than a large graph filled with unsupported marketing claims.
Common mistakes
- Marking up claims absent from visible content.
- Inventing aggregate ratings or customer reviews.
- Treating schema validity as rich-result eligibility.
- Resetting original publication dates on every build.
- Inserting JSON without safe HTML serialization.
Production checklist
- Entity types fit the actual page.
- Properties come from verified visible content.
- URLs, images, dates, and language are consistent.
- Less-than characters are escaped in serialized JSON.
- Syntax and supported feature rules are checked separately.
- Search appearance claims match observed evidence.
FAQ
Should every page include FAQ markup?
Only describe genuine visible content and check current eligibility for the intended search feature. Adding an FAQ section or JSON-LD does not create an automatic rich-result entitlement.
Can structured data compensate for weak articles?
No. It describes the content; it does not supply missing explanations, examples, or evidence. Complete editorial work independently.
Conclusion
Describe a small set of real entities, serialize safely, and validate the intended feature. Keep unsupported claims out of the graph and assess actual search behavior after deployment rather than promising results from markup alone.
Primary sources
Related guides and examples
Need this implemented in a real product?
Explore relevant product case studies or share the context for a web application, Chrome extension, API, or SaaS build.