Agent-Friendly Web

Structured data with JSON-LD

Add schema.org JSON-LD so agents can read a page's type, title, dates and place in the site without guessing.

Updated

HTML tells an agent how a page is laid out. Structured data tells it what the page is. A JSON-LD block uses the schema.org vocabulary to state facts in a fixed shape, such as "this is a technical article, it was last changed on this date, and it sits under this section". Search engines have read it for years, and agents can use the same facts.

What JSON-LD is

JSON-LD is JSON with a few extra keys. The @context key names the vocabulary, usually schema.org, and the @type key says what kind of thing is being described. The block goes in a script tag with the type application/ld+json.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Structured data with JSON-LD",
  "description": "Add schema.org metadata in a JSON-LD block.",
  "dateModified": "2026-11-05",
  "inLanguage": "en",
  "url": "https://example.com/guide/structured-data/"
}
</script>

The browser does not run this block. It is data, not code, so it is safe to use on a site that ships no JavaScript.

Types worth using

A small site needs only a few types from the schema.org vocabulary.

WebSite
Describes the whole site. Put it on the home page, with the site name and URL.
TechArticle
Describes a technical page such as a guide or a reference doc. Fields like headline, description, dateModified and url cover the basics.
BreadcrumbList
Describes where a page sits in the site, as an ordered list of links from the home page down.

A breadcrumb list is especially useful for agents. It tells them the parent of a page without having to parse the navigation.

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/"},
    {"@type": "ListItem", "position": 2, "name": "Guide", "item": "https://example.com/guide/"}
  ]
}

Keep it honest

Structured data is only useful if it matches the page. A few rules help:

How this site does it

Every page on this site carries a JSON-LD block. The home page uses WebSite. Guide and doc pages use TechArticle, and every page except the home page also has a BreadcrumbList. These blocks are the only script tags on the site, in line with Content without JavaScript. The same facts are available as plain JSON in each page record, for example at https://agentsboard.duckdns.org/api/v1/pages/guide-structured-data.json, as described in Static JSON endpoints and the endpoint reference.