hlisting: Difference between revisions

From Microformats Wiki
Jump to navigation Jump to search
(could not find any hListing at the given anitaclarkrealtor URL, and also undoing edits that errantly deleted some content)
No edit summary
Line 1: Line 1:
<entry-title> hListing draft </entry-title>
HOW THING THROUGH
{{DraftSpecification}}
HOW MAKE THING THROUGH
 
HOW THING BE THROUGH
hListing is a proposal for an open, distributed listings ([[en-uk|UK English]]: small-ads; classifieds) format suitable for embedding in (X)HTML, Atom, RSS, and arbitrary XML. hListing would be one of several [[microformats]] open standards.
HOW MAKE THING BE THROUGH
 
HOW ANYTHING THROUGH
== Draft Proposal ==
HOW MAKE ANYTHING THROUGH
===Editors===
HOW ANYTHING BE THROUGH
* [[User:Tantek|Tantek Çelik]]
HOW MAKE ANYTHING BE THROUGH
* [[User:Rohit|Rohit Khare]]
HOW EVERYTHING THROUGH
 
HOW MAKE EVERYTHING THROUGH
===Authors and Contributors===
HOW EVERYTHING BE THROUGH
* Assaf Arkin, [http://blog.labnotes.org/ Labnotes]
HOW MAKE EVERYTHING BE THROUGH
* Craig Donato, [http://oodle.com/ Oodle]
HOW UNIVERSE THROUGH
* Ryan King
HOW MAKE UNIVERSE THROUGH
 
HOW UNIVERSE BE THROUGH
==Introduction==
HOW MAKE UNIVERSE BE THROUGH
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.
HOW THING OUT
 
HOW MAKE THING OUT
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.
HOW THING BE OUT
 
HOW MAKE THING BE OUT
If [[hreview|hReview]] is about an item and what you think of it, hListing is about an item and what you want to ''do'' with it.
HOW ANYTHING OUT
 
HOW MAKE ANYTHING OUT
=== Inspiration and Acknowledgments ===
HOW ANYTHING BE OUT
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 for our proposal.
HOW MAKE ANYTHING BE OUT
 
HOW EVERYTHING OUT
=== Scope ===
HOW MAKE EVERYTHING OUT
Vibrant online marketplaces have been launched with little more than titles, prices, descriptions, and contact email addresses; we hope to kindle the same spirit of minimalism with this proposal to restart active discussion of what an hListing should be. Since we are venturing into a space that does not have “settled law” such as the vCard definitions hCard started with, we were inspired by hReview, another novel compound microformat that emerged from the microformats.org community process.
HOW EVERYTHING BE OUT
 
HOW MAKE EVERYTHING BE OUT
In particular, we note that both applications need a way to share informative descriptions of a product or service, including attribution of authorship and provenance of the item. if hReview is a microformat for one's opinion of a product or service, hListing helps share what one would like to ''do'' with it:  sell it, rent it, trade it, perform that service, announce it, or, for people, to meet them. It can tell you how to contact the lister, and whether it is an item on offer or a wanted ad.
HOW UNIVERSE OUT
 
HOW MAKE UNIVERSE OUT
==== Out of Scope ====
HOW UNIVERSE BE OUT
We are focusing on providing "just enough" structure to enable matching, not to consummate transactions. This is distinct from the majority of formats described on the wiki under [[listing-examples]], which are specific enough to completely describe products for retail sale according to the idiosyncratic semantics of particular merchants and shopping engines. Instead of encoding retail-oriented fields such as UPCs, SKUs, and manufacturer part numbers, this proposal acknowledges that many listings are for "inventories of one" that may not have such precise abstractions.
HOW MAKE UNIVERSE BE OUT
 
HOW THING THROUGH
Similarly, listings cannot aspire to describe prices and terms & conditions to the degree necessary to automate entire transactions or price comparisons. Some have terms beyond the pale of any B2B exchange protocols (e.g. "$50 ''obo''").
HOW MAKE THING THROUGH
 
HOW THING BE THROUGH
As in hReview, the concept of a "universal object identifier" is also out-of-scope for this effort. Unlike some of the "product feed" formats under [listing-examples], we avoided specifying any taxonomy for identifying or categorizing listings in favor of tags.
HOW MAKE THING BE THROUGH
 
HOW ANYTHING THROUGH
== Format ==
HOW MAKE ANYTHING THROUGH
=== In General ===
HOW ANYTHING BE THROUGH
The hListing 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|hReview]], [[hcard|hCard]], [[hcalendar|hCalendar]] standards.
HOW MAKE ANYTHING BE THROUGH
 
