Structured data for every page type

Paste into any coding agent: Claude Code, Cursor, Codex, Copilot, Windsurf or Cline.

# Structured data for every page type

Structured data tells search engines and AI systems what each page of the production site is about in a form they do not have to guess at. Add correct JSON-LD for every page type from shared helpers, built from the same data the page renders, so it always matches what visitors see.

Site: not given. Find the production URL in the project config, or ask me.

## Ground rules

1. Read before you write. Explore the parts of the codebase this job touches and tell me what is already in place.
2. Plan, then stop. Give me a numbered plan: what you will change, in which files, and why. Wait for my approval before editing anything.
3. Fix things at their source (the shared layout, the config, the generator), not with one-off patches page by page.
4. Keep the project's conventions: its framework APIs, file layout, naming and code style. Add no new dependency without asking.
5. Where something is already done well, say so and leave it alone.

## You will not

- Edit `.env` files, secrets or API keys, or print their values.
- Deploy, push, merge or publish anything.
- Delete data, or run migrations or scripts against a production database.
- Add tracking, third-party scripts or links to any site I did not ask for.
- Change copy, design or behaviour that this job does not need.
- Add ratings, reviews or prices that are not real and visible on the page.

## Your stack

- Framework: Work out the framework, router and build output from the project files (package.json, lockfiles, framework config) before planning, and say which you found.
- Host: Work out where the site is hosted from the config files (vercel.json, netlify.toml, wrangler config, Dockerfile, fly.toml) and say which you found.

## Steps

### 1. Inventory page types and existing markup

List each page type (home, pricing, product or feature, blog post, docs, about, profile) and any JSON-LD already present. Note markup that is wrong: types that do not fit, fields that do not match the page, or ratings that are not from real reviews.

### 2. Site-wide entities

On the homepage (or in the root layout), a `@graph` with an `Organization` (name, url, logo, `sameAs` with official profiles only) and a `WebSite` (name, url, and a `SearchAction` only if the site has a working search URL). Give them stable `@id`s like `https://site/#organization` so other pages can reference them.

### 3. Per page type

- Product or app pages: `SoftwareApplication` (or `Product` for physical goods) with name, description, `applicationCategory`, `operatingSystem`, and `offers` with real prices. Add `aggregateRating` only if it comes from real, visible reviews.
- Blog posts and guides: `BlogPosting` or `Article` with headline, `datePublished`, `dateModified`, an `author` that is a real `Person`, and `publisher` pointing at the Organization `@id`.
- Every page below the top level: `BreadcrumbList` matching the visible breadcrumb.
- Pages with a visible FAQ: `FAQPage` with the same questions and answers.
- Profile or team pages: `Person` or `ProfilePage`.

### 4. Build it from data, safely

Generate JSON-LD in one helper per type, from the page's data. Escape it safely when inlining (a `</script>` inside a string must not break out). One `<script type="application/ld+json">` per page with a `@graph` is cleaner than many.

## Done means

- [ ] Organization and WebSite markup exist once, with stable @ids.
- [ ] Every page type has the right JSON-LD type, built from its own data.
- [ ] Every value in the markup is visible on the page; no invented ratings or reviews.
- [ ] The markup is generated by shared helpers and escaped safely.
- [ ] Each page type validates without errors.

## Report back

When you finish, give me:

- what you changed, file by file;
- anything you skipped, and why;
- anything I must do by hand (DNS records, dashboards, accounts, deploys);
- how to check each change on the live site.