data format
authorRobin Berjon <robin@berjon.com>
Fri, 22 Jun 2012 18:03:41 +0200
changeset 123 519c13e6df24
parent 122 49eeb69d402e
child 124 cecfc8b99650
data format
contacts/Overview.html
--- a/contacts/Overview.html	Fri Jun 22 17:05:43 2012 +0200
+++ b/contacts/Overview.html	Fri Jun 22 18:03:41 2012 +0200
@@ -224,118 +224,114 @@
         </li>
         <li>
           If an error of any kind takes place in the service, then an error payload is returned (using
-          <code>postFailure()</code>) matching the error data format defined below. This includes the
-          case in which the user has selected zero contacts.
+          <code>postFailure()</code>) matching the error data format defined below. The <a>contact service</a>
+          MUST NOT treat the user selecting zero contacts or cancelling the service as error conditions.
         </li>
       </ul>
+      <section>
+        <h2>Intent Extras</h2>
+        <p>
+          The Pick Contact Intent can be instantiated with an <code>extras</code> field that adheres to the 
+          following dictionary.
+        </p>
+        <section>
+          <h2>The <a>ContactIntentExtras</a> dictionary</h2>
+          <p>
+            The <a>ContactIntentExtras</a> dictionary describes the options that can be applied to contact searching.
+          </p>
+          <dl title='dictionary ContactIntentExtras' class='idl'>
+            <dt>DOMString? search</dt>
+            <dd>
+              A string which provides a hint to the <a>contact service</a> to facilitate contacts selection by the user.
+              The exact manner in which this hint is exploited is entirely up to the <a>contact service</a>.
+            </dd>
+            <dt>unsigned long? limit</dt>
+            <dd>
+              By default a <a>contact service</a> MAY return as many contacts as the user selects. If <code>limit</code>
+              is specified, the <a>contact service</a> MUST NOT return more than <code>limit</code> contacts. The
+              <a>contact service</a> SHOULD enforce this limitation in the user interface that it exposes.
+            </dd>
+            <dt>DOMString[] fields</dt>
+            <dd>
+              An array of field names corresponding to the name of the fields in the <a>Contact</a> dictionary that
+              the Web application is requesting from the <a>contact service</a>. The <a>contact service</a> MUST
+              NOT return defined fields on the contact objects that it provides other than those present in this
+              list. If a field name is provided that the <a>contact service</a> does not recognise as a field
+              of the <a>Contact</a> dictionary, then it MUST ignore it.
+            </dd>
+          </dl>
+        </section>
+      </section>
     </section>
     <section>
       <h2>Data Format</h2>
       <p>
-        Upon successful invocation, the <a>contact service</a> MUST return an array of <a>Contact</a> objects.
+        Upon successful invocation, the <a>contact service</a> MUST return an array of <a>Contact</a> dictionaries.
       </p>
       <section>
-        <h2><a>Contact</a> </h2>
+        <h2>The <a>Contact</a> dictionary</h2>
         <p>
-          The <a>Contact</a> interface captures the properties of a contact object. All properties included in this 
-          interface have a corresponding definition in [[POCO-SCHEMA]], [[RFC2426]] (aka vCard), and [[OMA-CAB]], thereby
-          allowing the API to be supported across implementations supporting these various contact formats.
-        </p>
-        <p id="ta-ac" class="product-ua">
-          All <a>Contact</a> objects MUST include all attributes supported by the implementation, regardless 
-          of whether these attributes have been assigned a <code>null</code> value or not. If a supported attribute has not been
-          assigned a value by the user or the implementation, then this attribute MUST still be present in the
-          resulting <a>Contact</a> object and MUST have a value of <code>null</code>.
+          The <a>Contact</a> dictionary captures the properties of a contact object. All properties included in this 
+          interface have a corresponding definition in [[POCO-SCHEMA]], [[RFC2426]] (also known as vCard), and 
+          [[OMA-CAB]], thereby allowing the data format to be supported across implementations supporting these 
+          various contact representations.
         </p>
         <p>
           Additional attributes MAY be included according to the provisions detailed in 