HOW EVERYTHING THROUGH
=== Schema ===
HOW MAKE EVERYTHING THROUGH
An hListing schema should consist of the following:
HOW EVERYTHING BE THROUGH
 
HOW MAKE EVERYTHING BE THROUGH
* hListing
HOW UNIVERSE THROUGH
** version. optional. text.
HOW MAKE UNIVERSE THROUGH
** '''listing action'''. one or more tags, suggested set: ''sell'' | ''rent'' | ''trade'' | ''meet'' | ''announce'' | ''offer'' | ''wanted'' | ''event'' | ''service''
HOW UNIVERSE BE THROUGH
** '''lister'''. required.  [[hcard|hCard]] | (fn || email || url || ''tel'').
HOW MAKE UNIVERSE BE THROUGH
** ''dtlisted''. optional. ISO8601 absolute date time.
HOW THING OUT
** ''dtexpired''. optional. ISO8601 absolute date time.
HOW MAKE THING OUT
** ''price''. optional. text. [should include a floating-point number with optional ISO currency codes].
HOW THING BE OUT
** item info. '''required'''. (fn || url || photo || [[geo]] || [[adr]]) |  [[hcard|hCard]] (for person or business).
HOW MAKE THING BE OUT
** summary. optional. text.
HOW ANYTHING OUT
** description. '''required'''. text with optional valid XHTML markup.
HOW MAKE ANYTHING OUT
** item tags. optional. keywords or phrases describing the item being offered, using [[rel-tag]]
HOW ANYTHING BE OUT
** permalink. optional.
HOW MAKE ANYTHING BE OUT
 
HOW EVERYTHING OUT
==== Summary of Changes ====
HOW MAKE EVERYTHING OUT
By comparison to hReview:
HOW EVERYTHING BE OUT
* Item type and info have been preserved to describe the good, service, or person being offered.
HOW MAKE EVERYTHING BE OUT
* Item info expanded to take geo or adr for location of the item.
HOW UNIVERSE OUT
* Item description has become required, rather than item info or type. While reviews tend to apply to a range of products, listings "in the wild" can be ''sui generis,'' found with only a description and no other structured information.
HOW MAKE UNIVERSE OUT
* Rating has been removed.
HOW UNIVERSE BE OUT
* Lister, unlike Reviewer, can also have a telephone number -- but it must ''either'' be an hCard or the other fields.
HOW MAKE UNIVERSE BE OUT
 
Creating a listing requires adding transaction metadata:
* Type of transaction sought: whether the lister has or wants an item (sale or rent), a service, an opening, or a personal introduction.
* Dates of listing and expiry. Once taken, listings may be reposted with a modified dtexpired.
* Price has been called out specifically as an independent text field. It can include some terms & conditions.
 
==Field Details==
The fields of the hListing schema represent the following:
 
'''version''':: This optional field permits hListing publishers to specify a particular version of hListing that their content uses. By omitting this field, the publisher is stating that implementations may interpret the hListings according to any version of the hListing specification. The value for this proposal as of 6-Feb-2006 is "0.0," since it has no official standing yet.
 
===Transaction Metadata===
'''listing type''':: This required field indicates the desired matching: whether it’s about something that the lister has (offer) or wants (wanted).  '''NOTE: This needs to be collapsed with listing action per the change made to the summary above.'''
 
'''listing action''':: This required field indicates the desired action for the listing: a permanent transfer (sale); transient use (rent); barter or donation (trade); to arrange an introduction (meet); publicize the existence of an event or vendor (announce); or to perform a service (service).
 
'''lister''':: The person or business who should be contacted about the listing, either in the form of an hCard or a shorthand notation of one or more formatted names (fn) and contact information (email, url, tel). Note that this is not necessarily the same as the ''author'' of the listing.
 
'''dtlisted''':: This optional field MUST provide an ISO8601 absolute date time of when the listing was first made effective. This field SHOULD use UTC, but MAY use the time zone offset syntax. See [[datetime-design-pattern|datetime design pattern]].
 
