hproduct: Difference between revisions

Revision as of 04:59, 7 April 2013

<entry-title>hProduct</entry-title> 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.

hProduct is a microformat suitable for publishing and embedding product data. hProduct is one of several open microformats standards suitable for embedding in HTML, XHTML, Atom, RSS, and arbitrary XML.

hProduct Microformat Draft Specification

Editors/Authors

(alphabetical)

Paul Lee, Google Product Search
Jay Myers, Best Buy, Co., Inc.

Contributors

(alphabetical)

Craig Cook, Focal Curve
Aaron Gustafson, Easy! Designs

Microformats copyright and patents statements apply.

Status

Draft, version 0.3.

Introduction

The web is a thriving consumer marketplace with a plethora of manufacturers and vendors scattered across the globe. Sifting through massive amounts of unstructured product data is a difficult task for both browsers and machines alike. The hProduct microformat gives structure to this metadata by providing constructs to identify universal product attributes, plus a mechanism to accomodate the wide variation in product attributes.

The hProduct microformat can assist consumers, manufacturers and retailers in a number of ways. If a browser or application understands that a specific web page contains the hProduct microformat, it can inform and help facilitate the best product choice by the consumer to fulfill their needs. An adopted, open standard will ensure the correct product data is published between manufacturers and retailers, to the benefit of the consumer. Bringing order and structure to product data makes it easy for people and organizations to list the products and services they offer, and easy for web services to consume that product data for analysis and syndication.

Semantic XHTML Design Principles

XHTML is built on XML, and thus XHTML-based formats can be used not only for convenient display presentation, but also for general-purpose data exchange. In many ways, XHTML-based formats exemplify the best of both HTML and XML worlds. However, when building XHTML-based formats, it helps to have a guiding set of principles.

Reuse the schema (names, objects, properties, values, types, hierarchies, constraints) as much as possible from pre-existing, established, well-supported standards by reference. Avoid restating constraints expressed in the source standard. Informative mentions are ok.
1. For types with multiple components, use nested elements with class names equivalent to the names of the components.
2. Plural components are made singular, and thus multiple nested elements are used to represent multiple text values that are comma-delimited.
Use the most accurately precise semantic XHTML building block for each object etc.
Otherwise use a generic structural element (e.g. <span> or <div>), or the appropriate contextual element (e.g. an <li> inside a <ul> or <ol>).
Use class names based on names from the original schema, unless the semantic XHTML building block precisely represents that part of the original schema. If names in the source schema are case-insensitive, then use an all lowercase equivalent. Components names implicit in prose (rather than explicit in the defined schema) should also use lowercase equivalents for ease of use. Spaces in component names become dash '-' characters.
Finally, if the format of the data according to the original schema is too long and/or not human-friendly, use <abbr> instead of a generic structural element, and place the literal data into the 'title' attribute (where abbr expansions go), and the more brief and human-readable equivalent into the element itself. Further informative explanation of this use of <abbr>: Human vs. ISO8601 dates problem solved

Inspiration and Acknowledgment

Many thanks go out to the contributors who laid the foundation for the current hProduct draft spec.

Scope

Giving details about a particular product is sometimes very complex as parameters are different for books and CDs than they are for iPods or cars. It should be very easy to mark up an item using hProduct and the syntax should be simple yet flexible enough for more advanced applications.

Out of Scope

This microformat does not intend to replicate any of the content proposed within hListing and would defer all money/transactional matters to that microformat. This microformat also does not attempt to specify a product ontology, or category-specific attributes; instead, it aims to create a framework to allow for flexible expression of both.

Format

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

In General

The hProduct format is based on a set of fields common to numerous ecommerce sites and formats in use today on the web.

Schema

The hProduct schema consists of the following (see existing class names for reference):

hproduct
- brand. optional. text. can also use hCard for manufacturer.
- category. optional. text. can also use rel-tag. re-used from hCard.
- price. optional. floating point number. can use currency format.
- description. optional. text. can also include valid HTML markup. re-used from hReview.
- fn. required. text. product name or title. re-used from hCard.
- photo. optional. image element or link. re-used from hCard.
- url. optional. href. can contain rel-tag rel='product'. re-used from hCard.
- review. optional. hReview, or hReview-aggregate.
- listing. optional. hListing, or hListing-aggregate.
- identifier. optional.
  - type. required. - examples:
    - model
    - mpn
    - upc
    - isbn
    - issn
    - ean
    - jan
    - sn
    - vin
    - sku
  - value. required. - label may be implied

Field details

Class names category, fn, photo, url are reused from hCard. description is reused from hReview.

The fields of the hProduct schema represent the following:

