Add JSON-LD to your app/site

Add JSON-LD to a Site

JSON-LD (JSON Linked Data) is structured data that lives in a `

- `@context: "https://schema.org"` tells crawlers which vocabulary is in use. Schema.org defines every valid `@type` and property.
- `@graph` is an array of nodes describing the page and its entities.
- Each node has an `@type` (what it is), an `@id` (unique identifier), and properties.

**The `@id` convention is load-bearing.** IDs are URLs with a hash fragment that uniquely identifies the node — e.g. `https://example.com/#website`, `https://example.com/#person`, `https://example.com/blog/post-slug/#blogposting`. Two things rely on this:

1. **Within a page**, nodes reference each other by `@id` to build relationships: a `BlogPosting` says `"author": { "@id": "https://example.com/#person" }`, and the `Person` node with that `@id` is in the same `@graph`.
2. **Across pages**, crawlers (Googlebot and friends) merge properties of nodes that share an `@id`. So the `Person` node only needs full detail on one canonical page — other pages can reference `https://example.com/#person` and the crawler will stitch the data together.

LLM scrapers usually read one page at a time and don't merge, so important nodes (especially `Person`) should be fully described on every page where they matter, not just the canonical one. The slim/full distinction below addresses this.

## Workflow

When the user asks for JSON-LD help, work through these steps:

### 1. Figure out what kind of site and what pages exist

Ask (or infer from context) what type of site it is — personal site, blog, portfolio, business site — and what pages need JSON-LD. Common page types:

- **Root / home page** — usually doubles as an "about me" page on personal sites
- **About page** — if separate from root
- **Blog index** — lists all posts
- **Blog post** — individual article
- **Project / software showcase** — page describing one or more apps, libraries, games
- **Collection page** — any page that is primarily a list (e.g. `/links/`, `/elsewhere/`, `/projects/`)

Also confirm the site's canonical domain and whether the user has profiles elsewhere (GitHub, LinkedIn, Mastodon, etc.) — those go in `Person.sameAs` and meaningfully help disambiguation.

### 2. Decide which nodes each page needs

Use this matrix as a starting point.

| Page type        | Nodes to include                                                              |
|------------------|-------------------------------------------------------------------------------|
| Root (about-me)  | `WebSite` (full), `Person`, `ProfilePage`                                     |
| About (separate) | `WebSite` (slim), `Person`, `ProfilePage`, `BreadcrumbList`                   |
| Blog index       | `WebSite` (slim), `Person`, `WebPage`, `Blog`, `BreadcrumbList`               |
| Blog post        | `WebSite` (slim), `Person`, `WebPage`, `BlogPosting`, `BreadcrumbList`        |
| Project showcase | `WebSite` (slim), `Person`, `WebPage`, `SoftwareApplication`(s), `BreadcrumbList` |
| Collection page  | `WebSite` (slim), `Person`, `CollectionPage`, `BreadcrumbList`                |

Two rules underlie this matrix:

- **`Person` goes on every page.** Google uses it as a content quality signal, and LLM crawlers use it to decide who to cite. Since LLM scrapers don't merge nodes across pages, include the full `Person` on every page, not just the root.
- **`WebSite` goes on every page too, but slim on non-root pages.** The root page should have the full version (description, image, publisher, alternateName). Other pages just need the slim version so single-page crawlers correctly identify the site's name and domain.

`BreadcrumbList` is optional but useful — it controls how the page's path is displayed in search results. Skip it on the root page; include it elsewhere unless the site already has very short URLs.

### 3. Generate the JSON-LD

For each node:

1. Use the correct schema.org type and properties.
2. Replace placeholder URLs, names, and IDs with the user's actual values.
3. Wire up the `@id` references between nodes — e.g. a `BlogPosting`'s `author` should point at the `@id` of the `Person` node in the same `@graph`.
4. Assemble all nodes for the page into a single `@graph` array inside one `` block.

If the user provides a real example page (URL, content, dates, image paths), use their real values rather than placeholders. Concrete output is much more useful than a fill-in-the-blank template.

### 4. Where to place it in the HTML

The script tag goes inside the `` element. Order within `` doesn't matter for crawlers. If the site has a build step or a templating system, put the JSON-LD in the shared layout/template so each page type gets the right nodes automatically.

For static sites without a build step, even just adding `WebSite` + `Person` + `ProfilePage` to the root `index.html` is a meaningful improvement — start there if the user is overwhelmed.

## Important details and best practices

**Use the same `@id` for `Person` and `WebSite` across the entire site.** This is what lets Googlebot merge them into a single knowledge-graph entity. Pick the canonical form once (`https://example.com/#person`, `https://example.com/#website`) and reuse it verbatim on every page.

**Fill out `Person.sameAs` thoroughly.** Each link to another profile (GitHub, LinkedIn, Mastodon, Twitter/X, ORCID, Google Scholar, Wikipedia, etc.) helps crawlers disambiguate, especially if the user has a common name. If the user has a Google Knowledge Graph ID, include it as `https://www.google.com/search?kgmid=/g/...`.

**For `BlogPosting`, mirror the OG image.** The `image` property should point at the same image used for OpenGraph previews — that way social shares, search results, and structured data all match. Use dimensions 1200×630 unless the site has chosen otherwise.

**`publisher` can be a `Person` on a personal site.** Older Google docs required `Organization` for `publisher` on `Blog` and `BlogPosting`. That's been relaxed — `Person` is now valid and is more accurate for personal sites. Don't invent a fake organization just to fill the field.

**Always include `offers` on `SoftwareApplication`, even for FOSS.** Set `price: 0` and pick a `priceCurrency`. Google requires this field to render rich results for software.

**`dateCreated` / `dateModified` are freshness signals.** Include them when the site already tracks these dates. Don't fabricate them — outdated or wrong dates hurt more than missing ones.

**Pick the most specific `@type` available.** `SoftwareApplication` has subtypes `MobileApplication`, `WebApplication`, and `VideoGame` — use them when they fit. Similarly, `WebPage` has subtypes like `ProfilePage`, `CollectionPage`, `ContactPage`, `FAQPage`, `AboutPage`. More specific types give crawlers more to work with.

**Watch out for `BreadcrumbList` on the current page.** The `breadcrumb` property on `WebPage` (or its subtypes) should reference the `BreadcrumbList` `@id` for *that same page* — not a generic one. Each page needs its own `BreadcrumbList` with its own `@id`.

## Validating the output

After generating the JSON-LD, recommend the user validate it:

- **Google's Rich Results Test**: `https://search.google.com/test/rich-results` — checks for errors and shows which rich-result features the page qualifies for.
- **Schema.org Validator**: `https://validator.schema.org/` — strictly validates against the schema.org vocabulary without Google's opinionated requirements.

Both accept either a URL or pasted code. Run the output through at least one before considering the job done.

## What's out of scope

Schema.org defines many more types than this skill covers (`Recipe`, `Event`, `Product`, `LocalBusiness`, `Course`, `JobPosting`, `Review`, and so on). This skill focuses on the nodes that matter for personal sites, blogs, and portfolios. If the user needs JSON-LD for e-commerce, events, or other specialized contexts, point them at `https://schema.org` and `https://developers.google.com/search/docs/appearance/structured-data/search-gallery` for the relevant type-specific guidance.