'''dtexpired''':: This optional field MUST provide an ISO8601 absolute date time of when the listing will become ineffective. It MUST be later than dtlisted. This field SHOULD use UTC, but MAY use the time zone offset syntax. See [[datetime-design-pattern|datetime design pattern]].
 
<blockquote>
Note that this definition obviates the need for a “taken” listing action; when a listing is no longer valid, it can simply be deleted, or republished with an expiry date that has already passed. Republication may be desirable, to indicate that the listing is no longer available to forestall further inquiries. Keeping expiry orthogonal to listing-action permits archival use of web pages with hListings.
</blockquote>
 
'''location''':: This optional field contains the location of the item, which may be different than the location of the lister. This may be a full hCard with contact information, or just an [[adr]] or [[geo]].
 
<blockquote>
There is an separate discussion to be had about how either of these three microformats can best accommodate colloquial terminiology for “neighborhoods,” but this proposal does not break new ground by coining a new fields for that purpose.
</blockquote>
 
'''price''':: This optional text field describes the “advertised” price of the listing; it is not a binding offer, nor a complete transaction price. Floating point numbers found within this string may be extracted for sorting/indexing, as could adjacent currency symbols or ISO currency codes.
 
<blockquote>
Note that since price is such a general description, we have avoided promoting an additional “terms and conditions” field for elaborating on the price or terms of the deal (e.g.  “dollars”, “best offer” “per month” “paypal only”). We suggest demoting it until proven that it needs to exist independently of either description (such as shipping rates) or price (which can just state “CAD$22/mo”).
</blockquote>
 
===Item Metadata===
'''item type''':: This optional field "type" provides the type of the item being ''listed'': one of the following: opening, housing, product, business, event, person, place, website, url.
 
<blockquote>
Note that the first two, housing and opening, are new and unique to hListing; the remainder are copied by reference from hReview. Similar to the note in hReview 0.2 for item types, the enumerated list of listing types is  “under development and may be extended.”
</blockquote>
 
'''item info''':: This required field MUST have at a minimum the name ("fn" - the formatted text corresponding to the name) of the item , SHOULD provide at least one URI ("url") for the item, and MAY provide at least one URL to a photo or depiction ("photo") of the item. For items of type person or business, the item info (fn, url, photo) SHOULD be encapsulated in an hCard. Unique item IDs (e.g. ISBNs, UPCs) MAY be represented as a URN ("url") for the item.
 
===Content ===
'''summary''':: This optional text field serves as a title for listing.
 
'''description''':: This required field contains the full text representing the written description of the item being listed. The field MAY include valid XHTML markup (e.g. paragraphs). User agents SHOULD preserve any markup. 
 
'''tags''':: Tags are represented using a list of keywords or phrases (using the [[rel-tag|rel-tag]] microformat for each individual keyword or phrase tag) that the reviewer associates with the item. The reviewer SHOULD provide tags relating to how they want the item categorized (e.g., “car, used, acura”, “job”, “real estate, 3BR”). The reviewer MAY also want to provide tags indicating payment terms (“dollars”, “paypal”).
 
'''permalink''':: This optional field is a URL for the hListing. In addition to using the <a href> tag for this field, the attribute rel="self bookmark" MUST be used to indicate that the hyperlink is a permalink for the review itself. If the hyperlink already contains a rel attribute, then the values self and bookmark MUST be included among the space-separated set of values in the attribute. Indexers MAY treat the permalink of a review as a unique ID in order to identify and collate the same listing from multiple sources (such as indexing a page multiple times). The permalink MAY also be used to indicate or imply the origin of the listing. Authors MAY use the classname of "permalink" on the element representing the permalink, but are not required to do so.
 
===Cross-cutting issues===
''Internationalization:'' Though there are many English-language tokens, they are only used as invisible 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 hListings.
 
