# Schema.org

Schema.org is a shared vocabulary for describing what a page is about, normally embedded as JSON-LD. Every page in this manual carries a graph with `TechArticle`, `BreadcrumbList` and, where the page has questions, `FAQPage` — and the build refuses `Product`, `Offer`, `Review` and their relatives.

- **Status:** Reference
- **Audience:** developer, both
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/protocols/schema-org/

## Vocabulary, syntax and the difference

Schema.org supplies the nouns: types like `Article`, `Organization` or `Question`, each with defined properties. It does not supply the syntax. The same vocabulary can be expressed as JSON-LD in a script tag, as microdata woven through the HTML, or as RDFa. JSON-LD in a `application/ld+json` block is the practical choice, because it is one self-contained object that can be generated and validated separately from the markup around it.

There is no version to declare. Schema.org is updated continuously, types are added rather than replaced, and a consumer ignores properties it does not know. That is a genuine advantage and also why nobody can tell you which release they are reading.

A `@graph` holding several nodes is usually cleaner than several separate blocks: one object per page, nodes for the article, the breadcrumbs and the questions, each able to reference the others.

## The types worth using on a documentation site

| Type | Where | The property that matters most |
|---|---|---|
| `TechArticle` | Every page | `headline` — must equal the visible H1 |
| `BreadcrumbList` / `ListItem` | Every page | `position`, in the order a reader sees |
| `FAQPage` / `Question` / `Answer` | Pages with FAQs | Each `name` must appear as a visible heading |
| `SoftwareApplication` | As the article's `about` | `name` — the product the page describes |

`TechArticle` rather than plain `Article` because these pages are technical documentation, and `dateModified` because a documentation page with no date is a page whose reader cannot judge it. Breadcrumbs matter more here than they look: a thousand-page corpus needs its hierarchy stated, not inferred from URL segments.

## The types to avoid, and why

The build refuses `Product`, `Offer`, `AggregateOffer`, `Review`, `Rating` and `AggregateRating` outright. Each of them requires data this product does not have — a price, a customer's review, an aggregate score — and the only way to emit one is to invent it.

- Fabricated review or rating markup is a search-engine spam policy violation, not merely a bad idea, and manual action removes a site rather than one page.
- Structured data that describes something absent from the page is misleading whether or not any consumer notices.
- A refused type is a better outcome than a conversation about whether one invented star rating is really so bad.

> **Careful** Marking up an FAQ that a reader cannot see is the same offence in smaller print. The check here compares every declared `Question` against the headings actually rendered, and a question that exists only in the JSON-LD fails the build.

## Does Connect use Schema.org?

Yes, on the public documentation site, and it is verified rather than assumed. Every page under `/docs/`, `/research/` and `/developers/` carries a JSON-LD graph, generated from the same page data that renders the HTML — so the two are two views of one source rather than two things to keep in step.

A dedicated gate checks each built page: that a JSON-LD block exists and parses, that there is exactly one H1, that an `Article` or `TechArticle` node is present with a `dateModified`, that its `headline` is character-for-character the visible H1, that no forbidden type appears, and that every `FAQPage` question is also a visible heading.

The application itself emits no Schema.org markup. `/app` is a signed-in interface carrying a `noindex` tag; describing a private screen to a search engine would be pointless and slightly worse than pointless.

## Questions

### Does structured data improve rankings?

It is not a ranking factor in any published sense. What it does is make a page's subject, hierarchy and questions unambiguous to a machine reading it, and enable some result presentations. That is worth having on its own terms; expecting a position change from it is a different claim and not one this page makes.

### Why does the build refuse Product and Offer markup?

Because emitting them would require a price, an availability or a rating that does not exist here. Refusing the type in the gate removes the temptation and the argument at once.

### Can I rely on the JSON-LD matching the page?

Yes, and it is checked rather than promised: the headline must equal the rendered H1 and every declared FAQ question must appear as a visible heading, or the build fails. That check exists because structured data that quietly drifts from its page is worse than none.

## Related

- [llms.txt](https://connectbyjbrh.com/docs/protocols/llms-txt/)
- [The machine-readable documentation](https://connectbyjbrh.com/developers/machine-manifests/)
- [Writing documentation that both a person and a retrieval system can use](https://connectbyjbrh.com/research/writing-for-people-and-machines/)
- [RFC 9309 — the Robots Exclusion Protocol](https://connectbyjbrh.com/docs/protocols/rfc-9309/)
- [Measuring whether AI systems can actually read your site](https://connectbyjbrh.com/research/measuring-ai-visibility/)

## What this page is based on

- https://schema.org/
- `tools/docs_schema_check.py` — FORBIDDEN_TYPES and the page assertions
- `docs-source/render.py` — the JSON-LD graph each page carries