-          <a href="#extended-contact-properties-and-parameters">Extended Contact Properties and Parameters</a>. If an
-          extended attribute is supported by the current implementation and has not been assigned a value by the
-          user or the implementation, then this extended attribute MUST still be present in the resulting
-          <a>Contact</a> object and MUST have a value of <code>null</code>.
+          <a href="#extended-contact-properties-and-parameters">Extended Contact Properties and Parameters</a>.
         </p>
-
-        <!-- XXX make this a dictionary -->
-        <dl title='[NoInterfaceObject] interface Contact' class='idl'>
-          <dt>readonly attribute DOMString id</dt>
-          <dd>
-            <p>
-              A globally unique identifier for the given <a>Contact</a> object. 
-            </p>
-            <p>
-              An implementation MUST maintain this globally unique identifier when a <a>Contact</a> is added
-              to an address book.
-            </p>
-          </dd>
-          <dt>attribute DOMString? displayName</dt>
-          <dd>
-            <p>
-              This attribute contains the name of this <a>Contact</a> in a form that is suitable for display 
-              to the user.
-            </p>
-          </dd>
-          <dt>attribute ContactName? name</dt>
-          <dd>
-            <p>
-              This attribute represents the full name of this <a>Contact</a> indicated by the name components 
-              associated with the <a>ContactName</a> object.
-            </p>
-          </dd>
-          <dt>attribute DOMString? nickname</dt>
-          <dd>
-            <p>
-              This attribute contains the nickname (or a casual name) for this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute ContactField[]? phoneNumbers</dt>
+        <dl title='dictionary Contact' class='idl'>
+          <dt>DOMString id</dt>
           <dd>
-            <p>
-              This attribute captures one or more phone numbers associated with this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute ContactField[]? emails</dt>
-          <dd>
-            <p>
-              This attribute represents one or more email addresses associated with this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute ContactAddress[]? addresses</dt>
-          <dd>
-            <p>
-              This attribute represents one or more physical addresses associated with this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute ContactField[]? ims</dt>
-          <dd>
-            <p>
-              This attribute represents one or more instant messaging identifiers associated with this
-              <a>Contact</a>.
-            </p>
+            A globally unique identifier for the given <a>Contact</a> object. 
           </dd>
-          <dt>attribute ContactOrganization[]? organizations</dt>
-          <dd>
-            <p>
-              This attribute represents one or more organizations associated with this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute Date? birthday</dt>
+          <dt>DOMString? displayName</dt>
           <dd>
-            <p>
-              This attribute contains birthday of this <a>Contact</a>.
-            </p>
-            <p>
-              The year value MAY be set to 0000 when the age of the <a>Contact</a> is private or the year is not
-              available.
-            </p>
+            This attribute contains the name of this <a>Contact</a> in a form that is suitable for display 
+            to the user.
           </dd>
-          <dt>attribute DOMString? note</dt>
+          <dt>ContactName? name</dt>
           <dd>
-            <p>
-              This attribute contains the personal notes (free-text) for this <a>Contact</a> that is managed by the
-              user of the address book.
-            </p>
+            This attribute represents the full name of this <a>Contact</a> indicated by the name components 
+            associated with the <a>ContactName</a> dictionary.
           </dd>