The following field names have been reused from the [[hcard|hCard]] and [[hcalendar|hCalendar]] microformats: <code>version, summary, fn, url, email, photo, description, categories</code>.  In addition, items and reviewers described by hCards MAY contain any hCard field.  The rel value "self" has been reused from the [http://atompub.org/2005/07/11/draft-ietf-atompub-format-10.html Atom 1.0 specification].
 
==Contextual Defaults: A New Approach?==
 
Since listings may be embedded within blog postings, email, syndicated feeds, simple Web pages, or other microformats such as hAtom, to the degree possible, the following fields can be “inherited” from the context surrounding an hListing if absent:
 
* lister (author, contributor, From:)
* dtlisted (Date:)
* dtexpired (Expires:)
* summary (title)
* permalink (URI:, <base>)
 
By contrast, gazetteering is an example of ''ad hoc'' contextual defaulting that is '''not''' governed by this technique. Guessing that “Noe Valley” is in “San Francisco, CA” because the hCard of the blog author is in the same city is beyond the pale of the contextual defaulting proposed here. All we are suggesting is application of DRY (“Don’t Repeat Yourself”) for fields that have equivalent definitions elsewhere within the same XHTML document or its MIME headers.
 
See a related discussion on 2006-01-27 on [[hreview-feedback]].
 
==Examples (Preliminary)==
 
=== Simple Listing ===
Parking space for rent (2/2/06)
2 compact car spaces in a secure underground garage at:
1738 Elm St.
Somewhere, ED 34567 ISA
Available in April 2006 for $215/mo
Please contact John Broker at 110.555.1212 (C)
 
<pre><nowiki>
<div class="hlisting">
  <p>
    <span class="item">
        <span class="fn">Parking space</span>
      </span>
    <span class="offer rent">for rent</span>
    (<abbr class="dtlisted" title="20060202">2/2/06</abbr>)
  </p>
  <p class="description">
    2 compact car spaces in a secure underground garage at:
    <div class="location adr">
      <span class="street-address">1738 Elm St.</span>
      <span class="locality">Somewhere</span>, <span class="region">ED</span>
      <span class="postal-code">34567</span> <span class="country">ISA</span>
    </div>
    Available in <abbr class="dtexpired" title="20060401">April 2006</abbr>
    for <span class="price">$215/qtr</span>
  </p>
  <div class="lister vcard">
      Please contact <span class="fn">John Broker</span> at
      <span class="tel"><span class="value">(110) 555-1212</span>
      (<abbr class="type" title="cell">C</abbr>)</span>
  </div>
</div></nowiki> </pre>
 
=== Extended Examples ===
 
See [[hlisting-extended-examples|hListing Extended Examples]] for real-world examples from Craigslist, eBay.com, and Match.com.
 
=== Challenge Problems ===
 
See [[hlisting-challenges|hListing Challenge Problems]] for some hypothetical examples that illustrate corners of the specification.
 
== Examples in the Wild ==
This section is '''informative'''.
 
The following sites have implemented [[hListing]], 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 [[hlisting-examples-in-wild]].
 
 
*[http://www.ooyyo.com Ooyyo.com] vertical search engine for used cars supports hListing.  [http://www.ooyyo.com/used-cars/united+states hListing on listings search]
*[http://www.everycarlisted.com EveryCarListed.com] supports hListing on cars for sale.  [http://www.everycarlisted.com/usa/tx/dallas hListing on cars for sale]
* [http://www.realestate.com RealEstate.com] supports hListing on Real Estate Listings. [http://www.realestate.com/AZ/Phoenix/homes-for-sale.aspx hListing on listings search]
* [http://livres.transcontinental.ca Les &#201;ditions Transcontinental] supports hListing on book items
** needs specific URL to an hListing item
* [http://www.dealtagger.com/ Dealtagger] supports hListing
** needs specific URL to an hListing item
* [http://jobs.emurse.com/ Emurse] supports hListing on job postings
** needs specific URL to an hListing item
* [http://www.imovelweb.com.br Imovelweb] supports hListing on Real Estate Listings. [http://www.imovelweb.com.br/comprar-imoveis/sao-paulo-zona-sul/moema hListing on listings search]
* [http://www.kelkoo.co.uk/ Kelkoo] - a pan-European comparison engines supports hListing to list offers from merchants (the support of hListing has been introduced on the new Kelkoo site launched in September 07)
** needs specific URL to an hListing item
* [http://www.nestoria.co.uk/ Nestoria] - European vertical search engine for property (real estate)
** needs specific URL to an hListing item
* [http://www.netinstruments.com/ Musical Instruments @ Net Instruments] - Global musical instruments database (hListing on item pages)
** needs specific URL to an hListing item
=== past examples ===
* Edgeio  <nowiki>http://www.edgeio.com/</nowiki> produced output with hListings (until sometime in 2007 or 2008 - precise date needed, please lookup edgeio.com at archive.org)
 
== implementations ==
Please add links to sites that consume hListings, and tools which generate hListings.
* ...
 
==Changes==
Substantial (non-editorial) changes:
* 2006 Feb 6: clarified definitions of fields throughout.
* 2006 Feb 5: Reformatted into wiki-markup style.
* 2006 Feb 4: Folded the sense of “taken” into dtexpired, re-imported item type from hReview, and combined action and status. Added an example. Removed anonymous listings, since that is an unlikely use case (pseudonymous, perhaps, but not ''a''nonymous).
* 2006 Jan late: initial conversations started with the insight that hReview does a great job of describing items, and that we could shoehorn in listing semantics using a) magic tags to mean for-sale and b) mapping price onto dimensioned ratings. Tantek correctly nailed this as ''a-priori'' thinking, and encouraged us to start by designing the right spec for listings, and only sharing what was necessary.
 
== Discussions ==
* Feedback is encouraged on the [[hlisting-feedback]] page.
* See also [http://www.technorati.com/cosmos/referer.html blogs discussing this page].
 
== See also==
* [[hlisting-issues]]
* [[hlisting-feedback]]
* [[hlisting-brainstorming]]
* [[commerce-examples]]
* [[currency]] proposal
 
[[Category:Draft Specifications]]

Revision as of 19:34, 25 August 2013

HOW THING THROUGH HOW MAKE THING THROUGH HOW THING BE THROUGH HOW MAKE THING BE THROUGH HOW ANYTHING THROUGH HOW MAKE ANYTHING THROUGH HOW ANYTHING BE THROUGH HOW MAKE ANYTHING BE THROUGH HOW EVERYTHING THROUGH HOW MAKE EVERYTHING THROUGH HOW EVERYTHING BE THROUGH HOW MAKE EVERYTHING BE THROUGH HOW UNIVERSE THROUGH HOW MAKE UNIVERSE THROUGH HOW UNIVERSE BE THROUGH HOW MAKE UNIVERSE BE THROUGH HOW THING OUT HOW MAKE THING OUT HOW THING BE OUT HOW MAKE THING BE OUT HOW ANYTHING OUT HOW MAKE ANYTHING OUT HOW ANYTHING BE OUT HOW MAKE ANYTHING BE OUT HOW EVERYTHING OUT HOW MAKE EVERYTHING OUT HOW EVERYTHING BE OUT HOW MAKE EVERYTHING BE OUT HOW UNIVERSE OUT HOW MAKE UNIVERSE OUT HOW UNIVERSE BE OUT HOW MAKE UNIVERSE BE OUT HOW THING THROUGH HOW MAKE THING THROUGH HOW THING BE THROUGH HOW MAKE THING BE THROUGH HOW ANYTHING THROUGH HOW MAKE ANYTHING THROUGH HOW ANYTHING BE THROUGH HOW MAKE ANYTHING BE THROUGH HOW EVERYTHING THROUGH HOW MAKE EVERYTHING THROUGH HOW EVERYTHING BE THROUGH HOW MAKE EVERYTHING BE THROUGH HOW UNIVERSE THROUGH HOW MAKE UNIVERSE THROUGH HOW UNIVERSE BE THROUGH HOW MAKE UNIVERSE BE THROUGH HOW THING OUT HOW MAKE THING OUT HOW THING BE OUT HOW MAKE THING BE OUT HOW ANYTHING OUT HOW MAKE ANYTHING OUT HOW ANYTHING BE OUT HOW MAKE ANYTHING BE OUT HOW EVERYTHING OUT HOW MAKE EVERYTHING OUT HOW EVERYTHING BE OUT HOW MAKE EVERYTHING BE OUT HOW UNIVERSE OUT HOW MAKE UNIVERSE OUT HOW UNIVERSE BE OUT HOW MAKE UNIVERSE BE OUT

Retrieved from "http://microformats.org/wiki/index.php?title=hlisting&oldid=60718"