# Structured Data

> How to add JSON-LD structured data for AI agents: missing blocks, invalid JSON, schema.org context, @graph, entity types, and BreadcrumbList.

Cette vérification représente 6 % du score.

*Ces guides de correction sont rédigés en anglais.*

<a id="not-found"></a>

## No JSON-LD found

Your homepage has no `<script type="application/ld+json">` blocks. JSON-LD is the preferred format for structured data because it's embedded in HTML but completely separate from the visual content, making it easy for AI agents to parse.

Add a JSON-LD block to your `<head>`:

```
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "WebSite",
      "name": "Your Site Name",
      "url": "https://your-site.com"
    },
    {
      "@type": "Organization",
      "name": "Your Company",
      "url": "https://your-site.com",
      "logo": "https://your-site.com/logo.png"
    }
  ]
}
</script>
```

---

<a id="invalid-json"></a>

## Invalid JSON in block

One of your JSON-LD blocks contains invalid JSON syntax. Common issues include:

- Trailing commas after the last property
- Single quotes instead of double quotes
- Unescaped special characters in strings
- Missing commas between properties

Validate your JSON-LD at [validator.schema.org](https://validator.schema.org/) or use a JSON linter in your IDE.

---

<a id="all-invalid"></a>

## All blocks invalid

Every JSON-LD block on your page has invalid JSON. This means AI agents can't extract any structured data from your site. Fix the JSON syntax errors using the guidance in the [section above](#invalid-json).

---

<a id="missing-context"></a>

## Missing @context

Your JSON-LD doesn't include `@context` referencing schema.org. Without it, AI agents can't interpret the vocabulary of your structured data.

```
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company"
}
```

The context can be a string (`"https://schema.org"`) or an object with `@vocab`. Both `http` and `https` are accepted, with or without a trailing slash.

---

<a id="no-graph"></a>

## No @graph array

Your JSON-LD uses single-entity format. While valid, using an `@graph` array allows you to define multiple related entities in a single block, giving AI agents a richer understanding of your site.

```
{
  "@context": "https://schema.org",
  "@graph": [
    { "@type": "WebSite", "name": "...", "url": "..." },
    { "@type": "Person", "name": "...", "jobTitle": "..." },
    { "@type": "WebPage", "name": "...", "url": "..." }
  ]
}
```

---

<a id="few-types"></a>

## Few key entity types

ax-audit checks for 5 key entity types: `Person`, `Organization`, `WebSite`, `WebPage`, and `ProfilePage`. Your site has only 1 of these. Adding more types gives AI agents a more complete picture.

For a personal portfolio, a good combination is:

- `Person`: your identity, job title, social links
- `WebSite`: site name, URL, search action
- `WebPage` or `ProfilePage`: the current page

For a company site, use `Organization` instead of `Person`.

---

<a id="no-types"></a>

## No key entity types

Your JSON-LD has no recognized `@type` values. Every entity in your structured data should have a type from the schema.org vocabulary. See the [section above](#few-types) for recommended types.

---

<a id="no-breadcrumb"></a>

## No BreadcrumbList

Adding a `BreadcrumbList` entity helps AI agents understand your site's navigation hierarchy: which pages are parents of which.

```
{
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://your-site.com/"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog",
      "item": "https://your-site.com/blog"
    }
  ]
}
```

---

<a id="no-author"></a>

## No author

An assistant deciding whether to cite a page weighs where it came from. Declare `author` as a `Person` or `Organization`, not a bare string: a name in a string is a label, an object is an entity.

```
"author": {
  "@type": "Person",
  "name": "Ada Lovelace",
  "url": "https://example.com/authors/ada"
}
```

---

<a id="no-same-as"></a>

## No sameAs

`sameAs` is what turns a name into an entity. Link your `Organization` or `Person` to Wikidata, LinkedIn, GitHub or Crunchbase, and a model can connect this page to everything it already knows about you rather than treating you as a new string.

```
"sameAs": [
  "https://www.wikidata.org/wiki/Q123456",
  "https://github.com/example",
  "https://www.linkedin.com/company/example"
]
```

---

<a id="no-publisher"></a>

## No publisher

An article has a writer and an outlet, and a citation usually wants both. Declaring only the author leaves an assistant naming a person with no institution behind them, which reads as weaker sourcing than it is.

---

<a id="no-dates"></a>

## No dates

Assistants weigh recency when they answer time-sensitive questions, and a page with no date cannot be weighed at all. It is not treated as old; it is treated as unknown, which for a question about this year is the same outcome.

```
"datePublished": "2026-01-15",
"dateModified": "2026-09-04"
```

Add `dateModified` to anything that changes, and make it the real modification time rather than the build time, or every page on the site claims to have been updated today.

---

<a id="invalid-date"></a>

## A date that is not ISO 8601

`03/04/2026` is March in one country and April in another. Use `2026-09-04` or `2026-09-04T12:00:00Z`; anything else is either ignored or misread, and misread is worse.

---

<a id="future-date"></a>

## A date in the future

A future `dateModified` reads as a mistake or as an attempt to look fresher than you are, and both cost trust. Usually a timezone bug or a scheduled-publishing field written before the schedule ran.

---

<a id="stale-content"></a>

## Nothing modified in a long time

Informational, and not a defect: a reference page that was right in 2021 is still right. It matters because an assistant answering "what is the current" anything weighs recency heavily, so an accurate old page loses to a newer worse one.

If the content is current, say so by updating `dateModified` when you review it. If it is not, this is the page telling you.

---

<a id="markup-mismatch"></a>

## Markup that does not match the visible page

Your JSON-LD names a headline, a price or a rating that does not appear in the served text. This is Google's one explicit requirement for structured data and AI features: the markup must match what a reader sees.

> **Usually rendering, not deception**
>
> The comparison is against the static HTML, so a price injected by JavaScript after load looks exactly like a price that was never there. If that is your case, the finding is real and its cause is in the HTML Rendering guide rather than here.

---

Représentation Markdown de https://axrush.com/guides/structured-data