Skip to content
Skills Library
Marketing & content · Building & coding

structured-data

/structured-data

Write JSON-LD structured data that is valid, matches what the page shows, and earns the rich results Google still supports. Use when adding or fixing schema markup for a page type (Organization and WebSite, Breadcrumb, Article, Product with Offer, Review and AggregateRating, Event, JobPosting, SoftwareApplication, VideoObject, Dataset, ProfilePage), deciding whether a type still earns a rich result after the 2025 and 2026 retirements, joining entities with @id, or validating built HTML against the Rich Results Test and the Schema Markup Validator. Checks built output with scripts/jsonld_check.

Repository
ai-skill-ai ↗
Licence
MIT
Last repository change
31.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
2
Deprecation

No signals detected. Repository changed on 31.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/jsonld_check.py

What it does and when to use it

Write JSON-LD structured data that is valid, matches what the page shows, and earns the rich results Google still supports. Use when adding or fixing schema markup for a page type (Organization and WebSite, Breadcrumb, Article, Product with Offer, Review and AggregateRating, Event, JobPosting, SoftwareApplication, VideoObject, Dataset, ProfilePage), deciding whether a type still earns a rich result after the 2025 and 2026 retirements, joining entities with @id, or validating built HTML against the Rich Results Test and the Schema Markup Validator. Checks built output with scripts/jsonld_check.

Original author description

Write JSON-LD structured data that is valid, matches what the page shows, and earns the rich results Google still supports. Use when adding or fixing schema markup for a page type (Organization and WebSite, Breadcrumb, Article, Product with Offer, Review and AggregateRating, Event, JobPosting, SoftwareApplication, VideoObject, Dataset, ProfilePage), deciding whether a type still earns a rich result after the 2025 and 2026 retirements, joining entities with @id, or validating built HTML against the Rich Results Test and the Schema Markup Validator. Checks built output with scripts/jsonld_check.

How it works

  1. When to use and when to stay off
  2. Non-negotiables
  3. Procedure
  4. Self-audit
  5. What this cannot do
Original SKILL.md headings · 149 lines, 1,985 words
SKILL.md preview
---
name: structured-data
description: Write JSON-LD structured data that is valid, matches what the page shows, and earns the rich results Google still supports. Use when adding or fixing schema markup for a page type (Organization and WebSite, Breadcrumb, Article, Product with Offer, Review and AggregateRating, Event, JobPosting, SoftwareApplication, VideoObject, Dataset, ProfilePage), deciding whether a type still earns a rich result after the 2025 and 2026 retirements, joining entities with @id, or validating built HTML against the Rich Results Test and the Schema Markup Validator. Checks built output with scripts/jsonld_check.py before claiming eligibility. Triggers on JSON-LD, schema markup, structured data, rich results, rich snippet, Product schema, Review stars, breadcrumb markup, JobPosting, Rich Results Test, schema validator, why is my rich result gone. For a LocalBusiness block use local-seo. For rendering and the index policy use seo-technical. For a parse error in an audit use seo-audit. For AI citations use ai-search-visibility.
license: MIT
metadata:
  version: 1.0.1
  suite: ai-skill
---

# JSON-LD structured data

The common failure is markup that validates but earns nothing, or worse, markup that contradicts the
page. An agent copies a Product block with a 4.8 star rating onto a page that shows no reviews, marks
up a price the visitor never sees, or ships schema for a type Google retired a year ago and then waits
for a rich result that will never come. Structured data does not raise rankings on its own and it never
invents eligibility: it describes what is already on the page so Google can draw a richer result, and
only for the handful of types Google still supports. This skill writes markup that matches the visible
page, joins entities into one graph, and gets verified against the built HTML before anyone claims a
result.

## When to use and when to stay off

Run when the task is the JSON-LD itself: choosing the type for a page, writing the block, joining
Organization, WebSite, Product, Article or Person nodes with `@id`, deciding whether a type still
produces a rich result, or validating markup against the built output and the two official testers.

