h-listing

This document represents a draft microformat specification. Although drafts are somewhat mature in the development process, the stability of this document cannot be guaranteed, and implementers should be prepared to keep abreast of future developments and changes. Watch this wiki page, or follow discussions on the #microformats IRC channel to stay up-to-date.

h-listing is a simple, open format for publishing product data on the web. h-listing is one of several open microformat draft standards suitable for embedding data in HTML.

h-Listing is the microformats2 update to hListing.

Per CC0, to the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 2024-11-21, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0.

Draft Proposal

Editors

• Tantek Çelik
• Tom Morris
• Arthur Rădulescu

Introduction

Individuals and professionals are increasingly publishing their offerings online: whether as items for sale or rent (cars, homes, apartments), services for hire (music lessons, dog walker, plumber), openings (jobs, volunteers, extra spot in a book club) or personals (people looking for dates, companions, roommates). The goal of publishing (and promoting) these listings online is to seek out interested parties, often within a limited time period.

While descriptions of products and services are common on the Web, particularly on e-commerce sites, we are proposing an hListing microformat for sharing, searching, and syndicating the information that helps match up buyers and sellers. This proposal follows the common practices of trading sites such as Craigslist, eBay and newspaper classifieds.

If hReview is about an item and what you think of it, h-listing is about an item and what you want to do with it.

Inspiration and Acknowledgments

Thanks to everyone who participated in the initial burst of hListing activity in August 2005, particularly Emiliano Martínez Luque and Trevor O'Reilly, for naming the effort and organizing the listing-{brainstorming, formats, examples} pages on the wiki. We would like to thank Tantek for an initial debate about whether to extend hReview or pursue an independent-though-similar hListing and later on, h-Listing for our proposal.

Format

In General

The h-listing format is based on a set of fields common to numerous listing sites and formats in use today on the web. Where possible field names have been chosen based on those defined by the related hReview, hCard, hCalendar standards.

Properties

(Not yet finished)

The class h-listing is a root class name that indicates the presence of an h-Listing.

• h-listing: root
  • p-lister: h-card
  • dt-listed: datetime, optional
  • dt-expired: datetime, optional
  • p-price: text, optional (should include a floating-point number with optional ISO currency codes)
  • p-category: text, optional, zero or more
  • p-action: text, optional, one of the following values
    • sell, rent, trade, meet, announce, offer, wanted, event, service
  • u-url

Summary of Changes

• Modified to use microformats-2.
• The version property from hListing has been deprecated. No hListing markup (even in example files used by parsers) has ever been presented that actually uses the version property, nor any enumeration of valid values. No other microformat thus far has had a version property, and explicit versioning seems like clumsy design: any future changes to the specification should be made in such a way as to support existing content and degrade gracefully per the design principles of HTML.
• The dtlisted and dtexpired properties are prefixed with dt- in microformats2 anyway, so no duplication of the dt is needed.
• lister must contain an embedded h-card object for simplicity—the microformats-2-parsing specification would need to be modified to specify any optimisations there.
• The use of rel-tag has been deprecated due to the rel attribute being defined as document scoped in HTML5. Following on from the example of h-entry, category seems the ideal mapping.
• permalink has been replaced with url following h-entry.

Property Details

h-Listing property details:

Authoring guidelines

action type internationalisation

One issue with hard-coded action types is it prevents internationalisation.

The p- value parsing algorithm can be used to provide an alternative text description in a non-English language, at the cost of introducing invisible data.

For instance, one could use a data element.

<section class="h-listing" lang="fr">
  <h1><data class="action" value="sale">À vendre</data>! <span class="summary">Belle usine widget pour produire widgets magique et révolutionnaire</span></h1>
</section>

Examples

Challenges and problems

See h-Listing Challenge Problems for some hypothetical examples that illustrate corners of the specification.

• If no action is specified, should parsers assume the 'sale' property? A listing with no action seems less than useful.

Examples in the Wild

This section is informative.

The following sites have implemented h-listing, and thus are a great place to start for anyone looking for examples "in the wild" to try parsing, indexing, organizing etc. If your site is marked up with hListing, feel free to add it to the top of this list. Include both a URL to the top level site, and at least one URL to a specific hListing item on that site so that the hListing markup can be verified.

Once the list grows too big, we'll make a separate wiki page like h-listing-examples-in-wild.

implementations

Please add links to sites that consume h-listings, and tools which generate h-listings.

• ...

Background

Unlike hCard, hCalendar, hReview and other microformats, hListing has not been nearly as widely adopted. A number of inconsistencies and unclear properties has led to difficulty by page authors to implement the microformat.

Discussions

• Feedback is encouraged on the h-listing-feedback page.

Internationalization

Internationalization: Though there are many English-language tokens, they are only used as class-names; user-visible listing information can be completely localized. N.b. that (X)HTML lang attribute rules still apply as usual, for multilingual aggregators of h-Listings.

See also

• h-listing, a draft reboot of hListing based on microformats-2
• h-listing-issues
• h-listing-feedback
• h-listing-brainstorming
• commerce-examples
• currency proposal