Re: [calsify] Artart last call review of draft-ietf-calext-jscontact-07

[Robert Stepanek <[e-mail]>]

Hi Martin,

we just published a new RFC draft version. Please find our remarks to your feedback below.

On Thu, Jun 22, 2023, at 9:39 AM, Martin J. Dürst wrote:
> > Which specific parts of the data model use too many levels? How would a straight-forward design for these look like?
> 
> As a simple example, why
> 
>    "name": {
>      "components": [{
>        "kind": "given",
>        "value": "John"
>      }, {
>        "kind": "surname",
>        "value": "Doe"
>      }]
>    }
> 
> and not just
> 
>    "name": [ { "given": "John" }, { "surname": "Doe" } ]
> 
> or maybe
> 
>    "name": {
>      "components: [ { "given": "John" }, { "surname": "Doe" } ]
>    }


We actually had tested defining components in the form:

"components: [
  ["given", "John"],
  ["surname", "Doe"],
  ["middle", "M.", {
    "example.com:foo", "bar"
  }
]

that is, a component is either an array of length 2 (kind, value) or length 3, where for the latter the third value is an object that allows for extending that component.

We decided against it: using the above form for names and addresses would either be inconsistent with the rest of property definitions, or would require to use a similar scheme for all of them. We do think that proper names trump positional arguments if order is not relevant, both for readability and correctness.

> 
> > How is JSON-LD, a Linked Data format, relevant in the context of JSContact?
> 
> At IETF 116, I asked around to find somebody who might be able to 
> explain the design decisions re. JSON in this draft, and somebody 
> (sorry, forgot who that was) mentioned JSON-LD. Then I had a quick look 
> at JSON-LD, and found a @type attribute, so I thought there was a 
> connection. But as I say above, it's not exactly JSON-LD.

We did not take JSON-LD into consideration at all. We now renamed the "@version" property to "version", if only to avoid confusion.

But for "@type" we want to stay consistent with JSCalendar (RFC 8984), and that RFC already defines the "@type" property in section 4.1.1.

> >> - I'm not usually doing this, but by chance, I read the Gen-ART review
> >>    for this document. I fully support it. In particular with respect to
> >>    legal vs. preferred names, there's also the example of researchers
> >>    preferring to use their maiden name in an academic context, and there
> >>    are cases of people with multiple nationalities that may have
> >>    different names in each nationality because of legal requirements
> >>    (the last case is orthogonal to the locale/script issue).
> > 
> > Version 10 defines the name property as "This can be any type of name, e.g. it can but need not be the legal name of a person".
> > 
> > We chose not to support multiple names in order to stay compatible with vCard in this matter. Would it help to have one "main" name and multiple "alternative" names?
> 
> You already have multiple locales. People could give different names in 
> the different locales. In some cases, that would be exactly the right 
> thing, but it would be a bad idea to have to use locales to 'cheat' in 
> order to be able to represent multiple names.

I am not against supporting multiple names on principle. We just could not find a way to make that interoperate with vCard  implementations, and in this initial specification we do not want JSContact to deviate too far from vCard.

For example, before we redefined the vCard ADR property in version 08 of draft-ietf-calext-vcard-jscontact-extensions we tested how existing vCard implementations deal with these changes. We concluded that they ignore them, which is good enough for us for backwards-compatibility. For names, however, we found that most implementations broke for multiple names or extended N property values.

A lot of existing addressbook and contact applications seem to center their model around a contact name. Even if JSContact would allow multiple names, it is very likely that we would need to come up with some way to define a single "main" name and some optional additional names. I would rather want to see such a model be defined in an extension to JSContact that also describes how to handle them in vCard.

> >> - Some (names or) addresses in the Near East (Arabic/Hebrew/... script)
> >>    may contain data of mixed directionality (right-to-left as well as
> >>    left-to-right). The document contains absolutely no information about
> >>    how to deal with such issues.
> > 
> > The document defines "locale" as top-level property to indicate a default locale for text contained in the Card, as well as the "localizations" property for specific text elements. We consider supporting multiple locales within a single String property out of scope.
> 
> This is NOT about supporting multiple locales within a single String. 
> It's about bidirectionality. The fact that a name or address, or a 
> component thereof, is in a certain locale doesn't guarantee that all the 
> characters in that piece have the same directionality.

The definition of the "language" property now states:

