MICRODATA
=========

Overview
--------

Microdata allows you to layer lists of name-value pairs on top of Web
pages, so that JavaScript scripts, search engines, and other tools can
extract that data from the page directly, instead of you having to
provide it in a separate file, or them having to use screen scraping.

Note: The URLs used in this study are completely arbitrary and do not
really mean anything. Please don't be tempted to actually visit those
pages, that won't be helpful!


Data structures
---------------

The data structures that can be described using metadata are lists of
name-value pairs.

   Name: Value
   Foo: Bar

Each value can be one of several types: strings, URLs, datetimes, or
further nested lists of name-value pairs:

   Strings: Just some regular text
   URLs: http://example.com/
   Datetimes: 2009-04-01T14:23-08:00
   Lists of name-value pairs:
       Name: Value
       Foo: Bar

Each name can have multiple values:

   Color: Blue
   Color: Green
   Color: http://example.com/yellow


Syntax
------

To declare a list of name-value pairs in HTML, put the "itemscope"
attribute on an element:

   <div itemscope=""> ... </div>

This makes the <div> element declare that its contents are a list of
name-value pairs. The name-value pairs are then put inside this
element. It can be any element, not just <div>:

   <span itemscope=""> ... </span>
   <p itemscope=""> ... </p>

To declare a name in a name-value pair, you use the itemprop=""
attribute on elements inside the one with the itemscope="" attribute:

   itemprop="name"

The values you're allowed to use on itemprop="" are listed below,
under "Predefined Vocabularies". You cannot just make up names on a
own whim, otherwise nobody else would know what they meant!

Declaring a value is done in various ways depending on what the value
is. For URLs, use <link>, <img>, or <a>:

   <div itemscope="">
    <link itemprop="name" href="http://example.com/">
    <img itemprop="name" src="http://example.com/">
    <a itemprop="name" href="http://example.com/"> ... </a>
   </div>

For datetimes, use <time>:

   <div itemscope="">
    <time itemprop="dtstart" datetime="1999-12-31T02:45-08:00"> ... </time>
   </div>

For strings, you can either use <meta>:

   <div itemscope="">
    <meta itemprop="name" content="string">
   </div>

...or use any element other than the above, and put the value in the
contents:

   <div itemscope=">
    <span itemprop="name">string</span>
    <p itemprop="name">string</p>
    <div itemprop="name">string</div>
   </div>

For nested lists of name-value pairs, declare the scope nested list of
name-value pairs, using itemscope="", on the same element as you put
the itemprop="" attribute:

   <div itemscope="">
    <!-- outer list of name value pairs -->
    <div itemprop="contact" itemscope="">
     <!-- nested name-value pairs go here -->
     <meta itemprop="name" content="string">
    </div>
   </div>


Examples
--------

This snippet:

   <div itemscope="">
    <img itemprop="image" src="muse.jpeg" alt="">
    <span itemprop="title">The Muse in a Hat</span>
    <p>Published on: <time itemprop="pubdate" datetime="2009-12-31T00:00-08:00">December
    31st 2009, at midnight</time>.</p>
   </div>

...contains this list of name-value pairs:

   image: muse.jpeg
   title: The Muse in a Hat
   pubdate: 2009-12-31T00:00-08:00


This snippet:

   <div itemscope="">
    <p itemprop="author" itemscope="">
     <span itemprop="name">Fred Smith</span>
     (<span itemprop="age">28</span>)
    </p>
    <p itemprop="author" itemscope="">
     <span itemprop="name">John Carey</span>
     (<span itemprop="age">35</span>)
    </p>
    <p itemprop="publisher" itemscope="">
     <span itemprop="company">Sage Ojing Publishers</span>,
     <span itemprop="location">London</span>
    </p>
    ISBN: <span itemprop="isbn">0-123-123456789</span>
   </div>

...contains this list of name-value pairs:

   author:
     name: Fred Smith
     age: 28
   author:
     name: John Carey
     age: 35
   publisher:
     company: Sage Ojing Publishers
     location: London
   isbn: 0-123-123456789


Vocabularies
------------

Each list of name-value pairs can be annotated with the kind of list
of name-value pairs being described, using the itemtype=""
attribute. For example, it could be a "review", or a "business card",
or a "licensed work". The actual values are URLs, taken from the list
of predefined vocabularies given below.

Each of these defines a vocabulary, which then defines what terms can
be used as names in the name-value pair list.

For example, this:

   <p itemscope="" itemtype="http://example.com/animal">
    <a itemprop="itemid" href="http://en.wikipedia.org/wiki/Dog">
     <img itemprop="image" src="dog.jpeg" alt="">
     <span itemprop="name">Dogs</span>
    </a>
   </p>

