h-review: Reviews in Human-Readable HTML

A review is an editorial statement

An h-review connects an author, reviewed item, publication date, rating and review text. Markup cannot establish that an opinion is independent or accurate; it only exposes the structure already present. The visible page should identify who reviewed what, how any rating scale works and whether relevant relationships or incentives exist.

Root and core properties

Use h-review on the review container. p-name can provide a review title, p-summary a short assessment, e-content the full marked-up text, p-rating the score and dt-published the publication time. A property should wrap the content that actually carries the value. Avoid hidden spans that state a different conclusion from the prose.

Identify the reviewed item

The p-item property can contain a nested h-product, h-card or other suitable microformat. Give the item a stable URL when possible so separate reviews can refer to the same subject. A product name alone may be ambiguous across models or editions; include the distinctions that readers need to understand the scope of the judgment.

Rating scales

A numeric rating is meaningless without its scale. Provide best and, when necessary, worst values, and state the scale visibly. Do not convert qualitative judgments to numbers solely to fill structured fields. If sections use different scoring systems, avoid presenting an unqualified aggregate that suggests mathematical comparability.

Authorship and dates

The reviewer can be a nested h-card or a link to a stable author profile. Use dt-published for the original publication and explain meaningful updates separately. Replacing the date on every edit hides the review’s age. When a product changes substantially, a new review or clearly versioned update may be more honest than silent revision.

Moderation and user content

User reviews need controls against impersonation, spam and unsafe markup. Escape submitted content, constrain allowed HTML and separate verified transactional status from the opinion itself. Structured markup can amplify low-quality submissions, so only expose properties for content the site is prepared to publish and maintain as part of the page.

Parser and editorial checks

Inspect extracted author, item, rating, scale, date and content. Then perform a human review that compares those values with the visible claim. Test a review without a rating, one with a nested item and one updated after publication. The structured result and the editorial presentation should never contradict each other.

Questions for a design review

Use this reference to make a review decision, not merely to recognize terminology. Record the concrete document, schema, processor or consumer being discussed; the language and processor versions; and the behavior that must remain compatible. A useful review produces fixtures and an owner for every unresolved assumption.

• What executable example or test demonstrates the intended behavior for a review is an editorial statement?
• What executable example or test demonstrates the intended behavior for root and core properties?
• What executable example or test demonstrates the intended behavior for identify the reviewed item?
• What executable example or test demonstrates the intended behavior for rating scales?
• What executable example or test demonstrates the intended behavior for authorship and dates?
• What executable example or test demonstrates the intended behavior for moderation and user content?

Include at least one ordinary case, one boundary case and one deliberately invalid or unsupported case. Check the result in the actual production toolchain, because parsers, validators, code generators and reasoners do not all implement the same optional features. Store the selected contract version with the test result, then repeat the review when a dependency, namespace, profile or public declaration changes.

Continue with a working reference

Author identity with h-card · Microformats overview