Stay off, and route instead, when:

- The block is `LocalBusiness` for a shop, clinic or branch. Use `local-seo`: it decides the name, address, hours and category, and hands the markup here only to write and validate.
- The question is rendering mode, canonicals, the sitemap, or the one index-policy function that decides indexability. Use `seo-technical`. Markup goes in server-rendered HTML, which that skill owns.
- An audit reported a JSON-LD parse error among many issues. Use `seo-audit` for the catalogue; come here for the fix and the per-type check.
- The work is keywords, briefs or page copy. Use `seo-content`.
- The goal is being read or cited by AI answer engines. Use `ai-search-visibility`: structured data helps machines parse a page but is not required for AI features.
- The task is building the pages themselves. Use `website-build`, which calls this skill per page type.

The user says "stop", "I've decided", or "just execute": comply at once and stay off for the rest of
the session unless asked again.

## Non-negotiables

These override everything else in this file.

1. The markup matches what the visitor sees. Every marked-up name, price, rating, date and availability appears in the rendered page body. Google's general guidelines state content in structured data must be visible to users, and marking up hidden or absent content is a quality violation that can cost all rich results for the site. `scripts/jsonld_check.py` flags marked-up text missing from the visible body; do not ship past that finding.
2. No markup for a type Google no longer shows. Check the type against the current Search gallery and the retirement list in step 1 before writing it. A retired type still validates on Schema.org, so validation alone never proves eligibility.
3. One entity graph, joined by `@id`. A page has one `Organization` and one `WebSite` referenced by `@id`, not a fresh copy inside every block. Duplicate conflicting nodes make Google pick one or ignore the set.
4. Every self-serving review follows Google's review-snippet rules. The thing being rated is a type Google allows review snippets for, the rating is real and collected from real users, and a self-serving review (a site rating its own products or the business itself) is not eligible for a star snippet. Do not fabricate `aggregateRating`.
5. JSON-LD lives in the server-rendered HTML. The block is in the HTML Google first fetches, not injected by a later client script, because a crawler may not run that script. When injecting into HTML, escape `<` as `\u003c` so the markup cannot break out of the script tag.
6. Every eligibility claim carries the date it was checked, or an `ASSUMPTION:` label with its risk. Google changes rich result support often (FAQ went from broad, to government and health only in August 2023, to gone in May 2026), so an undated "this earns a rich result" is worthless.

## Procedure

Work the type decision first, then the markup, then the build check and the official testers in order.

### Step 1, check what Google still supports today

Google retires rich result types regularly, and the Schema.org vocabulary keeps the retired types
valid, so a block can pass every validator and still produce nothing. Confirm the type against the
current Search gallery before writing it.

Supported and producing rich results, verified against the Google Search gallery on 29 October 2026:
Article, Breadcrumb, Dataset, Event, Image metadata, Job posting, Local business, Organization,
Product (product snippet and merchant listing), Profile page, Q and A, Recipe, Review snippet, Software
app, Speakable, Subscription and paywalled content, Vacation rental, Video, Movie carousel, Math
solver, Discussion forum, Education Q and A, Employer aggregate rating. Carousel and the site-name
signal from Organization and WebSite also still apply.

Retired, so do not expect a rich result (verify before relying on this list):

- FAQ: rich results stopped appearing 7 May 2026; the search appearance, the rich result report and Rich Results Test support were dropped in June 2026, and the Search Console API support in August 2026 (Google FAQPage documentation, verified 29 October 2026). FAQPage stays valid Schema.org and Google still parses it, but there is no SERP feature.
- HowTo: rich results deprecated in 2023 (desktop 13 September 2023, mobile earlier) and gone since (Google HowTo changes blog, 2023).
- Book actions, Course info, Claim review, Estimated salary, Learning video, Special announcement, Vehicle listing: all seven retired in the June 2025 simplification (announced 12 June 2025; Search Console reporting removed 9 September 2025; Google "Simplifying the search results page" blog, verified 29 October 2026).