...declares a list of name-value pairs with the type
"http://example.com/animal", whose name-value pairs are:

   itemid: http://en.wikipedia.org/wiki/Dog
   image: dog.jpeg
   name: Dogs


Predefined Vocabularies
-----------------------

For the purpose of this exercise, the following possible item types
exist, with the following valid names and expected values:

   itemtype="http://example.com/animal": describes an animal species
     itemprop="itemid": A URL that uniquely identifies the species
     itemprop="image": A URL to an image of an animal of the species

   itemtype="http://n.vii.org/work": describes a licensed work
     itemprop="itemid": A URL that can be used to refer to the work
     itemprop="author": The name of the author
     itemprop="license": A URL to the license
     itemprop="title": The title of the work
     itemprop="description": The description of the work

   itemtype="http://n.vii.org/vEvent": describes a calendar event
     itemprop="summary": The name of the event
     itemprop="dtstart": The time of the start of the event
     itemprop="location": The location of the event

   itemtype="http://n.vii.org/vcard": describes a person or organisation
     itemprop="fn": The full name of the person
     itemprop="fn org": The full name of the organisation
     itemprop="adr" itemscope="": The address, as a nested list of
       name-value pairs with no explicit type but with the following
       names given:
         itemprop="street-address": The street address
         itemprop="locality": The city of the address
         itemprop="region": The state of the address
         itemprop="postal-code": The ZIP code of the address
     itemprop="tel": The telephone number

   itemtype="http://open-vocabulary.org/review": describes a product
     itemprop="itemid": A URL that identifies the product
     itemprop="name": The name of the product
     itemprop="price": The price of the product
     itemprop="price-range": The expected price range for the product
     itemprop="rating": The review's rating, a number from 0.0 to 5.0
     itemprop="weight": The product's weight, with units
     itemprop="category": The URL to the relevant product category
     itemprop="image": An image of the product
     itemprop="contact" itemscope="": The person or organisation to
       contact regarding the product, as a nested list of name-value
       pairs; include itemtype="http://n.vii.org/vcard"
     itemprop="kids": Whether kids are allowed
     itemprop="takeout": Whether takeout is available
     itemprop="outdoor-seating": Whether outdoor seating is available
     itemprop="attire": What kind of attire is needed to attend
     itemprop="parking": What kind of parking is available

In addition, the following names can always be used as a name in any
list of name-value pairs (their names are unique URLs so there's no
danger they will clash with other names):

   itemprop="http://wiki.tdwg.org/twiki/bin/view/DarwinCore/ScientificName"
   The scientific name of the item being described

   itemprop="http://flickr.com/ns/camera"
   The name of the camera used to take the picture, if applicable

   itemprop="http://flickr.com/ns/pubdate"
   The datetime that the resource was obtained, if applicable

   itemprop="http://technorati.com/tag"
   A tag that applies to the item being described


Indirect references
-------------------

Sometimes, the value part of a name-value pair is not inside the
element that has the item="" attribute. For example:

   <p itemscope="" itemtype="http://n.vii.org/vcard">
    <span itemprop="fn">Fred Smith</span> is 28 years old.
   </p>
   <p>
    <span itemscope="" itemtype="http://n.vii.org/vcard">Fred has a
    child named <span itemprop="fn">George Smith</span> who is 5 years
    old.</span>
    Fred's phone number is <span itemprop="tel">0181 811 8181</span>
    <!-- this is wrong: the phone number isn't part of the first item! -->
   </p>

In this example, Fred's phone number in the second paragraph isn't
associated with Fred in the first paragraph.

To get around this, the id="" attribute can be used to name the orphan
itemprop="", and then the <itemref ref="..."> element can be given to
reference the orphan itemprop="" or one of its ancestors from the
original itemscope="":

   <p itemscope itemtype="http://n.vii.org/vcard">
    <span itemprop="fn">Fred Smith</span> is 28 years old.
    <itemref ref="fred-phone">
   </p>
   <p>
    <span itemscope="" itemtype="http://n.vii.org/vcard">Fred has a
    child named <span itemprop="fn">George Smith</span> who is 5 years
    old.</span>
    Fred's phone number is <span id="fred-phone" itemprop="tel">0181
    811 8181</span>
   </p>

There are two lists of name-value pairs here, both of type
"http://n.vii.org/vcard"; the first has these name-value pairs:

   fn: Fred Smith
   tel: 0181 811 8181

...and the second has just:

   fn: George Smith

------------------------------------------------------------------------