-          <dt>attribute ContactField[]? photos</dt>
+          <dt>DOMString? nickname</dt>
+          <dd>
+            This attribute contains the nickname (or a casual name) for this <a>Contact</a>.
+          </dd>
+          <dt>ContactField[]? phoneNumbers</dt>
+          <dd>
+            This attribute captures one or more phone numbers associated with this <a>Contact</a>.
+          </dd>
+          <dt>ContactField[]? emails</dt>
+          <dd>
+            This attribute represents one or more email addresses associated with this <a>Contact</a>.
+          </dd>
+          <dt>ContactAddress[]? addresses</dt>
+          <dd>
+            This attribute represents one or more physical addresses associated with this <a>Contact</a>.
+          </dd>
+          <dt>ContactField[]? ims</dt>
+          <dd>
+            This attribute represents one or more instant messaging identifiers associated with this
+            <a>Contact</a>.
+          </dd>
+          <dt>ContactOrganization[]? organizations</dt>
+          <dd>
+            This attribute represents one or more organisations associated with this <a>Contact</a>.
+          </dd>
+          <dt>Date? birthday</dt>
+          <dd>
+            This attribute contains birthday of this <a>Contact</a>. The <a>contact service</a> MAY
+            set the year value to 0000 when the age of the <a>Contact</a> is private or the year is not
+            available.
+          </dd>
+          <dt>DOMString? note</dt>
+          <dd>
+            This attribute contains the personal notes (free-text) for this <a>Contact</a> that is managed by the
+            user of the address book.
+          </dd>
+          <dt>ContactField[]? photos</dt>
           <dd>
             <p>
               This attribute represents one or more photos associated with this <a>Contact</a>.
@@ -346,476 +342,178 @@
               to provide inline data.
             </p>
             <p class="note">
-              This attribute SHOULD NOT be used to send down arbitrary photos taken by this user,
+              A <a>contact service</a> SHOULD NOT use this attribute to send down arbitrary photos taken by this user,
               but specifically profile photos of the contact suitable for display when describing the
               contact.
             </p>
           </dd>
-          <dt>attribute DOMString[]? categories</dt>
+          <dt>DOMString[]? categories</dt>
           <dd>
-            <p>
-              This attribute contains one or more user-defined categories/tags/labels associated with this
-              <a>Contact</a>. e.g. "family", "favorite", "cryptozoologists".
-            </p>
+            This attribute contains one or more user-defined categories/tags/labels associated with this
+            <a>Contact</a>. e.g. "family", "favourite", "cryptozoologists".
           </dd>
-          <dt>attribute ContactField[]? urls</dt>
+          <dt>ContactField[]? urls</dt>
           <dd>
             <p>
               This attribute represents one or more URLs associated with this <a>Contact</a> e.g. personal web page, 
               blog.
             </p>
