WebIntents/ContactsAPI

Registration

This is assuming the new schema.org usage:

<intent action="http://webintents.org/pick"
        type="http://schema.org/Person http://schema.org/Organization"
        encoding="application/json"
        ></intent>

Client

This is assuming the new schema.org usage, but that we haven't yet switched to object literals.

 var intent = new Intent("http://webintents.org/pick",
                         "http://schema.org/Person",
                         "application/json",
                         null,
                         null,
                         { filter: "Bob", fields: ["name", "emails", "birthday"]});
 navigator.startActivity(intent, gotContacts);
 function gotContacts (data) {
     console.log(data); // logs an array of contacts as selected
 }

The same using object literal:

 var intent = new Intent({
                         action:    "http://webintents.org/pick",
                         type:      "http://schema.org/Person",
                         encoding:  "application/json",
                         extras:    { filter: "Bob", fields: ["name", "emails", "birthday"]}});

Discussion

Actually the above makes use of encoding "application/json" when it really means that the client expects to get a JS object (in this case an array) which is a structured clone of the contact information. Presumably an alternative would be to use encoding "text/vcard" and get a blob of a vcard (or possibly a string in this case).

I think that that's wrong because in one case we're getting a blob of vcard and in the other we're getting an in-memory structure, when in fact we logically should be getting a blob of JSON — JSON is being treated specially. Furthermore, if the fields had included pictures, ideally we'd want them to be Blobs where in fact if they were application/json they'd have to be serialised as data URIs (or some similar option). So the application/json is a lie.

Alternative proposal: when no encoding parameter is specified, this means that a structured clone will always be passed. When the encoding is passed, it means that a Blob (or array of Blobs?) will always be passed. This leads to this alternative variant (that is both more semantically correct and shorter):

<intent action="http://webintents.org/pick"
        type="http://schema.org/Person http://schema.org/Organization"
        ></intent>

 var intent = new Intent({
                         action:    "http://webintents.org/pick",
                         type:      "http://schema.org/Person",
                         extras:    { filter: "Bob", fields: ["name", "emails", "birthday"]}});