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

[Neil Jenkins <[e-mail]>]

Hi Mahesh,

Thank you for your review.

On Tue, 21 May 2024, at 10:56, Mahesh Jethanandani via Datatracker wrote:
> Section 2.3, paragraph 3
> >       If false, any attempt to destroy an AddressBook that still has
> >       ContactCard in it will be rejected with an addressBookHasContents
> >       SetError.  If true, any ContactCards that were in the AddressBook
> >       will be removed from it, and if in no other AddressBooks they will
> >       be destroyed.
> 
> The "if true" condition is not clear to me, especially if other AddressBooks
> exist. There is a distinction that is being drawn between removing a
> ContactCard and destroying it, which is not apparent. Can that distinction be
> explained?

I will explain, but I'm not sure how to reword this to make it more obvious. Quoting from the data model overview <https://www.ietf.org/archive/id/draft-ietf-jmap-contacts-09.html#name-data-model-overview>:

*A ContactCard is a representation of a person, company, or other entity, or a group of such entities […]. Each ContactCard belongs to one or more AddressBooks.*

And from the definition of ContactCard <https://www.ietf.org/archive/id/draft-ietf-jmap-contacts-09.html#name-contactcards>:
 • **addressBookIds***: *`*Id[Boolean]*`*
**The set of AddressBook ids this ContactCard belongs to. A card MUST belong to at least one AddressBook at all times (until it is destroyed).*
So the way ContactCards are associated with AddressBook objects is via a property on the ContactCard. The API enforces consistency — you can't have an id in the ContactCard's `addressBookIds` property that's not a currently valid AddressBook. So if you try to destroy an AddressBook that is currently referenced by a ContactCard we can do one of two things to ensure the data remains consistent:
 • Reject the destroy (this is the default).
 • Update the ContactCards that currently reference the AddressBook. This is what happens if you set `onDestroyRemoveContents` to true. It removes the now non-existent AddressBook id from the ContactCard's `addressBookIds` property. But all ContactCards MUST be associated with at least one AddressBook at all times, so if this was the only AddressBook it was in, we will destroy the ContactCard instead to ensure the data consistency constraints are upheld.
Intuitively you can think of it like this: every contact is in an address book. If you delete the address book, it cascades the delete to the contacts in it, except for those that are still in another (non-deleted) address book.

Does that clarify? I think that the original text will probably be clear enough for anyone implementing this, who will probably have more time to understand the whole data model first. But I am open to suggestions on how to reword this to make it easier to parse without deeper understanding.

> Related to that, it appears the ContactCards that were part of an AddressBook
> that is being deleted, will be moved if another AddressBook exists.

As per the above, that's not correct. The ContactCard may already be in another AddressBook as well (think of the AddressBooks as more like labels in this regard), however it will not be automatically added to another one.

> Section 3, paragraph 2
> >    *  *addressBookIds*: Id[Boolean]
> >       The set of AddressBook ids this ContactCard belongs to.  A card
> >       MUST belong to at least one AddressBook at all times (until it is
> >       destroyed).  The set is represented as an object, with each key
> >       being an AddressBook id.  The value for each key in the object
> >       MUST be true.
> 
> What happens if a ContactCard is removed from an AddressBook that is present in
> multiple AddressBooks? Is it removed from all AddressBooks, or just one?

I'm not sure I fully understand your question here, but let me provide an example to perhaps clarify:

You have two AddressBooks in an account:
 • Work
 • Personal
You have a ContactCard representing Bill. Bill is your friend *and* colleague, and you have placed him in both address books. Some things that could happen:
 • Bill leaves the company. You update Bill's ContactCard (using a JMAP Contact/set method call) to change the `addressBookIds` property, removing Bill from the Work address book but leaving the card in your Personal address book.
 • You leave the company. You destroy the Work AddressBook, with `onDestroyRemoveContents` set to true. Because Bill's contact is also in your Personal address book, it is implicitly updated as above (to remove it from the now-destroyed Work AddressBook), but otherwise unchanged. Any contacts just in the Work AddressBook will have been destroyed.
 • Bill leaves the company and you have a massive fight, to the point you are no longer friends. You destroy Bill's contact card (again, using a JMAP Contact/set method call).
Does that help? If not, could you please rephrase to help me understand the question?

> If it is removed from all AddressBooks, how does a user who wants to trim the
> AddressBook to certain contacts remove a ContactCard?

You can't update a ContactCard to not be in any AddressBook (that update would be rejected by the server). You can destroy the ContactCard instead.

> Section 2, paragraph 12
> > w AddressBooks created by the user themself. If false, the AddressBook and it
> >                                    ^^^^^^^^
> Generally speaking, "themself" is only acceptable when referring to a singular
> entity (such as the singular usage of "they", which is the preferred pronoun
> for many non-binary people). If "themself" refers to a plural entity (such as
> "everybody", or the standard usage of "they"), you should use "themselves".

As "the user" is singular, I believe the current wording is correct,

> Section 2.3, paragraph 3
> > s, it MUST be ignored and the currently default AddressBook (if any) will rem
> >                               ^^^^^^^^^^^^^^^^^
> You used an adverb ("currently") instead of an adjective, or a noun ("default")
> instead of another adjective.

I believe the current phrasing is clear and reasonable; I'll leave this and revisit if the RFC editors flag it.

Cheers,
Neil.