-            <p>
-              The web resources MUST be specified using the <code>value</code> attribute of the
-              <code>ContactField</code> object, and its <code>type</code> field may be set to "blog" or
-              "profile".
-            </p>
-          </dd>
-        </dl>
-      </section>
-
-      <section>
-        <h2><a>ContactName</a> interface</h2>
-
-        <p>
-          The <a>ContactName</a> interface describes a contact's name.
-        </p>
-
-        <dl title='[NoInterfaceObject] interface ContactName' class='idl'>
-          <dt>attribute DOMString? familyName</dt>
-          <dd>
-            <p>
-              This attribute contains the family name (also referred to as the last name) of this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? givenName</dt>
-          <dd>
-            <p>
-              This attribute contains the given name (also referred to as the first name) of this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? middleName</dt>
-          <dd>
-            <p>
-              This attribute contains the middle name of this <a>Contact</a>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? honorificPrefix</dt>
-          <dd>
-            <p>
-              This attribute contains the honorific prefix (or title) of this <a>Contact</a>. E.g. Mr., Dr., Ms.,
-              Mrs.
-            </p>
-          </dd>
-          <dt>attribute DOMString? honorificSuffix</dt>
-          <dd>
-            <p>
-              This attribute contains the honorific suffix of this <a>Contact</a>. E.g. Jr., III, Sr.
-            </p>
-          </dd>
-        </dl>
-      </section>
-
-      <section>
-        <h2><a>ContactField</a> interface</h2>
-
-        <p>
-          The <a>ContactField</a> interface is a reusable component that is used to capture contact fields of the
-          <a>Contact</a> interface that have some modicum of structure.
-        </p>
-
-        <dl title='[NoInterfaceObject] interface ContactField' class='idl'>
-          <dt>attribute DOMString type</dt>
-          <dd>
-            <p>
-              This attribute contains the type information for this <a>ContactField</a> and its content varies subject
-              to the contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a> 
-              is representing a <code>phoneNumber</code> property, the <code>type</code> attribute can be set to 
-              <code>home</code>, <code>mobile</code>; if the <a>ContactField</a> is representing the <code>ims</code> 
-              property, the type attribute could be set to <code>xmpp</code>, <code>irc</code>, <code>bbm</code>, etc.
-            </p>
-          </dd>
-          <dt>attribute DOMString? value</dt>
-          <dd>
-            <p>
-              This attribute contains the value for this <a>ContactField</a> and its content varies subject to the
-              contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a> is 
-              representing an <code>email</code>, the value attribute could be set to <code>[email protected]</code>, 
-              and if the <a>ContactField</a> is representing a <code>url</code>, the value attribute can be set to    
-              <code>http://www.example.org/joesmith</code>, etc.
-            </p>
-          </dd>
-          <dt>attribute boolean pref</dt>
-          <dd>
-            <p>
-              This attribute indicates whether this instance of the <a>ContactField</a> is the
-              preferred, or primary, value for the contact property this <a>ContactField</a> is
-              representing in the <a>Contact</a> interface. By default, the value is <code>false</code>.
-            </p>
-          </dd>
-        </dl>
-      </section>
-
-      <section>
-        <h2><a>ContactAddress</a> interface</h2>
-
-        <p>
-          The <a>ContactAddress</a> interface is a reusable component that is used to capture addresses
-          within the <a>Contact</a> interface.
-        </p>
-        <dl title='[NoInterfaceObject] interface ContactAddress' class='idl'>
-          <dt>attribute boolean pref</dt>
-          <dd>
-            <p>
-              This attribute indicates whether this instance of the <code>ContactAddress</code> is the preferred, or primary, value for the contact. 
-              By default, the value is <code>false</code>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? type</dt>
-          <dd>
-            <p>
-              This attribute contains the type of address this object is representing (e.g. <code>work</code>, <code>home</code>, <code>premises</code>, etc).
-            </p>
-          </dd>
-          <dt>attribute DOMString? streetAddress</dt>
-          <dd>
-            <p>
-              This attribute contains the street address corresponding to this <a>ContactAddress</a>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? locality</dt>
-          <dd>
-            <p>
-              This attribute contains the locality (or city) name corresponding to this <a>ContactAddress</a>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? region</dt>
-          <dd>
-            <p>
-              This attribute contains the region (or state/province) name corresponding to this <a>ContactAddress</a>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? postalCode</dt>
-          <dd>
-            <p>
-              This attribute contains the postal code (or zip) corresponding to this <a>ContactAddress</a>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? country</dt>
-          <dd>
-            <p>
-              This attribute contains the country name corresponding to this <a>ContactAddress</a>.
-            </p>
-          </dd>
-        </dl>
-      </section>
-
-      <section>
-        <h2><a>ContactOrganization</a> interface</h2>
-
-        <p>
-          The <a>ContactOrganization</a> interface is a reusable component that is used to support contact
-          organisations within the <a>Contact</a> interface.
-        </p>
-
-        <dl title='[NoInterfaceObject] interface ContactOrganization' class='idl'>
-          <dt>attribute boolean pref</dt>
-          <dd>
-            <p>
-              This attribute indicates whether this instance of the <code>ContactOrganization</code> is the preferred, or 
-              primary, value for the contact. By default, the value is <code>false</code>.
-            </p>
-          </dd>
-          <dt>attribute DOMString? type</dt>
-          <dd>
-            <p>
-              This attribute contains the type of organization this object is representing. 
-            </p>
-          </dd>
-          <dt>attribute DOMString? name</dt>
-          <dd>
-            <p>
-              The name of the organisation.
-            </p>
-          </dd>
-          <dt>attribute DOMString? department</dt>
-          <dd>
-            <p>
-              The department within which this <a>Contact</a> works.
-            </p>
-          </dd>
-          <dt>attribute DOMString? title</dt>
-          <dd>
-            <p>
-              The job title that the <a>Contact</a> holds inside this organisation.
-            </p>
           </dd>
         </dl>
       </section>
 
       <section>
