JSON LD schema library

Start with the page, then choose a type

A library entry should answer two questions: what real thing is this page about, and what facts does the page actually show? Begin with the page template and visible content, not a list of properties that sounds useful. Then select a Schema.org type that expresses the subject. A news story may be an Article or NewsArticle; an editorial blog post can use BlogPosting; a store location may fit LocalBusiness or a more specific subtype.

The type should describe the page, not the business goal you hope to achieve. Use the Schema.org Article definition for vocabulary relationships, then check Google’s own feature documentation when a search appearance is relevant.

Separate format, vocabulary, and feature eligibility

These are different decisions. JSON LD is a way to encode structured data, commonly in a script element in the page HTML. Schema.org is a shared vocabulary of types and properties. A search engine’s feature documentation sets out the markup and additional requirements for a particular result. Google says it generally recommends JSON LD where a site can implement and maintain it, while also supporting Microdata and RDFa. That preference is about maintainability, not a ranking advantage.

Keep vocabulary validation separate from feature checks: a valid Schema.org item does not automatically qualify for a Google presentation. The Google Search feature gallery is the place to check current documented features and their dedicated guides. For implementation context, see the AEO implementation hub and Rankwox’s schema markup definition.

Keep a starter example small and honest

A library works best when each snippet is small and every field has a source. This illustrative structure is not ready to publish: replace its title, author, and date with information present on the page. Add properties only when they apply and can be kept accurate.

Google’s Article structured data guide lists properties it recommends when applicable, including headline, author, publication or modification date, and representative images; it does not prescribe inventing values to fill out a template.

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Example: Maintaining a content library",
  "author": {
    "@type": "Person",
    "name": "Example Editor"
  },
  "datePublished": "2025-01-15"
}

Document what belongs in each field

Without operating notes, snippets are easy to misuse. For every field, record its meaning, source, format, whether it is required for this use, and when to omit it. For an Article template, `headline` should match the article’s actual title; the author should match the byline; and dates should reflect the real publication or modification event. Do not convert a displayed year into a made up full date.

For Product markup, price and availability must come from the current offer, rather than a reusable placeholder that survives a catalog update. For an Organization entity, use the organization’s actual name and public identity details. If a value is unknown, optional, or not represented on the page, omit it rather than guessing. Rankwox’s JSON LD templates for AEO provide a related starting point; this library’s notes should explain how to adapt any example to the page and CMS at hand.

Avoid the failure modes of copy and paste schema

Many library problems are operational, not syntactic. A universal block may label articles, service pages, and products alike. A template may retain a former author or stale product price after a page changes. A plugin and a hand written block may both emit Organization or Article data, creating duplicate or conflicting descriptions. Teams may also add properties because a competitor appears to use them, without confirming visibility, provenance, or relevance.

Prevent these issues by assigning each template to a named page pattern, defining which component owns each entity, and reviewing the rendered output after changes to a CMS theme or plugin. Google’s general structured data policies require markup to represent page content and warn that misleading, irrelevant, or hidden data can make it ineligible for rich result display. A passing test cannot establish that a claim on the page is true.

Validate the markup and the page it describes

Use complementary checks instead of treating one green test as sign off. The Schema Markup Validator checks markup against Schema.org vocabulary. Google’s Rich Results Test is for checking supported Google rich result features. Neither test replaces a human check that the page tells the same story as its markup. A practical release sequence is:

1. 01Validate the JSON syntax and confirm the intended type and property names.
2. 02Run Schema.org vocabulary validation, then use Google’s Rich Results Test if a documented Google feature applies.
3. 03Compare the rendered page with every material value: identity, title, dates, price, availability, images, or location.
4. 04Inspect the deployed URL and confirm the markup is present, crawlable, and not duplicated by another integration.
5. 05Record errors, warnings, test date, affected template, and the person responsible for follow up.

Make the library maintainable across a site

Treat a schema library like code documentation: give each pattern an owner, intended use, review date, sample URL, test notes, and a changelog. Keep stable organization level data separate from fields generated for each page, so changing a product or article cannot accidentally alter shared identity details. Store snippets in version control or another reviewable source, and test representative URLs after template releases. A staging sample can reveal malformed output, but production checks are still important because plugins, caching, and rendering can change what crawlers receive.

When guidance changes, update the relevant library note and explain what changed instead of silently replacing the snippet. Agencies can pair this process with the schema validation guide and use the AEO implementation hub to connect schema work with answer first content and page architecture.

Set expectations around Google results

Describe markup as a way to make page information explicit and potentially support search features not as a guarantee of rankings, citations, or enhanced display. Google states that valid structured data can make an eligible page able to appear in a rich result, but does not guarantee that it will be shown. The system can choose a different presentation, and eligibility depends on more than syntax: the page must fit the feature and follow applicable content and quality policies.

Report outcomes carefully: distinguish markup validity, feature eligibility, observed impressions, and business impact instead of attributing a traffic change to schema alone. Rankwox’s structured data explainer covers the broader concept. The Rankwox resources hub and AEO templates offer related planning material.