Structured data for a developer tool site

The one rule

The markup must describe what a reader can see on the page.

That is not a style preference. Marking up an FAQ that is not on the page, a rating nobody left, or a price that is not shown is a guidelines violation, and the penalty is not scoped to the page. A site can lose its rich results entirely.

We ran into this on our own site. The service page was a good candidate for FAQPage markup and it has no visible FAQ, so it did not get one. It got Service with an Offer at the price the page already states, which is a claim the page supports.

What is worth adding

What is not worth adding

AggregateRating you cannot substantiate. The most common way sites get manual actions in this area.

Review you wrote about yourself. Same.

Product on a page that is not a product. A blog post about a product is an Article.

Every type you can think of, stacked. More markup is not better markup. Each type is a claim, and a wrong claim is worse than a missing one.

The shape that works

One JSON-LD block, one @graph, nodes referring to each other by @id:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Acme",
      "url": "https://example.com/",
      "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" }
    },
    {
      "@type": "Article",
      "headline": "How the queue retries",
      "datePublished": "2026-09-03",
      "dateModified": "2026-09-03",
      "publisher": { "@id": "https://example.com/#organization" }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [
        { "@type": "ListItem", "position": 1, "name": "Acme", "item": "https://example.com/" },
        { "@type": "ListItem", "position": 2, "name": "Docs", "item": "https://example.com/docs" }
      ]
    }
  ]
}
</script>

Three things that go wrong here often:

A missing @context. Without it the block is not schema.org and does nothing. Easy to omit when hand-writing, and it fails silently.

Unescaped content. A </script> inside a string ends the block. Escape <, > and & when generating.

Dates that are not real. dateModified set to the build date on every page tells a parser that your whole site changed today, every day. Use the date the content actually changed.

Generate it, do not hand-write it

Hand-written markup drifts from the page. The title changes and the headline does not. A date is updated in the text and not in the block.

Generate it from the same source as the page, in the same build, and add a test that parses every block and asserts the required nodes exist. We do that: every page in this library is checked for parseable JSON-LD, a correct @context and a BreadcrumbList, and the build fails without them.

Does it matter for coding agents

Less than for search engines, and it is not nothing.

An agent fetching a page mostly reads the content. But structured data on a documentation page states the version, the publisher and the dates in a form that cannot be misread, and that is exactly the class of fact models get stale on.

The bigger lever for agents is a Markdown twin of the page, which almost nobody publishes. Do both. The markup is an hour, the twin is an afternoon, and neither is a substitute for the content being correct.