Trap to watch: the gallery navigation still lists some retired pages (Book actions, Course list, Fact
check) as documentation, which does not mean the rich result still shows. Trust the retirement
announcements, not the nav tree. The script's embedded type table carries the same retirement notes and
a source date; re-verify it against the gallery before a clean run on a type that matters.

Schema.org itself is at version 30.1, published 16 September 2026 (schema.org release listing, verified
29 October 2026). Use `https://schema.org` as the `@context`.

### Step 2, pick the type per page and read what it shows

Match the type to the page, then read the rendered page so the markup can only describe what is there.

- Home and every page: one `Organization` plus one `WebSite`, joined by `@id`. This feeds the site-name and logo signals. Put the real legal name, the canonical home URL, an absolute logo URL, and `sameAs` links to the real profiles.
- Any page below the home page: `BreadcrumbList`, one `itemListElement` per level, in the order shown in the visible breadcrumb trail.
- Article, news or blog post: `Article`, `NewsArticle` or `BlogPosting` with the real headline, author, publish and modified dates, and an absolute image URL.
- Product page: `Product` with `name`, an `offers` block carrying `price` and `priceCurrency`, and `availability`. A merchant listing (a page selling the product) adds shipping and return detail; a product snippet (a page about the product) can carry review and rating. Never a price the page does not show.
- A review or a rated item: `Review` with a real `reviewRating` and `author`, or `AggregateRating` with a real `ratingValue` and a `reviewCount` or `ratingCount`. Honour non-negotiable 4.
- `Event`, `JobPosting`, `SoftwareApplication`, `VideoObject`, `Dataset`, `ProfilePage`: one node each, every required property from the script's table present, the recommended ones added where the page has the data.

### Step 3, write one joined graph

Put the blocks in a single `<script type="application/ld+json">` using `@graph`, with shared entities
referenced by `@id` rather than repeated. A Product that cites its seller points at the one
`Organization` node by `@id`. Keep absolute URLs for every `url`, `logo`, `image`, `contentUrl`,
`thumbnailUrl` and `sameAs`, because Google resolves these as absolute. Escape `<` as `\u003c` on the
way into the HTML.

### Step 4, place it in server-rendered HTML

The block ships in the HTML the server returns, per non-negotiable 5 and `seo-technical`'s rendering
rules. For a framework that renders on the client, move the JSON-LD into the server-rendered head or
body, or prerender the route. Confirm by fetching the built page and finding the block in the raw HTML,
not only in the browser after scripts run.

### Step 5, validate against the built output

Run the script against the built HTML or the live URL before claiming anything:

```
py -3 scripts/jsonld_check.py ./dist
py -3 scripts/jsonld_check.py https://example.com/product --url
py -3 scripts/jsonld_check.py page.html --min-severity medium --json
```

It pulls every JSON-LD block (following `@graph` and arrays), parses it, and reports parse errors,
retired types, missing required properties (high), missing recommended properties (low), a relative URL
where Google wants an absolute one, an `Offer` price with no `priceCurrency`, an `aggregateRating` with
no count, and marked-up `name`, `headline` or `description` text absent from the visible body. It exits
0 when nothing sits at or above the threshold, 1 when something does, 2 on a usage error. Default
threshold is low, so `--min-severity medium` hides the recommended-property notes while still failing on
real breakage. Stdlib only; set `PYTHONPYCACHEPREFIX` to a scratch folder outside the repository
first. The script is a first pass, not the final word: finish with the two official testers.

### Step 6, confirm with the official testers and watch Search Console

- Rich Results Test (search.google.com/test/rich-results): confirms a specific page is eligible for a Google rich result and shows what it detected. Use it for the final eligibility check.
- Schema Markup Validator (validator.schema.org): checks Schema.org validity without the Google eligibility lens. Use it when the type is not one Google renders but the markup still has to be correct.
- After launch, read the per-type rich-result reports in Search Console. They show valid items, warnings and errors on pages Google actually crawled, which is the only view of how the live site is read. Record the date of each check.

