> ## Documentation Index
> Fetch the complete documentation index at: https://learn.orbexa.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema.org structured data for AI agents

> A complete guide to Schema.org structured data markup — making AI agents accurately understand your products, company, and web content.

# Schema.org in Practice

## 3.1 What is Schema.org

[Schema.org](https://schema.org) is a structured data standard created jointly by Google, Microsoft, Yahoo, and Yandex. It defines a unified vocabulary that turns web page content into machine-readable data.

**Plain-language explanation**: Your product page displays "Nike Air Max 90, \$129.99, In Stock." A human reads that instantly, but a machine sees only a string of text. Schema.org markup tells the machine: this is a `Product`, the name is "Nike Air Max 90," the price is "129.99 USD," and the availability is `InStock`.

**Impact on AI agents**: AI agents (ChatGPT, Claude, Gemini, etc.) prioritize pages with structured data when making product recommendations, because they can extract product information accurately and reduce hallucination.

## 3.2 Three Implementation Formats

| Format        | Recommendation  | Description                                                                                     |
| ------------- | --------------- | ----------------------------------------------------------------------------------------------- |
| **JSON-LD**   | Recommended     | Officially recommended by Google. A standalone `script` tag that does not affect HTML structure |
| **Microdata** | Acceptable      | Embedded in HTML tag attributes (`itemprop`, `itemscope`)                                       |
| **RDFa**      | Not recommended | Older format with low adoption                                                                  |

**Why JSON-LD is recommended**:

* Completely decoupled from HTML, easy to maintain
* Can be dynamically generated on the server side
* Parsed most efficiently by AI agents
* Explicitly recommended by Google

## 3.3 E-Commerce Essential: Product Markup

A complete Product markup example:

```json theme={null}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Classic Canvas Sneakers",
  "description": "Comfortable, breathable classic canvas shoes for everyday wear.",
  "image": [
    "https://example.com/photos/shoe-1.jpg",
    "https://example.com/photos/shoe-2.jpg"
  ],
  "brand": {
    "@type": "Brand",
    "name": "ExampleBrand"
  },
  "sku": "SHOE-001",
  "gtin13": "1234567890123",
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/shoe-001",
    "priceCurrency": "USD",
    "price": "49.99",
    "availability": "https://schema.org/InStock",
    "seller": {
      "@type": "Organization",
      "name": "Example Store"
    },
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "US"
      },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "businessDays": {
          "@type": "QuantitativeValue",
          "minValue": 1,
          "maxValue": 5
        }
      }
    },
    "hasMerchantReturnPolicy": {
      "@type": "MerchantReturnPolicy",
      "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
      "merchantReturnDays": 30
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.6",
    "reviewCount": "128"
  }
}
</script>
```

**Required fields checklist**:

| Field                     | Importance           | Description                         |
| ------------------------- | -------------------- | ----------------------------------- |
| `name`                    | Required             | Product name                        |
| `description`             | Required             | Product description                 |
| `image`                   | Required             | At least one high-quality image URL |
| `offers.price`            | Required             | Price                               |
| `offers.priceCurrency`    | Required             | Currency code (USD/EUR/GBP, etc.)   |
| `offers.availability`     | Required             | Stock status                        |
| `brand`                   | Strongly recommended | Brand name                          |
| `sku`                     | Recommended          | Unique product identifier           |
| `gtin13` / `gtin14`       | Recommended          | International barcode               |
| `aggregateRating`         | Recommended          | Rating summary                      |
| `shippingDetails`         | Recommended          | Shipping information                |
| `hasMerchantReturnPolicy` | Recommended          | Return policy                       |

## 3.4 Company Information: Organization Markup

In addition to products, your company information needs to be structured. Place this on your homepage or "About Us" page:

```json theme={null}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Your Company Name",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "description": "A one-line description of your business",
  "foundingDate": "2020-01-01",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main Street",
    "addressLocality": "San Francisco",
    "addressRegion": "CA",
    "postalCode": "94105",
    "addressCountry": "US"
  },
  "contactPoint": {
    "@type": "ContactPoint",
    "contactType": "customer service",
    "email": "support@example.com",
    "telephone": "+1-555-123-4567"
  },
  "sameAs": [
    "https://twitter.com/example",
    "https://www.linkedin.com/company/example"
  ]
}
</script>
```

## 3.5 Breadcrumb Navigation: BreadcrumbList

Helps AI agents understand your site's hierarchical structure:

```json theme={null}
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://example.com"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Sneakers",
      "item": "https://example.com/category/sneakers"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Classic Canvas Sneakers"
    }
  ]
}
</script>
```

## 3.6 Common Mistakes

| Mistake                                  | Consequence                                    | Fix                                           |
| ---------------------------------------- | ---------------------------------------------- | --------------------------------------------- |
| Price missing currency code              | AI cannot compare prices                       | Always include `priceCurrency`                |
| Missing availability status              | AI does not know if the product is purchasable | Dynamically update `availability`             |
| Relative image paths                     | AI fails to fetch images                       | Use full `https://` URLs                      |
| Markup inconsistent with visible content | Penalized by search engines                    | Keep markup data aligned with on-page content |
| Malformed nested JSON                    | Parse failure                                  | Validate with testing tools                   |

## 3.7 Validation Tools

After configuring Schema.org markup, validate with these tools:

1. **[Google Rich Results Test](https://search.google.com/test/rich-results)** — Checks if markup is correct and eligible for rich results
2. **[Schema.org Validator](https://validator.schema.org/)** — The official validation tool
3. **Browser DevTools** — Inspect the page source for `script type="application/ld+json"` content

## 3.8 Self-Assessment Checklist

* [ ] Every product page has a `Product` JSON-LD block
* [ ] Product markup includes name, description, image, price, and availability
* [ ] Homepage or About page has an `Organization` JSON-LD block
* [ ] Category pages have `BreadcrumbList` markup
* [ ] At least 3 pages validated with Google Rich Results Test
* [ ] Markup data is consistent with visible page content

***

**Next chapter**: [JSON-LD vs Microdata](/en/book-6/ch4-jsonld-vs-microdata) — Technical comparison and migration guide