Merchant Evidence Brief · Issue 2
"Machine-readable product data" means two different things. Here are both specs, side by side.
Sources checked 22 November 2026 (Korea Standard Time, UTC+9). Published here as a web archive.
Last issue covered who reads your site. This one covers what they need. There are two common ways a store hands structured product facts to machines:
- On-page structured data: JSON-LD on each product page, read by crawlers like Googlebot.
- A product feed: a file (CSV, TSV, JSON) you submit with one row per item, such as the product feed OpenAI documents for its shopping surfaces.
They overlap, but their rules differ in ways that cause silent rejections. Below is what each primary source requires.
1. Google merchant listings (on-page JSON-LD)
Google’s merchant-listing documentation covers product pages where a customer can buy (Google). The required core:
- A
Productwithname,image, andoffers, and the offer has to be an individualOffer. Google’s general Product snippet docs acceptAggregateOfferfor pages that list several sellers, but merchant listings are about a single seller’s offer (Google; Google — product snippets). - The
Offerneeds a price, eitherpriceorpriceSpecification.price, with its currency, and Google requires the price to be greater than zero for merchant listings (Google). - Many other properties (description, availability, brand, GTIN, shipping, return policy) are listed as recommended: helpful, not required (Google).
Google’s AI-features guidance adds a related fundamental: “making sure your structured data matches the visible text on the page” (Google — AI features). Markup claiming a price or stock state the page doesn’t show is a problem in its own right.
Common misreadings
- “If the Rich Results Test passes, I’m eligible.” Passing validation isn’t a guarantee of display. Google’s documentation consistently separates eligibility from serving (Google — AI features).
- “AggregateOffer is fine everywhere.” For merchant listings, use an Offer.
2. OpenAI’s product feed (file upload)
OpenAI’s product feed reference describes a discovery feed with stricter, row-level rules (OpenAI):
- One row per purchasable item or variant. Variants get their own row with a distinct
item_id, sharing agroup_id. - Required discovery fields:
item_id,title,description,url,brand,seller_name,image_url,availability,price, plus geo fieldstarget_countriesandstore_country(OpenAI). - Availability is an enumeration:
in_stock,out_of_stock,pre_order,backorder, orunknown. The docs state: “Omitted, empty, or unrecognized values reject the row.” Useunknownexplicitly if you don’t know (OpenAI). - Price is a money string such as
79.99 USD, in major currency units (OpenAI). - No placeholders. “Do not use placeholder strings such as
null,unknown, orn/a.” For optional fields, omit unknown values.unknownis valid only where explicitly listed (OpenAI). - Format hygiene: UTF-8, absolute HTTP(S) URLs (HTTPS preferred), and identifiers kept as strings “to preserve leading zeros.” CSV cells with commas, quotes, or newlines must be quoted, with embedded quotes doubled (OpenAI).
- GTIN (optional): exactly 8, 12, 13, or 14 digits with a valid check digit, leading zeros preserved, no spaces or dashes. Omit it if unassigned (OpenAI).
- Length guidance: aim for at most 150 characters for titles and 5,000 for descriptions (OpenAI).
- Ads and checkout have separate requirements from the discovery feed (OpenAI).
3. Side by side
| Topic | Google merchant listing (JSON-LD) | OpenAI product feed (file) |
|---|---|---|
| Unit | One product page | One row per item/variant |
| Required identity | name, image |
item_id, title, image_url, url, brand, seller_name, description |
| Offer/price | Individual Offer with price + currency, price > 0 |
price as amount + currency string |
| Availability | Recommended | Required enum; bad value rejects the row |
| GTIN | Recommended | Optional; strict digits + check digit |
| Placeholders | Not addressed in the sections cited here | Explicitly prohibited |
4. Where spreadsheets quietly break feeds
Most of the OpenAI rules above are ones spreadsheets violate by default:
- Leading zeros: a GTIN like
0950...opened in a spreadsheet can lose its first digit. Long numbers may appear as9.506E+12. - Availability drift: “In Stock”, “available”, and
preorderaren’tin_stockorpre_order. - “N/A” in empty cells: a habit the OpenAI spec explicitly asks you not to follow.
- Formula-like text: cells starting with
=,+,-, or@can be executed when a colleague opens the CSV, which OWASP calls CSV injection (OWASP). That’s a safety issue for anyone opening the file, separate from feed validity.
5. Which one do you need?
It depends on where you want to appear, and the sources keep those decisions separate:
- Google Search product experiences: on-page structured data is the documented route for merchant listings. Google also lists keeping Merchant Center information up to date among the fundamentals (Google — AI features). Merchant Center feeds have their own specification, which this issue doesn’t cover.
- OpenAI shopping discovery: the product feed reference is the documented route. On-page JSON-LD isn’t described there as a substitute (OpenAI).
Many stores will want both, generated from one source of truth (your catalog database or platform export), so the price on the page, in the JSON-LD, and in the feed never disagree. If you maintain the feed by hand in a spreadsheet, the four failure modes in section 4 are the ones to automate first.
Ten-minute check
- Export your catalog as CSV. Open it in a text editor, not a spreadsheet, and search for
E+. Any hit in an ID or GTIN column means digits may already be lost. - Search for
n/a,null, andTBD, and delete them from optional fields. - List the distinct values in your availability column. Each one should map to exactly one value from the OpenAI enumeration.
- On one product page, view the source and find the JSON-LD. Confirm there’s an
Offer(not only anAggregateOffer), a price above zero, and a currency, and that the price matches what the page shows. - Write down which surface each fix was for. Ads and checkout integrations need their own checks.
Disclosure: the author is building Catalog Sentry Local, a local CSV preflight tool that checks several of these rules. It isn’t required for anything above, and every check here can be done by hand. This issue has no sponsor.
Sources - Google Search Central, Merchant listing structured data: https://developers.google.com/search/docs/appearance/structured-data/merchant-listing - Google Search Central, Product snippet structured data: https://developers.google.com/search/docs/appearance/structured-data/product - Google Search Central, AI features and your website: https://developers.google.com/search/docs/appearance/ai-features - OpenAI, Product feed schema: https://developers.openai.com/commerce/specs/file-upload/products - OWASP, CSV Injection: https://owasp.org/www-community/attacks/CSV_Injection