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.
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.
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.