Review boxes, shortcodes and JSON-LD

01What is the difference between a review box and its markup?

Review box JSON-LD is the part of a WordPress review that readers never see. A review box is the visible panel, usually a score, a few criteria bars and a verdict, that a plugin, block or shortcode places in a post. Its markup is a separate description of the same review, written for machines, that tells search engines who reviewed what and what score they gave.

The two must say the same thing. Google's review snippet guidelines require that the review content you mark up is readily available to users on the page, so the score in your JSON-LD has to be the score in the box.

Everything in this guide follows from that rule. If the box and the markup are produced from different data, they drift apart, and the drift stays invisible until a rich result disappears or a reader notices a different score in search. A score that appears as one rating in a search result and another on the page undermines the review before anyone reads it.

02Why move from microdata to JSON-LD?

Many older review boxes wrote microdata: itemprop attributes woven into the box's own HTML. Microdata is a format that marks up structured data inside visible HTML elements. JSON-LD is a format that keeps the same information in a separate script block, apart from the visible text.

Google accepts JSON-LD, microdata and RDFa equally for eligibility, and its introduction to structured data recommends JSON-LD where a site's setup allows it, because it is the easiest to implement and maintain at scale and less prone to user errors. JSON-LD is not interleaved with visible text, so a theme redesign cannot break it by changing the box's HTML.

The trade-off is in the third row. Microdata cannot drift from the visible score because it is the visible score. JSON-LD can, so a migration only pays off if both outputs read from one source.

When you migrate, remove the microdata in the same release. Two descriptions of one review, one inline and one in a script block, can disagree, and nothing is gained by keeping both. Search the rendered page for itemprop after the release to confirm nothing was left behind.

03How do you keep the visible rating and the markup in sync?

Store the review data once, as post meta or block attributes, and render both outputs from it. A shortcode is a WordPress macro in square brackets that runs code when a post is displayed; the Shortcode API handbook explains that shortcodes exist because running PHP inside post content is forbidden. That makes a shortcode a natural place to build the box and the markup from the same attributes in the same request.

1. Save the score, the scale, the item name and the reviewer as structured fields, never only as formatted text inside the post.
2. Render the visible box from those fields.
3. Build the JSON-LD as a PHP array from the same fields, and print it with wp_json_encode() rather than string concatenation.
4. State the scale. If the box shows a score out of 10, set bestRating to 10.
5. Print one Review per reviewed item, and only on the post that contains the box.

Step 4 is easy to miss. Google's review snippet documentation says that 5 is assumed when bestRating is omitted, so a box showing 8.5 out of 10 with markup that leaves out the scale describes a different rating. The guide to adding JSON-LD without a plugin shows the safe encoding pattern in full.

04How do block-based review boxes output schema?

Block review boxes come in two kinds. WordPress's guide to static and dynamic block rendering explains that static blocks save their front-end markup to the database when the post is saved, while dynamic blocks generate it on the server each time the page is requested.

For schema, the difference matters. A static block that saves JSON-LD into post content freezes it: change the markup logic later and old posts keep the old output until each one is saved again. A dynamic block can build the JSON-LD at request time from its attributes, so a fix reaches every post at once. If you are choosing or building a review block, prefer dynamic output for the markup, even if the visible box stays static. A block's attributes are stored with the block in the post content, so server code can read them back and build the JSON-LD from the same values the box displays.

Either way, check that the block prints markup once per reviewed item even if an editor places two boxes in one post. Google's review snippet guidelines ask for review information about a specific item, not about a category or a list of items, so a roundup post needs a different approach, covered in ItemList schema for ranked lists and tables.

05A review box JSON-LD template

The template below is what a single editorial review box should produce: one Review, the reviewed product named in itemReviewed, a named author, and a rating with an explicit scale. Every value is a placeholder.

1{2  "@context": "https://schema.org",3  "@type": "Review",4  "@id": "https://example.com/reviews/example-grinder/#review",5  "itemReviewed": {16    "@type": "Product",7    "name": "Example Coffee Grinder"8  },9  "author": {10    "@type": "Person",11    "name": "Example Author",212    "url": "https://example.com/authors/example-author/"13  },14  "reviewRating": {15    "@type": "Rating",16    "ratingValue": 8.5,17    "bestRating": 10,318    "worstRating": 119  },20  "datePublished": "2026-11-08",21  "reviewBody": "A consistent grind at every setting, let down by a noisy motor.",22  "publisher": {23    "@type": "Organization",24    "name": "Example Reviews",25    "url": "https://example.com/"26  }27}

Adapt the reviewed type to the content. The review snippet documentation lists the types that can carry review snippets, including Book, Course, Recipe, SoftwareApplication, Product and LocalBusiness. If the post reviews your own business, stop: those reviews are self-serving and will not earn stars.

06Testing the box and the markup together

Test a published post URL in the Rich Results Test and confirm that one Review snippet is detected with the same score the box shows. Then change the score in the editor, update the post and test again. If the markup follows the change, the two outputs share a source. If your box supports more than one scale, such as stars and a score out of 10, repeat the check on a post that uses each one.

Finally, run the WordPress schema plugin audit on a review post to make sure the theme or an SEO plugin is not adding a second Review or an Article that claims a different author.

For the wider picture of how review markup fits with everything else a page declares, the handbook home is a structured data handbook written for WordPress sites, and the other how-tos are in the WordPress guides.