Re: [Jmap] I-D Action: draft-ietf-jmap-jscontact-04.txt

[Robert Stepanek <[e-mail]>]

Hi Neil,

thanks for the feedback.

On Wed, Mar 10, 2021, at 6:02 AM, Neil Jenkins wrote:
> I've read through this draft and I have a few comments:
>  * The metadata section is missing a `created` timestamp. Also the type of this and updated should be `UTCDate`, not just String (this is more a notational comment, but I would recommend using exactly the same type system as JSCalendar).

Agreed.

>  * The `fullName` description doesn't make it clear to me what its purpose is. Is it always the same as `name` joined together by spaces? (Presumably not, as that wouldn't be very useful.) Or is it to provide alternative versions of the name in different character sets for internationalisation? (It's a LocalizedString type so can have multiple variants, so maybe.) Or is to provide the preferred name to call someone? (Not at all what the description says, but perhaps useful.)

Its purpose is to both allow internationalisation and to preserve the FN property value of a VCARD value. The latter is especially important in case the VCARD does not also contain a N property.

>  * The idea of the `name` field is its an array of tagged components, so you can accurately represent names in locales where, for example, the family name comes first when written out. That's great, however I think `nickname` is not the same as one of these components and should be a separate field in JSContact; a nickname is not a subpart of a name, it's an alternate one.

Agreed, nickname(s) should be a separate field.

>  * I found the description of the `roles` property hard to understand; I don't really get it.

We defined this property to make sure that we can cover the existing VCARD format, including the ROLE property. But now that I look at it, even the definition of the ROLE property isn't that clear to me (https://tools.ietf.org/html/rfc6350#section-6.6.2). It would interesting to understand how widely used this property is, and how people decide if to use TITLE or ROLE.

On a side-note it also bugs me that a jobTitle has no (optional) relation to an organization in the same card object. I think we should change that.

>  * The value for `Resources` in the `emails` field should just be the email address. The spec currently says it can be this or a mailto: URI, but there's no reason to allow an alternate encoding of exactly the same data and the escaping/unescaping of characters to transform to/from a mailto URI is a pain to get right and likely to lead to incompatibilities.

Just be clear, you mean we should get rid of the mailto: URI, right? This makes sense to me as we want to keep any email addressee name in addition to the address itself. Rather than using a String, we could reuse the EmailAddress type as defined in the JMAP Mail spec.

>  * For `phones` there's a kind of similar thing, although I do see the idea behind URIs here with `sip:` vs `tel:`. I wonder if uri should just be an optional extra property instead rather than the value being *either* a URI or the phone number.

I'd say in that case only allowing an URI is the better choice. In contrast to emails, we don't lose any information by restricting the type to a URI.

>  * The taxonomy of `type` doesn't feel quite right for phones: if I have a mobile (cell) phone number, is that "voice"? But it also accepts SMS. But type is single valued, so what type should it be?

Agreed, it makes sense for phones to have multiple types (or however one might call it). Both this and the idea to have an EmailAddress typed value for emails suggests that the generic Resource object is too simplistic. We might better use a specific type for each of the "phones", "email", .. properties.

>  * I don't think the `labels` property of a Resource should be multi-valued (it should just be `label`, like it is in the `Address` data type). While there's always a tension here between allowing expressivity and keeping it easier to use, I think this veers too much into the former. It's not clear how you would be supposed to deal with multiple values; as they are just free form text, a single one should be sufficient.

Works for me.

>  * I think the `Address` type needs thinking about more. The street/locality/region properties are not sufficient to accurately express many global addresses. An array of tagged components like in `name` is probably a better approach, allowing many more options for accurately describing the parts of the address without making it too unwieldy to use.

We had discussed internally if to use tagged components also for addresses, and we will also raise this discussion item at IETF 110 today. I initially vouched for tagged components, but now I am not as convinced anymore. 

The Wikipedia article on address formats suggests that the current scheme covers the majority of addresses in use globally (https://en.wikipedia.org/wiki/Address#Address_format). In addition, we cross-checked with the address APIs of services such as such as Google, Microsoft and Baidu, and came to realize that we can cover all of their address formats (except that we'll need to separate out the street number from the street field).

That being said, the current scheme might not be enough. It would be great to see examples of addresses it can't cover. Also, we are not experts on address schemes. I think we had a contact to a major delivery service once at CalConnect. I'll try to reach out to him. We are also aware of the ISO group efforts for a new address standard, but their approach seems to add considerably more complexity. It might be too much for a Contacts API. I think they will present at next CalConnect, so let's see what we can learn there.

>  * As with name, I think the purpose of `fullAddress` would need to be detailed more (if it is indeed needed at all).

We'll make clear that its main purpose it to allow for localized addresses.

>  * I think the `notes` field should be single-valued rather than an array, for the same reason as with `labels`.

Works for me.

Cheers,
Robert