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 "item"
attribute on an element:

   <div item></div>

This makes the <div> element declare a list of name-value pairs,
though it is an empty list. The name-value pairs are then put inside
this element. It can be any element, not just <div>:

   <span item></span>
   <p item></p>

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

   itemprop="Name"

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

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

For datetimes, use <time>:

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

For strings, you can either use <meta>:

   <meta itemprop="Name" content="String">

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

   <span itemprop="Name">String</span>
   <p itemprop="Name">String</p>
   <div itemprop="Name">String</div>

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

   <div itemprop="Name" item>
     <!-- nested name-value pairs go here -->
   </div>


Examples
--------

This snippet:

   <div item>
    <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 item>
    <p itemprop="author" item>
     <span itemprop="name">Fred Smith</span>
     (<span itemprop="age">28</span>)
    </p>
    <p itemprop="author" item>
     <span itemprop="name">John Carey</span>
     (<span itemprop="age">35</span>)
    </p>
    <p itemprop="publisher" item>
     <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
------------

The "item" attribute can be given a value, which specifies the kind of
list of name-value pairs being described. For example, it could be a
"review", or a "business card", or a "licensed work". The actual
values are URLs.

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 item="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:

   http://example.com/animal (describes an animal species)
     image: A URL to an image of an animal of the species (URL)
     itemid: A URL that can be used to refer to the species (URL)

   http://n.vii.org/vEvent (describes a calendar event)
     summary: The name of the event (text)
     dtstart: The time of the start of the event (datetime)
     location: The location of the event (text)

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

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

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

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):

   http://wiki.tdwg.org/twiki/bin/view/DarwinCore/ScientificName
   The scientific name of the item being described (text)

   http://flickr.com/ns/camera
   The name of the camera used to take the picture, if applicable (text)

   http://flickr.com/ns/pubdate
   The datetime that the resource was obtained, if applicable (datetime)

   http://technorati.com/tag
   A tag that applies to the item being described (URL)


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

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

   <p item="http://n.vii.org/vcard">
    <span itemprop="fn">Fred Smith</span> is 28 years old.
   </p>
   <p>
    <span item="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
item="", and then the itemfor="" attribute can be given with the
itemprop="" attribute to associate them together:

   <p item="http://n.vii.org/vcard" id="fred">
    <span itemprop="fn">Fred Smith</span> is 28 years old.
   </p>
   <p>
    <span item="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 itemfor="fred" 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

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