# Structured data and content

Structured data is a machine-readable description of what a page already says. Content is what a person can read. The rule that keeps both useful is that markup must describe what is visible — mark up a fact that is not on the page and you have published a claim nobody can check, which is both an eligibility problem and a credibility one.

- **Status:** Reference
- **Audience:** developer
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/compare/structured-data-vs-content/

## What each one is for

Content answers the question. Structured data — JSON-LD using the schema.org vocabulary — tells a machine what kind of thing the page is and which parts are the title, the question, the answer, the date. It makes a page *legible*, and legibility is not the same as substance.

The practical consequence is that markup cannot rescue a thin page. A retrieval system that wants to quote you needs a sentence worth quoting; there is no property in any vocabulary that supplies one.

**Content** — The words, the tables, the examples, the failure modes. Read by people, quoted by machines.
**Structured data** — A description of those words in a defined vocabulary. Read by machines, invisible to people.
**The relationship** — One describes the other. It is never a second source of truth, and the moment it becomes one, one of them is lying.

## The rule, and why it is a rule

**Markup must match what a reader can see.** Search systems state this in their own guidance, and the enforcement is not subtle: markup that describes content the page does not contain makes the page ineligible for the feature it was reaching for, and repeated cases attract manual action against the site.

> **Careful** The tempting version is a review or rating property on a page with no reviews. This documentation does not publish a rating, a testimonial or a customer count anywhere, in prose or in markup, because the two must agree and the prose is not allowed to invent one either.

- An FAQ described in markup must be an FAQ a reader can see and read.
- A date in markup must be the date the page actually changed.
- A price in markup must be a price on the page. If there is no price, there is no property.
- An author must be a real, identified author — which is why nothing here claims one.

## Drift, and how to make it impossible

Markup and content agree on the day they are written and diverge every day after, if they are maintained separately. Somebody edits a paragraph; nobody edits the JSON-LD. Six months later the page says one thing and its description says another, and the machine reads the description.

The fix is structural rather than procedural: generate both from one record. Every page in this corpus is a data structure — the answer, the sections, the FAQs, the date — and the HTML and the JSON-LD are two renderings of it. The build refuses malformed JSON-LD, and it refuses a page whose parts are missing, so drift is not something anyone has to remember to check.

| Approach | Fails when | Effort over time |
|---|---|---|
| Hand-written markup beside hand-written content | Anybody edits either one | Constant, and unrewarded |
| Both generated from one page record | The record is wrong — which is visible to a reader as well | Once, at build time |

## What to do with the effort instead

Structured data is cheap once it is generated, so the marginal hour is better spent on the content it describes. Concretely: answer the question in the first paragraph, name the real mechanism instead of *the system*, give the number you measured rather than an adjective, and write the failure modes down — a page that only describes success is half a page, and it is the half nobody needed.

> **Note** The same principle governs every machine surface here. [Markdown alternates](/developers/markdown-mirrors/) and the [manifests](/developers/machine-manifests/) are renderings of the page, not extra content. If something is true only in the manifest, it is not true on the page, and that is a defect.

## Questions

### Does structured data improve ranking?

It makes a page eligible for presentation features and helps a machine parse what is there. It does not add information, and a page with excellent markup and nothing to say competes against pages that answer the question. Treat it as plumbing, not as an advantage.

### Can I mark up an FAQ that is only in the markup?

No. That is precisely the violation — content described but not visible. If the questions are worth answering, put them on the page where a reader benefits too; if they are not, do not publish them in either place.

### How does this documentation keep the two in step?

Every page is one record from which the HTML, the JSON-LD, the Markdown alternate and the manifests are all generated, and the build gate refuses malformed markup, a page missing a required part, and a sitemap that disagrees with the published set.

## Related

- [JSON-LD and structured data](https://connectbyjbrh.com/docs/technology/json-ld/)
- [Schema.org](https://connectbyjbrh.com/docs/protocols/schema-org/)
- [Comparisons and concepts](https://connectbyjbrh.com/docs/compare/)
- [llms.txt and a sitemap](https://connectbyjbrh.com/docs/compare/llms-txt-vs-sitemap/)
- [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/)

## What this page is based on

- https://schema.org/ — the vocabulary
- `tools/docs_check.py` — malformed JSON-LD, missing parts, sitemap agreement
- `docs-source/WORKER-BRIEF.md` §3 — what may never be claimed
- `docs-source/sources/GENERAL.md` §12 — house style for the corpus