- From: Richard Tibbett via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 07 Apr 2010 13:44:17 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/contacts
In directory hutz:/tmp/cvs-serv7564
Modified Files:
Overview.html
Log Message:
Added 'Design Considerations' (work in progress).
Started to roll in changes from F2F (Prague Mar 2010)
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/contacts/Overview.html,v
retrieving revision 1.50
retrieving revision 1.51
diff -u -d -r1.50 -r1.51
--- Overview.html 24 Mar 2010 14:31:40 -0000 1.50
+++ Overview.html 7 Apr 2010 13:44:15 -0000 1.51
@@ -18,7 +18,6 @@
</script>
<script src='../common/config.js' class='remove'>
</script>
- <link rel="stylesheet" href="../ReSpec.js/css/respec.css" type="text/css" media="screen" />
</head>
<body>
<section id='abstract'>
@@ -76,7 +75,7 @@
successContactFindCallback,
generalErrorCB,
{filter:
- {'name': 'Bob'}
+ {name: 'Bob'}
} );</pre>
</div>
<div>
@@ -134,6 +133,134 @@
</section>
</section>
+
+ <section class="informative">
+ <h2>Design Considerations</h2>
+
+ <section>
+ <h2>Privacy by Design</h2>
+
+ <p>
+ The Contacts API has been designed with the intention of putting the user in control of their data and allowing user's
+ to control the flow of their information to 3rd party sites and services.
+ </p>
+
+ <p>
+ The <a href="#security-and-privacy-considerations">Security and Privacy Considerations</a> section provides both normative
+ and non-normative recommendations for both implementors and consumers of the Contacts API - it recommends that user's
+ should be able to review the information that is being requested by a web application and allow a user to override, modify
+ or supplement the requested information as they may require.
+ </p>
+
+ <p>
+ In addition to the included Security and Privacy Considerations additional features have been directly embedded within the Contacts API
+ that are intended to further ensure the privacy of a user's Contacts information. The Contacts API is built on the premise
+ that a user should be able to share the least information possible with a 3rd party service while still allowing the 3rd party service to
+ fulfill its intended function.
+ </p>
+
+ <section>
+ <h2>Data Minimization</h2>
+
+ <p>
+ <dfn>Data minimization</dfn> is the principle that a consumer is required to request the specific fields of Contact information
+ that it requires in order to fulfill its operation and that an implementation is required to return only the specific
+ fields granted by the user as a result of that request.
+ </p>
+
+ <p>
+ For example, a web application that requires email addresses to send information via email on to a selection of a user's contacts
+ should only need to request the <a href="#widl-ContactProperties-emails"><code>emails</code></a> attribute in the
+ <a href="#widl-Contacts-find"><code>fields</code></a> parameter of the associated <a href="#contacts-interface"><code>Contacts</code></a>
+ <a href='#widl-Contacts-find'>find()</a> operation. The web application may request additional fields as required.
+ </p>
+
+ <p>
+ An implementation should collect the Contact object(s) to be returned to a consumer request according to the
+ <a>rules for processing filter combinations</a> and then return the corresponding subset of
+ <a href="#contactproperties-interface"><code>ContactProperties</code></a> requested from the original consumer only after they have
+ been approved by the user.
+ </p>
+
+ <p>
+ The <dfn>data minimization process</dfn> is therefore defined as follows:
+
+ <ol>
+ <li>Let a <em>consumer</em> (e.g. a web application) request the specific contact properties (fields) required for its operation.</li>
+ <li>Let the <em>consumer</em> make a request for the requested fields to an <em>implementation</em> at run time.</li>
+ <li>Let the <em>user</em> review the requested fields and override, modify and/or supplement the resulting data as required.</li>
+ <li>Let the <em>implementation</em> return the data resulting from this process to the original <em>consumer</em> in step 1.</li>
+ </ol>
+ </p>
+ </section>
+
+ <section>
+ <h2>Object Minimization</h2>
+
+ <p>
+ <dfn>Object minimization</dfn> is the principle that by default an implementation of the Contacts API MUST return only a single
+ <a href="#contact-interface"><code>Contact</code></a> object as the result of a <a href="#contacts-interface"><code>Contacts</code></a>
+ <a href='#widl-Contacts-find'>find()</a> operation.
+ </p>
+
+ <p>
+ If a consumer wishes to indicate that it can accept more than one <a href="#contact-interface"><code>Contact</code></a> object, the consumer MUST
+ set the <a href="#contactfindoptions-interface">ContactFindOptions</a>
+ <a href="#widl-ContactFindOptions-multiple"><code>multiple</code></a> attribute to <code>true</code>.
+ </p>
+
+ <p>
+ The consumer MAY also set the <a href="#contactfindoptions-interface">ContactFindOptions</a>
+ <a href="#widl-ContactFindOptions-limit"><code>limit</code></a> attribute to a non-negative integer value. If this attribute is provided
+ the implementation MUST allow multiple Contact objects to be returned up to the value of the <a href="#widl-ContactFindOptions-limit"><code>limit</code></a>
+ provided.
+ </p>
+ </section>
+
+ </section>
+
+ <section>
+ <h2>Multiple Data Sources</h2>
+
+ <p class="note">
+ Data is sourced from multiple locations. No specific requirement on having a single central repository for contact information.
+ </p>
+ </section>
+
+ <section>
+ <h2>Asychronous Communications</h2>
+
+ <p class="note">
+ Avoid any potential for blocking communication calls (cross-domain, cross-service, between UA and device, etc) with asynchronous design pattern (except for sync helper functions).
+ </p>
+
+ <section>
+ <h2>Pending Operations</h2>
+
+ <p class="note">
+ A way to cancel existing asynchronous operations.
+ </p>
+ </section>
+
+ <section>
+ <h2>Operation Timeouts</h2>
+
+ <p class="note">
+ Default behaviour for request timeouts.
+ </p>
+ </section>
+ </section>
+
+ <section>
+ <h2>Interoperability with Existing Formats</h2>
+
+ <p class="note">
+ Homogenous design with vCard, hCard, Portable Contacts, etc... objectives, scope...
+ </p>
+ </section>
+
+ </section>
+
<section>
<h2>Security and Privacy Considerations</h2>
@@ -225,9 +352,7 @@
<h2>API Description</h2>
<section>
<h2><a>ServiceContacts</a> interface</h2>
-
-<p class='issue'>The actual object of which the API will be hanging off is still under discussion (e.g. <code>navigator.service</code> vs from <code>navigator.device</code>); see <a href="http://www.w3.org/2009/dap/track/issues/67">ISSUE-67</a></p>
-
+
<p>
The <a href='#servicecontacts-interface'><code>ServiceContacts</code></a> interface is exposed on the <code>navigator.service</code> object, as defined in [[!CORE-DEVICE]].
</p>
@@ -276,6 +401,10 @@
<p>This method takes one argument. When called, it returns
a <a href='#contact-interface'><code>Contact</code></a> object.</p>
+ <p>The newly created <a href='#contact-interface'><code>Contact</code></a> object MUST NOT be stored stored in the user's address book as a result
+ of calling this method. The <a href='#contact-interface'><code>Contact</code></a> <a href='#widl-Contact-save'>save()</a> method MUST be called on the
+ response of this method to store the new <a href='#contact-interface'><code>Contact</code></a> object in the user's address book.</p>
+
<dl class='parameters'>
<dt>
ContactProperties attributes
@@ -290,7 +419,7 @@
PendingOp find ()
</dt>
<dd>
- <p>Find contacts in the address book based on a <a href='#contactproperties-interface'><code>ContactProperties</code></a> object acting as a filter.</p>
+ <p>Find contacts in the address book according to the <a>find contacts process</a> detailed below.</p>
<p>This method takes two, three or four arguments. When called, it immediately returns
a <code>PendingOp</code> object , as defined in [[!CORE-DEVICE]], and then asynchronously starts a <dfn>find contacts process</dfn> defined as follows:</p>
@@ -313,7 +442,8 @@
requested to be returned as part of the associated <a href='#contactfindsuccesscb-interface'><code>ContactFindSuccessCB</code></a>.
<p>
- This method returns no ContactProperties by default. Therefore the requested <a href='#contact-interface'><code>Contact</code></a> fields MUST be specified as part of this operation.
+ This method returns no <a href='#contactproperties-interface'><code>ContactProperties</code></a> by default. Therefore the
+ requested <a href='#contact-interface'><code>Contact</code></a> fields MUST be specified as part of this operation.
</p>
</dd>
<dt>
@@ -754,7 +884,11 @@
Contact contactObj
</dt>
<dd>
+<<<<<<< Overview.html
+ The Contact object resulting from the given <a href='#contact-interface'><code>Contact</code></a> <a href='#widl-Contact-save'>save()</a> or <a href='#contact-interface'><code>Contact</code></a> <a href='#widl-Contact-remove'>remove()</a> method.
+=======
The Contact object resulting from the given <a href="#widl-Contact-save"><code>Contact.save()</code></a> or <a href="#widl-Contact-remove"><code>Contact.remove()</code></a> method.
+>>>>>>> 1.50
</dd>
</dl>
</dd>
@@ -878,13 +1012,13 @@
successContactFindCallback,
generalErrorCB,
{
- 'filter':
+ filter:
{
- 'name': 'Robert',
- 'nicknames': 'Bob'
+ name: 'Robert',
+ nicknames: 'Bob'
},
- 'multiple': true,
- 'limit': 3
+ multiple: true,
+ limit: 3
}
);</pre>
@@ -893,14 +1027,17 @@
2. Return the 'name', 'addresses', 'phones' and 'emails' attributes of the resulting Contact objects.</pre>
</p>
- <p class='note'>
- We need to be a lot clearer about partial matching included below. It might just be simpler to use pass RegExp objects around. Then again it might not...
- </p>
<p>
All contact searching SHOULD apply a loose-matching policy. If a <a href='#contactproperties-interface'><code>ContactProperties</code></a> attribute being searched in <a href='#contacts-interface'><code>Contacts</code></a>
- <em>partially matches</em> the input filter value, a <a href='#contact-interface'><code>Contact</code></a> object representing the contact
+ is a <a>partial value match</a> of the input filter value, a <a href='#contact-interface'><code>Contact</code></a> object representing the contact
SHOULD be returned as part of the resulting <a href='#contactfindsuccesscb-interface'><code>ContactFindSuccessCB</code></a>.
</p>
+
+ <p>
+ A <dfn>partial value match</dfn> refers to both syntactic and semantic partial matching of an input filter value with
+ a corresponding value in the address book. A <a>partial value match</a> is case-insensitive and MUST be considered to match when the value in the
+ address book begins with, contains and/or ends with the value of the the input filter value.
+ </p>
<p>The <dfn id='rules-for-processing-filter-combinations'>rules for processing filter combinations</dfn> is defined below and is always provided with an <var title="">input</var> parameter and, an optional <var title="">options</var> parameter. Its behaviour depends on the type of <var title="">input</var>:</p>
@@ -930,109 +1067,14 @@
</dl>
</p>
-
- <p> </p>
</section>
- <section>
- <h2>Use Cases and Requirements</h2>
-
- <section>
- <h2>Use Cases</h2>
-
- <p>
- <h4 id='uc1'>Use Case 1: Upload a set of contact details to a user's social network</h4>
- A user is registered on a number of different social networking sites and would like to upload some or all of their
- address book contacts to the service. Using the Contacts API, the Web application has access to the user's address book,
- subject to user opt-in, and it is therefore able to import the user's selected contacts in to their service.
- </p>
-
- <p>
- <h4 id='uc2'>Use Case 2: Download a set of contact details from a user's social network</h4>
- A social networking user would like to download some or all of their social network contacts to their native address book, in to their native
- phone dialling application or in to another application for offline / non-web use. Using the Contacts API, the Web application provides the user with an export
- function and, subject to user opt-in, the selected contacts can be downloaded and imported in to the user's address book.
- </p>
-
- <p>
- <h4 id='uc3'>Use Case 3: A user would like to keep their work address book and personal address book seperate</h4>
- The Contacts API will provide all address book contacts in a unified way but the user would like to associate individual contacts
- to individual address books - keeping their work and social address books seperated. The Contacts API must allow Web Applications to
- distinguish between multiple address book stores and allow the user to manage different address books according to their needs.
- </p>
-
- <p>
- <h4 id='uc4'>Use Case 4: A user maintains a single unified address book but would like to maintain groups of contacts within that address book</h4>
- A user has a number of friends, family, colleagues and other contacts in their address book. They would like to create groups and assign
- existing contacts to these groups. The user can create, update or remove as many groups as they like and equally they would like to be able to
- add, remove and update the members assigned to those groups whenever they need to. The user's contacts can belong to multiple groups at the
- any one time.
- </p>
-
- <p>
- <h4 id='uc5'>Use Case 5: Use a web interface to manage contact details on both the user's device and the web</h4>
- A Web Application is built that allows users to add, update and remove friend's contact details stored in their native address book.
- The Web Application can add, remove and update contact details, subject to user opt-in, and these details are automatically propagated
- from the web interface to the user's address book.
- </p>
-
- <p>
- <h4 id='uc6'>Use Case 6: A user would like to export contacts from the one address book store and import them to another address book store</h4>
- The user maintains multiple address books that are stored on both the web and on their device(s). The user would like to move some or all of
- their contacts from one address book store to another. Using the Contacts API, the user can assign contact details to different address book
- stores. The underlying implementation will action the import/export process when the user changes to which address book store a contact is
- associated and the user makes an active request, via the Contacts API, to update the modified contacts.
- </p>
-
- <p>
- <h4 id='uc7'>Use Case 7: A user would like to be notified when friends have a birthday coming up</h4>
- A user would like their favorite Web Application to inform them when all their friend's birthdays are coming up. The user imports some or all
- of their address book contacts to the Web Application. The web application can read in the contacts' birthdays as well as other useful identifying
- information (e.g. the contacts' names). The Web Application can then email, SMS or otherwise notify the user when a contact's birthday is coming
- up.
- </p>
-
- <p>
- <h4 id='uc8'>Use Case 8: A user would like his/her contacts to update their own contact details via a mediating Web Application and sync any changes to their
- current address book</h4>
- User's contact details are constantly changing and being updated. A user has uploaded their address book to a Web Application which has then allowed
- the user's contacts to update the details contained therein in a collaborative way. The user can then synchronise any changes made by his/her contacts
- when they e.g. visit that Web Application at any point in the future.
- </p>
- </section>
-
- <section>
- <h2>Requirements</h2>
-
- <ul>
- <li>The Contacts API <em title="must" class="rfc2119">must</em> enable listing all available address books on the device;</li>
- <li>The Contacts API <em title="must" class="rfc2119">must</em> enable listing all contacts in the address book(s);</li>
- <li>The Contacts API <em title="must" class="rfc2119">must</em> enable reading the details for a contact;</li>
- <li>The Contacts API <em title="should" class="rfc2119">should</em> enable creating a new contact;</li>
- <li>The Contacts API <em title="should" class="rfc2119">should</em> enable updating a contact;</li>
- <li>The Contacts API <em title="should" class="rfc2119">should</em> enable deleting a contact;</li>
-
- <li>The Contacts API <em title="should" class="rfc2119">should</em> enable filtering the list of contacts to search for a subset.</li>
- </ul>
-
-
- </section>
-
- </section>
-
- <section class='appendix'>
- <h2>Features for Future Consideration</h2>
- <p>
- The requirements document contains a list of features that were considered for this version
- but deferred to future work [[DAP-REQS]].
- </p>
- </section>
-
<section class='appendix'>
<h2>Acknowledgements</h2>
<p>
- The editor would like to thank the input from the PhoneGap, Nokia, and OMTP BONDI groups and the feedback received from W3C DAP members to date ...
+ Robin Berjon, Dominique Hazaël-Massieux, Suresh Chitturi, Alissa Cooper, Max Froumentin, Frederick Hirsch, Anssi Kostainen, Brian LeRoux, Ilkka Oksanen
+ and other members of the W3C DAP WG ...
</p>
</section>
</body>
Received on Wednesday, 7 April 2010 13:44:19 UTC