Product Schema Builder

A product page already tells a person everything that matters: what the thing is, what it costs, whether it is in stock, what other buyers thought of it. Structured data says the same things again, in a form a program can read without guessing. The idea is modest. The execution is where pages go wrong.

What structured data is, and who reads it

The format most pages use is JSON-LD, a way of writing linked data as ordinary JSON. The W3C Recommendation for JSON-LD 1.1 describes how a block of it sits inside an HTML page: a script element whose type is application/ld+json. The browser does not run it and the visitor never sees it. It is a data block, addressed to whatever software fetches the page.

The words inside that block come from schema.org, a shared vocabulary of types and properties. A type is a kind of thing, such as Product or Offer. A property is something you can say about it, such as name, brand or price. Each property lists the types it belongs to and the kinds of value it expects. The vocabulary is versioned, and every release can be downloaded as a single file; release 30.1, published on 16 September 2026, holds 939 types.

Who reads these blocks? Search engines are the obvious audience, and their documentation is the reason most shops add markup at all. But the same data feeds price comparison tools, shopping assistants, catalogue importers and a shop’s own internal checks. Writing it correctly serves all of them at once, which is a good reason to treat the vocabulary rather than any one consumer as the standard.

Schema.org itself is relaxed about mistakes. Its data model page says plainly that it expects messy data: where it asks for a Person or an Organization, it will often get a plain text string instead, and in the spirit of some data being better than none, consumers will accept it and do their best. That tolerance is generous, but it is not a promise that every consumer will understand a value it did not expect.

Product, Offer and ProductGroup

Three types carry most of a product page. Product is defined as any offered product or service, from a pair of shoes to a haircut. Offer is the offer to sell it: a price, a currency, availability, condition and the dates the price holds. A product with several sellers can carry an AggregateOffer instead, which gives a lowest and a highest price across all of them.

The third type is newer and solves a real problem. Most shops sell the same item in several colours or sizes. ProductGroup stands for the family: it is not itself for sale, but it names the properties its members vary by and lists each variant as a Product with its own offer. The variant documentation that one large search engine publishes asks for a unique identifier on every variant, such as its own SKU or GTIN, and for a group identifier that matches on both sides when both are given.

Here the published requirements become strict in a way the vocabulary is not. The product snippet documentation needs a name and at least one of a review, an aggregate rating or an offer. The merchant listing documentation goes further. It needs a name, an image and an Offer with a price above zero and a three-letter ISO 4217 currency code, and it does not accept an AggregateOffer, because the merchant has to be the seller.

Currency is a small field that trips many pages. The ISO 4217 standard assigns three capital letters to each currency, and the active list on its encyclopedia page holds 178 codes, including the precious metals and fund codes that begin with X. Writing EUR beside a price of 10.00 is unambiguous. Writing a symbol into the price, or a lower case code, is not, and the schema.org description of price explicitly asks for the code rather than an ambiguous symbol.

Identifiers and the check digit

Identifiers are how one database recognises a product listed in another. The Global Trade Item Number is the family most retail goods carry under their barcode. A GTIN may be 8, 12, 13 or 14 digits long; the 12-digit form is the familiar UPC, and the 13-digit form is the EAN that also absorbed the ISBN. Schema.org gives each length its own property, gtin8 through gtin14, plus a generic gtin.

The last digit of every GTIN is not part of the number at all. It is a check digit, computed from the others by a modulo 10 rule. Starting from the digit next to the check digit and moving left, the digits are multiplied by 3, 1, 3, 1 and so on, the products are added, and the check digit is whatever brings the total up to the next multiple of ten.

Take the code 0012345000128 from this tool’s example page. Its first twelve digits, read from the right, are 2, 1, 0, 0, 0, 5, 4, 3, 2, 1, 0 and 0. Weighted 3, 1, 3, 1 in turn they give 6, 1, 0, 0, 0, 5, 12, 3, 6, 1, 0 and 0, which sum to 34. The next multiple of ten is 40, so the check digit must be 6. The code ends in 8. Somebody typed it wrong, and no amount of tidy markup will make a catalogue match it to the right product.

Why does such a simple rule catch so much? Because the weights 3 and 1 are both coprime with 10, changing any single digit always changes the total’s last digit, so every single-digit error is detected. Swapping two neighbouring digits is usually caught as well, since their weights differ. The one blind spot the arithmetic leaves is a swap of two neighbours that differ by exactly five, such as 2 and 7, because the difference then multiplies out to a whole ten.

It is worth being clear about what a valid check digit proves. It shows the number is well formed, not that it was ever assigned to your product. Only the registry behind the numbers can answer that.

Ratings, availability and the rules around them

Ratings are where markup most often says something the page does not. The review snippet documentation treats a rating as a number on a scale of 1 to 5 unless bestRating and worstRating say otherwise, accepts fractions and percentages, and wants a dot, not a comma, before any decimals. A ratingValue of 6 with no scale given is therefore out of bounds, even though a reader of the page might know the shop rates out of ten. The same documentation asks for a real author name on each review, shorter than 100 characters, and for at least one of ratingCount or reviewCount on an aggregate.

Availability and condition are not free text. Schema.org defines them as enumerations with fixed members. In release 30.1, ItemAvailability has 12 values, from InStock and OutOfStock to PreOrder, BackOrder and SoldOut, and OfferItemCondition has four: new, refurbished, used and damaged. A page that writes In stock with a space, or Available, has written a sentence where a code was expected. The documentation accepts the short name without the address prefix, but not a near miss.

Dates follow ISO 8601: four digits of year, then month, then day, joined by hyphens. The format is easy; the calendar is where errors hide. The thirtieth of February passes a naive pattern test and fails any real one. A priceValidUntil date in the past is valid syntax, yet the documentation warns that a listing may not appear while it points backwards in time.

Addresses matter too. An image address written as a path, such as one starting with a slash, only means something when it is read in place on the page that holds it. A copied block, a feed or a cache loses that context. The general guidelines also ask that image addresses can be crawled and indexed, which starts with writing them out in full.

Valid is not the same as shown

This is the point most markup advice blurs. The general structured data guidelines state that there is no guarantee structured data will appear in search results, even when it is marked up correctly. A search engine weighs things such as a person’s search history, location and device, and may decide that a plain result serves best. It may also ignore markup that does not represent the main content of the page, describes content hidden from visitors, or has fallen out of date.

So a checker can do two honest things and no more. It can test markup against the published vocabulary, type by type and value by value, and it can test it against the requirements a search engine publishes for a feature. Passing both makes a page eligible. It cannot predict the choice that follows, and a tool that claims otherwise is selling a guess.

The practical habit that follows is to keep markup in step with the page. Generate it from the same data that renders the price and the stock level, check it whenever a template changes, and treat every error as a mismatch between what the page says and what it claims to say. Valid markup is not a trick for a better listing. It is the page telling the truth twice, once for people and once for machines.