How to render text is out of scope of this specification, e.g., refer to [https://www.unicode.org/reports/tr9/] how to deal with different writing directions.

> My comment was on a higher level: a) How are you going to make sure that 
> for those cases where you have an example in your spec (i.e. the above 
> Russian patronymic), people follow your spec (even though it's just an 
> example). b) How are people in cultures where there are no examples in 
> your spec going to figure out which parts of their local naming 
> conventions correspond to which pieces in the spec, in a way that 
> results in an uniform use of pieces for components in that locale (and 
> hopefully locales with equivalent phenomena).

We revisited all examples, including the ones you kindly contributed to. If you find any further issues in the new RFC version we will be happy to update it accordingly.

Based on the feedback around international addresses and names, we added additional address components, giving multiple examples for what they may be used for. We also aligned the name components with the Personal Name formatting guidelines of Unicode.

In the end though, it is always up to implementations what to choose from the available options.

> >> 1.9.1: What about case sensitivity? ABNF is case insensitive, but
> >> as far as I understand, JSON object keys are case sensitive.
> > 
> > The property names are case-sensitive.
> 
> So in
>        "kind": "given",
>        "value": "John"
> both "kind" and "value" are case sensitive because of JSON, and because 
> of what your spec says about member names in JSON objects (1.3). But 
> what about "given"? Would "Given" or "GIVEN" be okay? Where does the 
> spec say so?

We now state that string values are case sensitive.

> Would you expect CardGroup documents (or any future new kinds of 
> documents) to be handled to different applications than Card documents? 
> Or would you expect applications to not be able to distinguish between 
> these different kinds of documents?
> If not, what purpose does the parameter serve?

We now removed the "type" parameter.

> 
> >> 2.1.5 locale, and 2.7.1: It may often be the case that a single
> >> set of data could be suited for more than one locale, but this
> >> cannot be expressed currently.
> >>
> >> The spec forces one of the locales to be the 'main' locale, the others to be
> >> localizations. This is quite in contrast to most other parts, where
> >> alternatives are treated on an equal footing, maybe with some preference
> >> indication. Why this inbalance? It may be inappropriate for some applications
> >> or users. (what if there's a requirement to treat different localizations as
> >> equivalent?)
> > 
> > A localization need not override all properties, it can just override a subset.
> 
> Looking at the algorithm again, that's indeed the case. Maybe it would 
> be good to have an example where that actually happens (both Fig. 36 and 
> 37 have 'complete' localizations).

The section of the "localizations" property now contains examples for that.

> > Any property values that are not localized are available across all localized variants of the Card. Likewise, a localization can remove a property without setting a new value, if the property value in the main Card would not be appropriate for that locale.
> > 
> >>
> >> 2.1.6: Using 'true' values rather than simply an array of UUIDs
> >> seems somewhat abstruse. Where does this kind of stuff come from?
> > 
> > JSContact, and RFC 8984, are designed to work well with the JMAP protocol (RFC 8620), which does not allow to remove single items of an array. A JSON set is the idiom in this context.
> 
> If the JSON spec defines sets, then that should be referenced. If 
> another spec defines JSON sets, then that should be referenced, even if 
> just informally.

The JSON spec does not define sets, nor does any other to my knowledge. It is an idiom used in both the documents of the jmap working group and JSCalendar (RFC 8984).

> I'm surprised you use "Irgendwostrasse" (would be okay in Switzerland) 
> and not "Irgendwostraße" (the correct form in Germany and Austria).

This was just me (an Austrian) typing on a US keyboard. That address is not part of the examples anymore.

> 
> As for "3 Chome-7-1 Nishishinjuku, Shinjuku City, Tokyo, Japan",
> { "kind": "apartment", "value": "3" } is definitely wrong.
> More compact, this is 3-7-1 Nishishinjuku, Shinjuku City, Tokyo, Japan
> More expanded, this is 3 Chome 7 Ban 1 Go Nishishinjuku, Shinjuku City, 
> Tokyo, Japan
> In Japanese (fully outside-in), it is 東京都新宿区西新宿3-7-1 or
> 東京都新宿区西新宿3丁目7-1 or 東京都新宿区西新宿3丁目7番1号。
> 3 is the number of a rather big block (including two Hotels and Tokyo 
> Opera City), not an apartment number.
> 
> In general (there are some exceptions), Japanese addresses have three 
> numbers for the smallest blocks (which may be a single apartment 
> building or a few small single-family houses; if there's an apartment 
> number, it's usually the fourth number.

Thanks again, we now updated the Japanese address example.

Regards,
Robert