[Jmap] Re: Orie Steele's Discuss on draft-ietf-jmap-contacts-09: (with DISCUSS and COMMENT)

[Neil Jenkins <[e-mail]>]

Hi Orie,

Thank you for your review.

> ### UID vs UUID
> 
> I suggest the following clarifications:
> 
> Add "UID" to your terminology since it is not defined in RFC8620.
> 
> Something like:
> 
> ```
> UID:
> : A unique identifier. UUID as defined RFC9562 is RECOMMENDED, but for backward
> compatibility it MAY be a free-text value, see RFC9553 Section 2.1.9 for
> details. ```
> 
> Then instead of:
> 
> ```
> 309        *  *id*: Id (immutable; server-set)
> 310           The id of the ContactCard.  The id uniquely identifies a
> 311           ContactCard with a particular "uid" within a particular account.
> ```
> 
> Consider this alternative text:
> 
> """
> The id of the ContactCard. The id MUST be a UID as defined in Section 1.2 of
> this document. """

This is not actually what the document is saying. The "uid" is a globally unique identifier for a card, defined in the JSContact spec <https://www.rfc-editor.org/rfc/rfc9553.html#name-uid>. It is a property of the data. When accessed over JMAP, each card will get an "id", which may be completely different (and not necessarily a UUID) that is used to identify it over the JMAP protocol.

JMAP has the concept of an Account. Modifications within an account are transactional, and certain data consistency rules can be enforced. (You may have access to multiple accounts from a single login, e.g. if someone is sharing data with you).

Given that context, I have rewritten the description to be clearer I hope:
 • *id*: `Id` (immutable; server-set)
The id of the ContactCard. The id property MAY be different to the ContactCard's "uid" property (as defined in RFC9553, Section 2.1.9 <https://www.rfc-editor.org/rfc/rfc9553.html#name-uid>). However, there MUST NOT be more than one ContactCard with the same "uid" in an Account.
> Later:
> 
> ```
> 371        *  *uid*: String
> 372           A card must have this string exactly as its uid to match.
> ```
> 
> "id" or "uid" ?

This is meant to be "uid". You don't need to do a query to find a record if you have its id, you can just just get it directly. I have updated this (and all the other filter properties) to reference the appropriate section of the JSContact spec to make this clearer.

> ### Whats a "data: URI"
> 
> ```
> 326        When returning ContactCards, any Media with a data: URI SHOULD return
> ```
> 
> Please add a reference to RFC2397.

Yes, done.

> ### Intended Use: Reserved
> 
> ```
> 748     7.5.3.  blobId
> 
> 750        Property Name: blobId
> 
> 752        Property Type: Not applicable
> 
> 754        Property Context: Media
> 
> 756        Intended Use: Reserved
> 
> 758        Since Version: 1.0
> 759        Change Controller: IETF
> ```
> 
> The current registry contains no "Reserved" entries, and RFC8620 does not
> define "reserved".
> 
> What does "Reserved" mean?

These registrations are for the JSContact properties registry, not a JMAP registry — the "reserved" use is defined in RFC9553, Section 3.3 <https://www.rfc-editor.org/rfc/rfc9553.html#name-registry-policy-and-change->. I have added an RFC reference here to make this more obvious.

> ## Comments
> 
> ### AddressBook description string length
> 
> ```
> 173        *  *description*: String|null (default: null)
> 
> 175           An optional longer-form description of the AddressBook, to provide
> 176           context in shared environments where users need more than just the
> 177           name.
> ```
> 
> Is there an octet limit for this field (and all other string fields), or a
> least a max length recommendation?

No. The server always has the right to reject an update as too large, but across all the JMAP data types there are a lot of fields and generally we haven't mandated particular limits, except where it's particularly important the string is short.

> ### Enumerations vs Booleans
> 
> ```
> 229        An *AddressBookRights* object has the following properties:
> 
> 231        *  *mayRead*: Boolean
> 232           The user may fetch the ContactCards in this AddressBook.
> 233        *  *mayWrite*: Boolean
> 234           The user may create, modify or destroy all ContactCards in this
> 235           AddressBook, or move them to or from this AddressBook.
> 236        *  *mayAdmin*: Boolean
> 237           The user may modify the "shareWith" property for this AddressBook.
> 238        *  *mayDelete*: Boolean
> 239           The user may delete the AddressBook itself.
> ```
> 
> Later:
> 
> ```
> 564                "addressBookIds": {
> 565                  "062adcfa-105d-455c-bc60-6db68b69c3f3": true
> 566                },
> ```
> 
> I wonder why these are not modeled as:
> 
> ```
> "<className>Ids": [<id or uid>]
> ```
> 
> Perhaps the object syntax is used to anticipate extension?

The object syntax is more amenable to patching — with JMAP you generally send efficient patches to update an object rather than the whole thing. This format is used to model sets throughout JMAP APIs for this reason.

> ### Access Control Policy
> 
> ```
> 282        The "shareWith" property may only be set by users that have the
> 283        mayAdmin right.  When modifying the shareWith property, the user
> 284        cannot give a right to a principal if the principal did not already
> 285        have that right and the user making the change also does not have
> 286        that right.  Any attempt to do so MUST be rejected with a forbidden
> 287        SetError.
> ```
> 
> This is discretionary access control? Consider a citation and an example that
> is not `"shareWith": null,` in Section 4.1.

I've added a sharee to one of the address books in the example section.

Cheers,
Neil.