Implementation · Machine-readable layer

Structured data for AI

Schema won't buy you a citation. It will stop a machine from guessing wrong about what you are, which turns out to matter more.

01Start with the graph, not the types

Most sites emit three separate JSON-LD blocks that never reference each other: an Organization here, an Article there, a BreadcrumbList somewhere else. A parser has to infer that they're related. Give it explicit edges instead.

The pattern: one @graph array per page, every node carrying an @id that is a real URL with a fragment, and references between nodes done by @id rather than by repeating the object. Every page on this site does exactly that — view source and read the block in the head.

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Co",
      "url": "https://example.com/",
      "sameAs": [
        "https://www.wikidata.org/wiki/Q000000",
        "https://www.linkedin.com/company/example-co"
      ],
      "knowsAbout": ["Retrieval augmented generation", "AI visibility"]
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com/",
      "publisher": { "@id": "https://example.com/#organization" }
    },
    {
      "@type": "TechArticle",
      "@id": "https://example.com/guide#article",
      "headline": "How retrieval works",
      "author": { "@id": "https://example.com/#organization" },
      "isPartOf": { "@id": "https://example.com/#website" },
      "datePublished": "2026-08-07",
      "dateModified": "2026-08-07",
      "about": { "@id": "https://example.com/#ai-visibility" }
    },
    {
      "@type": "DefinedTerm",
      "@id": "https://example.com/#ai-visibility",
      "name": "AI visibility",
      "description": "How often a brand is retrieved and cited inside AI answers."
    }
  ]
}
</script>

02The types that earn their place

03Three properties worth more than they look

sameAs

A list of authoritative URLs that refer to the same entity: Wikidata, Wikipedia, LinkedIn, Crunchbase, GitHub, official social profiles. This is the single most direct way to tell a machine “the thing on this page and the thing in that knowledge base are the same thing.” If you do one thing from this page, do this.

knowsAbout

On an Organization or Person, this declares topical expertise. It won't manufacture authority you don't have, but it disambiguates — a consultancy called “Northstar” that knowsAbout retrieval systems is clearly not the boat dealership with the same name.

speakable

A SpeakableSpecification with a CSS selector marks the passages you consider the canonical spoken summary of a page. Its official support is narrow, but it costs two lines and it states your intent about which passage is the answer. Point it at your answer block.

04Rules that keep you out of trouble

• Markup must match visible content. No exceptions. This is the rule that triggers manual actions.
• One canonical entity node per site, reused by @id on every page. Don't redefine your Organization with slightly different values on each template.
• Dates in ISO 8601, and dateModified only changes when content actually changes.
• Don't mark up navigation, ads or boilerplate as content.
• Validate before shipping with Google's Rich Results Test and the Schema.org validator. A single trailing comma silently kills the whole block.

Related: llms.txt, honestly — the other machine-readable file everyone is arguing about.