-        <h2><a>ContactFindOptions</a> interface</h2>
+        <h2>The <a>ContactName</a> dictionary</h2>
         <p>
-          The <a>ContactFindOptions</a> interface describes the options that can be applied to contact searching. 
-          When a <a>ContactFindOptions</a> parameter is provided to the <a>Contacts</a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a>
-          operation, it should be processed according to the provisions detailed in 
-          <a href="#options-processing">Options Processing</a>.
+          The <a>ContactName</a> dictionary describes a contact's name in detail.
         </p>
-        <dl title='[NoInterfaceObject] interface ContactFindOptions' class='idl'>
-          <dt>attribute DOMString? filter</dt>
+        <dl title='dictionary ContactName' class='idl'>
+          <dt>DOMString? familyName</dt>
           <dd>
-            A string-based <a>search filter</a> which provides a hint to the user agent to facilitate contacts selection by the user.
+            This attribute contains the family name (also referred to as the last name) of this <a>Contact</a>.
           </dd>
-          <dt>attribute boolean? multiple</dt>
+          <dt>DOMString? givenName</dt>
           <dd>
-            A boolean value to indicate whether multiple Contact objects are wanted as part of the
-            <a>Contacts</a> <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
-            By default this option is set to <code>false</code>.
+            This attribute contains the given name (also referred to as the first name) of this <a>Contact</a>.
+          </dd>
+          <dt>DOMString? middleName</dt>
+          <dd>
+            This attribute contains the middle name of this <a>Contact</a>.
+          </dd>
+          <dt>DOMString? honorificPrefix</dt>
+          <dd>
+            This attribute contains the honorific prefix (or title) of this <a>Contact</a>. E.g. Mr., Dr., Ms., Mrs.
+          </dd>
+          <dt>DOMString? honorificSuffix</dt>
+          <dd>
+            This attribute contains the honorific suffix of this <a>Contact</a>. E.g. Jr., III, Sr.
           </dd>
         </dl>
       </section>
 
       <section>
-        <h2><a>ContactFindCB</a> interface</h2>
+        <h2>The <a>ContactField</a> dictionary</h2>
         <p>
-          This is the wrapper interface for callbacks indicating success of the <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> 
-          operation.
+          The <a>ContactField</a> dictionary is a reusable component that is used to capture contact fields of the
+          <a>Contact</a> dictionary that have some modicum of structure.
         </p>
 
-        <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactFindCB' class='idl'>
-          <dt>void onsuccess ()</dt>
+        <dl title='dictionary ContactField' class='idl'>
+          <dt>DOMString type</dt>
           <dd>
-            <dl class='parameters'>
-              <dt>Contact[] contactObjs</dt>
-              <dd>
-                An array of <a>Contact</a> objects resulting from the given <a>Contacts</a> 
-                <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> operation.
-              </dd>
-            </dl>
+            This attribute contains the type information for this <a>ContactField</a> and its content varies subject
+            to the contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a> 
+            is representing a <code>phoneNumber</code> property, the <code>type</code> attribute can be set to 
+            <code>home</code>, <code>mobile</code>; if the <a>ContactField</a> is representing the <code>ims</code> 
+            property, the type attribute could be set to <code>xmpp</code>, <code>irc</code>, <code>bbm</code>, etc.
+          </dd>
+          <dt>DOMString? value</dt>
+          <dd>
+            This attribute contains the value for this <a>ContactField</a> and its content varies subject to the
+            contact property this <a>ContactField</a> is representing. For example, if the <a>ContactField</a> is 
+            representing an <code>email</code>, the value attribute could be set to <code>[email protected]</code>, 
+            and if the <a>ContactField</a> is representing a <code>url</code>, the value attribute can be set to    
+            <code>http://www.example.org/joesmith</code>, etc.
+          </dd>
+          <dt>boolean pref</dt>
+          <dd>
+            This attribute indicates whether this instance of the <a>ContactField</a> is the
+            preferred, or primary, value for the contact property this <a>ContactField</a> is
+            representing in the <a>Contact</a> interface. By default, the value is <code>false</code>.
           </dd>
         </dl>