hproduct:: Root class name
brand:: the class name brand is used identify brand of the product. SHOULD use hCard for manufacturer name. MUST be singular.
category:: the class name category identifies product category. MAY use rel-tag microformat. MAY be plural to represent multiple categories.
price:: the class name price is used to indicate the price of the product. MUST be singular.
description:: the class name description is used to describe the product. MUST be singular.
fn:: product text name. MUST be singular.
photo:: the class name photo MAY be applied to an <img> or <a> element. MAY be plural.
url:: the class name url SHOULD refer to the web page associated with product details. MAY use rel-tag, rel='product'. MUST be singular.
review:: the class name review identifies review(s) for the product. SHOULD use hReview. MAY be plural.
listing:: the class name listing identifies product listings. SHOULD use hListing. MAY be plural.
identifier:: the identifier structure is used to describe product identifiers like Model, UPC or SKU, and is designed to accommodate new or as-yet-unidentified identifiers. SHOULD be singular.
- type:: the class name type identifies the identifier type.
- value:: label MAY be implied

Additional Details

Note: If hProduct markup is used in a "standalone" fashion (eg. a manufacturer site that's not commerce enabled, strictly informational), it is assumed that the price attribute represents the manufacturer's suggested retail price. Any transactional (commerce) representation of price should be delegated to hListing.

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

Relationships with other microformats

Products can be complex structures with attributes and features that may fall outside the bounds of the proposed hProduct microformat. Care has been taken to provide just enough attributes to accurately represent products while not overloading the hProduct spec. This means that complete semantic solutions would rely on using hProduct in combination with other microformats to achieve their goals. Through examples (see also: recipes) and analysis, there are some clear relationships between hProduct and these microformats:

hListing :: provides additional context to the transaction side of a product, including elements like the transactional price.
hReview/hAggregate(concept) :: research shows that many commerce sites include product reviews, and they are often aggregated to provide overall ratings and reviews on the web. Utilizing these microformats can provide additional data around a product or service.
xoxo :: to address property-value data that may be necessary for a complete data representation of a product.

Of course, these are just a few of many that could be used with the hProduct microformat.

XMDP Profile

<dl class="profile">
	<dt>class</dt>
	<dd><p>
  <a rel="help" href="http://www.w3.org/TR/html401/struct/global.html#adef-class">
   HTML4 definition of the 'class' attribute.</a>
  This meta data profile defines some 'class' attribute values (class names) 
  and their meanings as suggested by a 
  <a href="http://www.w3.org/TR/WD-htmllink-970328#profile">
   draft of "Hypertext Links in HTML"</a>.</p>
	<dl>
		<dt>hproduct</dt>
		<dd>Used to identify and describe metadata universally common to products.</dd>
		<dt>brand</dt>
		<dd>The brand name of the product.</dd>
		<dt>category</dt>
		<dd>The product category/ categories the product belongs to.</dd>
		<dt>price</dt>
		<dd>The price of the product.</dd>
		<dt>description</dt>
		<dd>The full text representing the written description of the product.</dd>
		<dt>fn</dt>
		<dd>The common name of the product.</dd>
		<dt>photo</dt>
		<dd>Accompanying image of the product.</dd>
		<dt>url</dt>
		<dd>A link to the product details.</dd>
		<dt>review</dt>
		<dd>A review of the product.</dd>
		<dt>listing</dt>
		<dd>Listing details of the product.</dd>
		<dt>identifier</dt>
		<dd>The product identifier like Model, SKU, ISBN, or EAN associated with the product</dd>
	</dl>
	</dd>
</dl>

Notes

This section is informative.

...

Examples

need actual simple demonstration hProduct examples here! (not examples of what actual sites are doing - that's the next section)

Editors: please see http://microformats.org/wiki/hrecipe#Examples for example of an example in spec.

...

Examples in the wild

This section is informative.

Sites and pages that publish hProducts.

See hProduct Examples in the wild.

Implementations

This section is informative.

Tools for generating and consuming hProducts. When it gets too big we can move it to a separate page like hproduct-implementations.

Google parses some hProduct properties and adds extensions:

An example is a HP printer product page parsed with the help of Google Rich Snippets Tool: HP Printer Product from which Google extracted the following hProduct elements:

hproduct
   availability = In stock
   fn = HP Officejet 6000 Wireless Printer
   identifier
      type = SKU
      value = C9295A#B1H
   price = $119.99
   review hreview-aggregate
      item fn = HP Officejet 6000 Wireless Printer
      rating
         average (normalized to 5.0 scale) = 3.5
         average = 3.4
   count = 69

The "availability" extension was added by Google to further improve details about the availability of a product when it's listed. Google also provides the "availability" values reference:

- out_of_stock 
- in_stock 
- instore_only 
- preorder

The "availability" value can be typed in without the linking underscores, to reduce the visual impact e.g.:

    <span class="availability">In stock</span>

Karniyarik.com [1] is a vertical search engine for online goods and has experimental hProduct support.
...

Copyright

JayMyers: I release all of my contributions to the public domain.

Public Domain Contribution Requirement. Since the author(s) released this work into the public domain, in order to maintain this work's public domain status, all contributors to this page agree to release their contributions to this page to the public domain as well. Contributors may indicate their agreement by adding the public domain release template to their user page per the Voluntary Public Domain Declarations instructions. Unreleased contributions may be reverted/removed.

Patents

This specification is subject to a royalty free patent policy, e.g. per the W3C Patent Policy, and IETF RFC3667 & RFC3668.