## Self-audit

- Every marked-up name, price, rating, date and availability appears in the visible page body, confirmed by a `jsonld_check.py` run whose output is shown.
- No block uses a type retired by the 2023, June 2025 or May 2026 changes, and each kept type was checked against the gallery with the date recorded.
- The page has one `Organization` and one `WebSite` node, referenced elsewhere by `@id`, not copied.
- No `aggregateRating` or `Review` is fabricated, and no self-serving review is marked up for a star snippet it cannot earn.
- The JSON-LD is in the server-rendered HTML, found by fetching the built page, with `<` escaped as `\u003c`.
- Every `url`, `logo`, `image`, `contentUrl`, `thumbnailUrl` and `sameAs` is an absolute URL.
- `scripts/jsonld_check.py` was run against the built output and every high finding is fixed; the run and its date are recorded.
- The Rich Results Test or the Schema Markup Validator was run on a sample page, and the result and date are recorded.

## What this cannot do

It cannot promise a rich result. Eligibility is Google's decision, made per page and per query, and even
a perfect block can go unshown. This skill removes the reasons a result is withheld; it never claims the
result will appear.

It cannot see how Google renders or indexes a page. The script reads the HTML the server ships and the
testers read one page at a time; the live view across the site is the Search Console rich-result report,
which the user has to open.

It cannot decide whether a page may lawfully publish what it marks up. For a regulated field (finance,
health, legal), or for personal data in `Person` or `ProfilePage` markup, ask a lawyer qualified in that
field and country: "Does publishing this data as machine-readable structured data need consent, a
disclaimer, or a licence here, given it will be crawled and reused?"
Files in this package (2)
  • SKILL.md 13 KB
  • scripts/jsonld_check.py 19 KB

Versions

RepositoryScoreLicence
This page · devpilotX/ai-skill-ai100MIT
adobe/skills100Apache-2.0
sharabarinillia/SEO-GEO-Vercel-Playbook-Skill100MIT
thedaviddias/front-end-checklist100MIT

Database snapshot: 13.11.2026 · package version 0766a88e613d (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 95schema-markup
    When the user wants to add or optimize structured data (Schema.org, JSON-LD). Also use when the user mentions "schema," "structured data," "JSON-LD," "rich results," "rich snippets," "Google rich snippets," "featured snippet schema," "add schema to page," "missing structured…
  • 95schema-markup
    When the user wants to add or optimize structured data (Schema.org, JSON-LD). Also use when the user mentions "schema," "structured data," "JSON-LD," "rich results," "rich snippets," "Google rich snippets," "featured snippet schema," "add schema to page," "missing structured…
  • 95schema-markup
    When the user wants to add or optimize structured data (Schema.org, JSON-LD). Also use when the user mentions "schema," "structured data," "JSON-LD," "rich results," "rich snippets," "Google rich snippets," "featured snippet schema," "add schema to page," "missing structured…
  • 100schema
    Lint and plan structured data (JSON-LD) for a page: checks Google's required properties, flags Software application markup without aggregateRating or review, notes that FAQ rich results ended on 2026-05-07 and that HowTo is not in Google's gallery, picks types per page type,…
  • 100seo-schema-markup
    Get valid Schema.org JSON-LD that still earns surfaces in 2026. Input: a page and its type (article, product, local business, person, and so on). Output: ready-to-adapt JSON-LD (Organization with sameAs, Article, Product, Offer, AggregateRating, LocalBusiness, BreadcrumbList,…
  • 100schema-markup
    Adds, repairs and verifies schema.org structured data (JSON-LD) on a website, and says honestly which Google rich results the markup can still earn. Use when a user asks to "add schema markup", "add structured data", "write JSON-LD for this page", "fix structured data errors in…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.