AI Summary: JSON-LD gives machines an explicit description of a page, but it must match the visible main content and stay honest about what is known. Use stable identifiers, accurate types, canonical URLs, and reviewable dates; validate the graph and never promise rich results, ranking, or AI citation.
What JSON-LD is for
JSON-LD is a linked-data representation that can sit in a script type="application/ld+json" element. It lets a publisher describe an article, organization, software application, or other entity using named properties. The useful question is not “which schema has the most fields?” It is “what does this page actually contain, and which facts can be verified?” [1]
Choose properties such as @type, @id, headline, description, url, mainEntityOfPage, datePublished, dateModified, author, and publisher only when they describe the visible page. Keep the canonical URL consistent with the canonical link and Open Graph URL. If a value is not known, omit it rather than inventing a date, author, rating, or relationship.
Align the graph with the page
Google's structured-data guidance says markup should represent the main content and should not be misleading or hidden from users. [1] If the page is a technical article, publish an article graph and make its title, author, date, and subject visible. If the page describes a software product, use a software type only when the page actually explains that product. Do not add Product, Review, FAQ, or HowTo properties only because a template makes them available.
A stable @id such as https://example.com/guide#article can connect the graph to the canonical URL. A citation property may add context, but it should not be the only place a reader can discover an important source. Schema.org's vocabulary is useful for describing relationships; it is not a promise that a search or AI system will consume every property. [2]
Verification checklist
View the rendered page source and parse every JSON-LD block as JSON. Confirm the intended @type, absolute URLs, canonical alignment, and valid ISO date values. Compare headline, description, author, publisher, and dates with the visible page. Then run the relevant validator and record warnings instead of treating a clean parse as proof of eligibility.