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

[Mahesh Jethanandani <[e-mail]>]

Hi Neil,

My responses inline.

> On May 31, 2024, at 7:07 AM, Neil Jenkins <[e-mail]> wrote:
> 
> 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.

Thanks for that explanation. How about this?

OLD:
If false, any attempt to destroy an AddressBook that still has ContactCard in it will be rejected with an addressBookHasContentsSetError. If true, any ContactCards that were in the AddressBook will be removed from it, and if in no other AddressBooks they will be destroyed.

NEW:
If false, any attempt to destroy an AddressBook that still has ContactCard in it will be rejected with an addressBookHasContentsSetError. If true, any ContactCard that is in the AddressBook that is set to be destroyed. will be removed from it, and if the ContactCard does not exist in any other AddressBooks it will be destroyed.


> 
>> 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?

Sure. 

My question is about a ContactCard that is present in multiple AddressBooks. Take your example above, Bill appears in two AddressBooks, Work and Personal. And I will take the example of Apple’s Contacts App that I use. I use the search capability in the App to find the ContactCard for Bill, find it, select it, and hit the delete button. What happens?

Per your explanation above, I am not sure what will happen. Because per the description, the only way to delete Bill is for me is to select the AddressBook called Work, find Bill, remove it, then select AddressBook Personal, find Bill again, and then remove it. Then and only then Bill's ContactCard will be destroyed. Is that true?

> 
>> 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.

My question is slightly different. Take your above example again. It was, what happens if I want to remove Bill from the Work AddressBook? But I think I got the answer from the example above. It will be removed from the Work AddressBook, but will remain in the Personal AddressBook.

Which brings me to the comment I made initially. You are making a distinction between removing a ContactCard, and destroying it. Based on all the explanations, what I understand is:

remove: A ContactCard can be removed from an AddressBook, but MAY NOT be destroyed.
destroy: Once a ContactCard is removed from the last AddressBook that it is existed it, it is destroyed

If this distinction sounds right, it would help to make that distinction clear up front.

Thanks.

> 
>> 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.


Mahesh Jethanandani
[e-mail]