h-card: People and Organizations in HTML

What h-card represents

An h-card marks up a person, organization or place using the same HTML that readers already see. The root class is h-card; property classes identify names, URLs, email addresses, photographs, organizations and addresses. This is structured publishing, not a hidden duplicate record. When visible content and machine-readable content differ, maintenance and trust both suffer.

A minimal card

Start with one element carrying h-card and a visible name carrying p-name. Add u-url to the canonical profile link and u-photo only when an image is intentionally public. An anchor can carry more than one property class when its text and URL express different facets. Keep the smallest card that answers the page’s actual identity use case rather than filling every possible property.

Property prefixes

Microformats2 uses p- for plain text, u- for URL-like values, dt- for date or time values and e- for embedded HTML. The prefix influences value parsing, so choosing it is semantic rather than decorative. A u-email property, for example, extracts a URL value, while a p-note extracts text. Test the parsed value instead of assuming the browser’s visible rendering proves correct markup.

Canonical identity

A profile can appear on many pages, but its canonical URL should remain stable. rel=me links can connect profiles controlled by the same entity when that relationship is intentional. Do not equate matching display names with identity, and do not mint a new URL every time a card is embedded. Stable identity is what lets mentions, authorship and replies join reliably.

Addresses and nested cards

Address components can be properties on the card or grouped in a nested h-adr structure. Nested h-cards can express an organization or another related identity, but nesting changes how parsers associate properties. Use representative parser tests for each nested structure and keep labels visible so human readers understand the same relationship the markup describes.

Privacy and stale data

Structured contact data is easy to aggregate. Publish only details the subject expects to be public, avoid personal sample data in documentation and provide a process for corrections. A machine-readable phone number or address can remain cached after visible removal, so choose durable, role-based contact points when personal data does not need to be exposed.

Validation workflow

Validate the HTML, run at least one microformats2 parser and inspect the resulting JSON. Check relative URL resolution, image URLs, language, whitespace and cards embedded in lists. Add a regression fixture for every template that emits h-card. Parser output—not the presence of class names—is the acceptance test for structured identity data.

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 what h-card represents?
• What executable example or test demonstrates the intended behavior for a minimal card?
• What executable example or test demonstrates the intended behavior for property prefixes?
• What executable example or test demonstrates the intended behavior for canonical identity?
• What executable example or test demonstrates the intended behavior for addresses and nested cards?
• What executable example or test demonstrates the intended behavior for privacy and stale data?

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

Microformats overview · Résumé profiles