-
-        <section>
-          <h3>Event Handler Attributes</h3>
-          <p>
-            The following is the <a>event handler attribute</a> (and its corresponding <a>event handler event
-            type</a>) that MUST be supported as a DOM attribute by the <a>ContactFindCB</a> object.
-          </p>
-          <table class='simple'>
-            <thead>
-              <tr>
-                <th>event handler attribute</th>
-                <th>event handler event type</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr>
-                <td><strong><code>onsuccess</code></strong></td>
-                <td><code>success</code></td>
-              </tr>
-            </tbody>
-          </table>
-        </section>
-      </section>
-
-      <section>
-        <h2><a>ContactErrorCB</a> interface</h2>
-        <p>
-          This is the wrapper interface for callbacks indicating failure of the <a href="#widl-Contacts-find-void-DOMStringArray-fields-ContactFindCB-successCB-ContactErrorCB-errorCB-ContactFindOptions-options">find()</a> 
-          operation.
-        </p>
-
-        <dl title='[Callback=FunctionOnly, NoInterfaceObject] interface ContactErrorCB' class='idl'>
-          <dt>void onerror ()</dt>
-          <dd>
-            <dl class='parameters'>
-              <dt>ContactError error</dt>
-              <dd>The <a>ContactError</a> object capturing the type of the error.</dd>
-            </dl>
-          </dd>
-        </dl>
-
-        <section>
-          <h3>Event Handler Attributes</h3>
-          <p>
-            The following is the <a>event handler attribute</a> (and its corresponding <a>event handler event
-            type</a>) that MUST be supported as a DOM attribute by the <a>ContactErrorCB</a> object.
-          </p>
-
-          <table class='simple'>
-            <thead>
-              <tr>
-                <th>event handler attribute</th>
-                <th>event handler event type</th>
-              </tr>
-            </thead>
-            <tbody>
-              <tr>
-                <td><strong><code><strong>onerror</strong></code></strong></td>
-                <td><code>error</code></td>
-              </tr>
-            </tbody>
-          </table>
-        </section>
       </section>
 
       <section>
-        <h2><a>ContactError</a> interface</h2>
+        <h2>The <a>ContactAddress</a> dictionary</h2>
         <p>
-          The <a>ContactError</a> interface encapsulates all errors in the manipulation of 
-          <a>Contact</a> objects.
+          The <a>ContactAddress</a> dictionary is a reusable component that is used to capture addresses
+          within the <a>Contact</a> dictionary.
         </p>
-
-        <dl title='[NoInterfaceObject] interface ContactError' class='idl'>
-          <dt>const unsigned short UNKNOWN_ERROR = 0</dt>
-          <dd>An unknown error occurred.</dd>
-
-          <dt>const unsigned short INVALID_ARGUMENT_ERROR = 1</dt>
-          <dd>An invalid parameter was provided when the requested method was invoked.</dd>
-
-          <dt>const unsigned short TIMEOUT_ERROR = 2</dt>
-          <dd>The requested method timed out before it could be completed.</dd>
+        <dl title='dictionary ContactAddress' class='idl'>
+          <dt>boolean pref</dt>
+          <dd>
+            This attribute indicates whether this instance of the <code>ContactAddress</code> is the preferred, 
+            or primary, value for the contact. By default, the value is <code>false</code>.
+          </dd>
+          <dt>DOMString? type</dt>
+          <dd>
+            This attribute contains the type of address this object is representing (e.g. <code>work</code>, 
+            <code>home</code>, <code>premises</code>, etc).
+          </dd>
+          <dt>DOMString? streetAddress</dt>
+          <dd>
+            This attribute contains the street address corresponding to this <a>ContactAddress</a>.
+          </dd>
+          <dt>DOMString? locality</dt>
+          <dd>
+            This attribute contains the locality (or city) name corresponding to this <a>ContactAddress</a>.
+          </dd>
+          <dt>DOMString? region</dt>
+          <dd>
+            This attribute contains the region (or state/province) name corresponding to this <a>ContactAddress</a>.
+          </dd>
+          <dt>DOMString? postalCode</dt>
+          <dd>
+            This attribute contains the postal code (or zip) corresponding to this <a>ContactAddress</a>.
+          </dd>
+          <dt>DOMString? country</dt>
+          <dd>
+            This attribute contains the country name corresponding to this <a>ContactAddress</a>.
+          </dd>
+        </dl>
+      </section>
 
