From JSON-LD to Agent Actionable: How to Structure Product Data So AI Can Actually Buy

TL;DR: Schema.org JSON-LD is the backbone of product data for AI agents. Most implementations are too shallow - missing offers, aggregateRating, availability, or shippingDetails. An agent needs full product context to make a purchase decision. This guide shows you the before-and-after.

---

The Shallow JSON-LD Problem

Most e-commerce sites implement JSON-LD like this:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Running Shoes",
  "description": "Lightweight running shoes for daily training."
}

That tells an agent the product exists. It tells the agent nothing about whether it can buy it.

---

What an Agent Needs to Complete a Purchase

An AI agent that shops on behalf of a user needs to answer these questions:

1. What is the product? (name, description, image, SKU)
2. How much does it cost? (price, currency, offers)
3. Is it in stock? (availability, inventoryLevel)
4. Can it be shipped to the user? (shippingDetails, deliveryTime)
5. What do other buyers say? (aggregateRating, review)
6. What are the variants? (color, size, material)
7. What is the return policy? (merchantReturnPolicy)

Without these fields, the agent either abandons the purchase or asks the user for clarification - defeating the purpose of agentic commerce.

---

Before: Incomplete JSON-LD

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Nike Air Zoom Pegasus 40",
  "description": "Responsive cushioning for everyday runs.",
  "image": "https://example.com/shoes.jpg"
}

Agent verdict: "I found a product, but I cannot confirm price, stock, shipping, or reviews. I will skip it."

---

After: Agent-Actionable JSON-LD

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Nike Air Zoom Pegasus 40",
  "description": "Responsive cushioning for everyday runs.",
  "image": "https://example.com/shoes.jpg",
  "sku": "NIKE-P40-BLK-10",
  "mpn": "DV7480-001",
  "brand": {
    "@type": "Brand",
    "name": "Nike"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/nike-pegasus-40",
    "price": "129.99",
    "priceCurrency": "GBP",
    "priceValidUntil": "2026-12-31",
    "availability": "https://schema.org/InStock",
    "itemCondition": "https://schema.org/NewCondition",
    "shippingDetails": {
      "@type": "OfferShippingDetails",
      "shippingRate": {
        "@type": "MonetaryAmount",
        "value": "5.00",
        "currency": "GBP"
      },
      "shippingDestination": {
        "@type": "DefinedRegion",
        "addressCountry": "GB"
      },
      "deliveryTime": {
        "@type": "ShippingDeliveryTime",
        "handlingTime": {
          "@type": "QuantitativeValue",
          "minValue": "0",
          "maxValue": "1",
          "unitCode": "DAY"
        },
        "transitTime": {
          "@type": "QuantitativeValue",
          "minValue": "1",
          "maxValue": "3",
          "unitCode": "DAY"
        }
      }
    },
    "hasMerchantReturnPolicy": {
      "@type": "MerchantReturnPolicy",
      "returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
      "merchantReturnDays": "30",
      "returnMethod": "https://schema.org/ReturnByMail",
      "returnFees": "https://schema.org/FreeReturn"
    }
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.6",
    "reviewCount": "128"
  },
  "review": [
    {
      "@type": "Review",
      "author": { "@type": "Person", "name": "Sarah K." },
      "reviewRating": { "@type": "Rating", "ratingValue": "5" },
      "reviewBody": "Best daily trainer I have owned. Responsive and durable."
    }
  ]
}

Agent verdict: "Price confirmed: £129.99. In stock. Ships to UK in 1-3 days. 30-day free returns. 4.6 stars from 128 reviews. Proceeding to checkout."

---

Implementation Tips for Developers

Use a Structured Data Generator

Most e-commerce platforms have plugins or built-in generators:

• Shopify: Apps like JSON-LD for SEO or built-in Online Store 2.0 schema
• WooCommerce: Yoast SEO, Rank Math, or Schema Pro
• Custom Next.js: Use schema-dts for TypeScript-safe JSON-LD

import { Product, Offer, AggregateRating } from 'schema-dts';

const productSchema: Product = {
  '@type': 'Product',
  name: 'Nike Air Zoom Pegasus 40',
  offers: {
    '@type': 'Offer',
    price: '129.99',
    priceCurrency: 'GBP',
    availability: 'https://schema.org/InStock',
  },
};

Validate Before Publishing

Use Google's Rich Results Test or Schema.org validator:

# Validate with schema.org validator
curl -s -X POST https://validator.schema.org/validate \
  -H "Content-Type: application/json" \
  -d '{"jsonld": "<your-json-ld-string>"}'

---

Recommended Next Step

Run a free AI Readiness Scan on your product pages. The scanner checks for JSON-LD presence, depth, and completeness - and tells you exactly which fields are missing for agent purchase decisions.