-          <dt>const unsigned short PENDING_OPERATION_ERROR = 3</dt>
-          <dd>There is already a <a>task</a> in the <a>device task source</a>.</dd>
-
-          <dt>const unsigned short IO_ERROR = 4</dt>
-          <dd>An error occurred in communication with the underlying implementation that meant the requested
-          method could not complete.</dd>
-
-          <dt>const unsigned short NOT_SUPPORTED_ERROR = 5</dt>
-          <dd>The requested method is not supported by the current implementation.</dd>
-
-          <dt>const unsigned short PERMISSION_DENIED_ERROR = 20</dt>
-          <dd>Access to the requested information was denied by the implementation or by the user.</dd>
-
-          <dt>readonly attribute unsigned short code</dt>
-          <dd>An error code assigned by an implementation when an error has occurred in Pick Contacts Intent
-          processing.</dd>
+      <section>
+        <h2>The <a>ContactOrganization</a> dictionary</h2>
+        <p>
+          The <a>ContactOrganization</a> dictionary is a reusable component that is used to support contact
+          organisations within the <a>Contact</a> dictionary.
+        </p>
+        <dl title='dictionary ContactOrganization' class='idl'>
+          <dt>boolean pref</dt>
+          <dd>
+            This attribute indicates whether this instance of the <code>ContactOrganization</code> is the preferred, or 
+            primary, value for the contact. By default, the value is <code>false</code>.
+          </dd>
+          <dt>DOMString? type</dt>
+          <dd>
+            This attribute contains the type of organisation this object is representing. 
+          </dd>
+          <dt>DOMString? name</dt>
+          <dd>
+            The name of the organisation.
+          </dd>
+          <dt>DOMString? department</dt>
+          <dd>
+            The department within which this <a>Contact</a> works.
+          </dd>
+          <dt>DOMString? title</dt>
+          <dd>
+            The job title that the <a>Contact</a> holds inside this organisation.
+          </dd>
         </dl>
       </section>
+      <section>
+        <h2>The <a>ContactError</a> dictionary</h2>
+        <p>
+          If the <a>contact service</a> encounters an error then it MUST return an error 
+          (through <code>postFailure()</code>) using the <a>ContactError</a> dictionary.
+        </p>
+        <dl title='dictionary ContactError' class='idl'>
+          <dt>DOMString message</dt>
+          <dd>A message describing the error.</dd>
+        </dl>
+      </section>
+      <section>
+        <h2>Extended Contact Properties and Parameters</h2>
+        <p>
+          A <a>contact service</a> MAY extend the dictionaries described in in the Data Formats section with
+          additional fields. If providing an extended field, a <a>contact service</a> MUST prefix its name
+          with <code>X</code> (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix.
+        </p>
+      </section>
     </section>
-
-    <section>
-      <h2>Extended Contact Properties and Parameters</h2>
-
-      <p>
-      The properties and parameters defined on the <a href="#contact-interface"><code>Contact</code></a>
-      interface MAY be extended by implementers of this specification.
-      </p>
-
-      <p>
-      Non-standard, private properties and parameters MUST have a prefixed name starting with
-      <code>X</code> (U+0058 LATIN CAPITAL LETTER X) or use a vendor-specific prefix. Extended properties and
-      parameters can be defined bilaterally between <a title="user agent">user agents</a> without outside
-      registration or standardization.
-      </p>
-
-      <p>
-      It is RECOMMENDED that authors define both a formal vCard grammar and a WebIDL grammar for their
-      proposed extension to ensure interoperability between vCard databases and other non-standard Contact
-      databases and formats. It is also RECOMMENDED that authors provide documentation of their extension
-      properties and parameters within the public domain.
-      </p>
-
-      <div class="example">
-        <p>
-        A new parameter is required by Company X to provide information related to a user's accounts
-        registered across different networks and services.
-        </p>
-
-        <p>
-        The [[WEBIDL]] syntax for this parameter is defined as follows:
-        </p>
-
-        <div class='idl' title='Contact implements ContactExtended'>
-          &nbsp;
-        </div>
-
-        <dl title='[NoInterfaceObject] interface ContactExtended' class='idl'>
-          <dt>attribute ContactAccount[] Xaccounts</dt>
-
-          <dd>One or more user accounts. See [[[POCO-SCHEMA]] Section 7.2.2. <code>accounts</code>].</dd>
-        </dl>
-
-        <dl title='[NoInterfaceObject] interface ContactAccount' class='idl'>
-          <dt>attribute DOMString domain</dt>
-
-          <dd>
-            <p>
-            See [[[POCO-SCHEMA]] Section 7.6. <code>domain</code>].
-            </p>
-          </dd>
-
-          <dt>attribute DOMString username</dt>
-
-          <dd>
-            <p>
-            See [[[POCO-SCHEMA]] Section 7.6. <code>username</code>].
-            </p>
-          </dd>
-
-          <dt>attribute DOMString userid</dt>
-
-          <dd>
-            <p>
-            See [[[POCO-SCHEMA]] Section 7.6. <code>userid</code>].
-            </p>
-          </dd>
-        </dl>
-
-        <p>
-        The corresponding vCard [[RFC2426]] notation for this parameter is defined as follows:
-        </p>
-        <pre>
-     The following ABNF grammar extends the grammar found in [[RFC2426]] (Section 4).
-   
-     <strong>X-ACCOUNT</strong>
-   
-     Purpose:  To specify the components of the accounts for the vCard 
-        object.
-
-     Value type:  A single structured text value, separated by the SEMI-
-        COLON character (ASCII decimal 59).
-
-     Cardinality:  (0,n)
-
-     Special notes:  The structured type value consists of a sequence of
-        account components.  The component values must be specified in
-        their corresponding position.  The structured type value
-        corresponds, in sequence, to the domain; the username; the userid.
-        When a component value is missing, the associated component 
-        separator must still be specified.    
-
-        The text components are separated by the SEMI-COLON character
-        (ASCII decimal 59).
-      
-     ABNF:
-   
-       X-ACCOUNT-param = ; no parameter allowed
-       X-ACCOUNT-value = list-component 3(";" list-component)
-  </pre>
-
-        <p>
-        This parameter will be used within the Pick Contacts Intent as follows:
-        </p>
-        <pre class="sh_javascript">
-     var contact = ...; // ...obtain individual contact object
-     for(var i in contact.Xaccounts) {
-        alert(contact.Xaccounts[i].domain);   // thesocialnetwork.com
-        alert(contact.Xaccounts[i].username); // null
-        alert(contact.Xaccounts[i].userid);   // 344aesq2
-     }            
-  </pre>
-
-        <p>
-        This parameter will be used within the vCard format [[RFC2426]]] as follows:
-        </p>
-        <pre>
-     X-ACCOUNT;thesocialnetwork.com;;344aesq2
-  </pre>
-      </div>
-    </section>
-
     <section class="informative appendix">
       <h2>User Interaction Guidelines</h2>