Subject: [core] Resource Directory - Patch

From: Jim Schaad <[email-masked]>
Date: Tue, 5 Sep 2017 20:54:42 -0700

Somewhere during the day today I had a major paradigm shift in my thinking
about how PATCH was supposed to work and a great deal of what is written in
the document suddenly became much clearer.  I was operating under the
mistaken impression that the "document" that was being patched was the same
for the add, change and delete cases and it is not.  The add case is
operating on the array of registration elements while the change and delete
cases are operating on individual registration elements.  With that shift in
how things work the different patch examples became much easier to follow.

So, with this new understanding I am going to try some different questions
about PATCH.

1.  Is there a good reason to support the addition of new resources in two
different methods?  Addition of new resources can already be done through
the POST method, needing to recognize that the documents to be patched are
different is a potential error waiting to happen if this is not well
described in document.

2.  For the delete case, the patch string of {"href":null}  is more in line
with how I understand a JSON patch document to be designed.  The string of
{} would say that nothing is to be changed by default unless it is special
cased.  Setting the value of the href to absent or null would be easily
understood as saying remove the element.

3.  The text on patch needs to be clear on how to treat a patch document
where multiple occurrences of an attribute to modify occur in the patch
document.  It should also be clearer on the correct way to deal with
updating multiple occurrences of the attribute in the link document.  My
reading of the current text could end up with "</foo>;alpha=beta;alpha=beta"
as the output if the input was "</foo>;alpha=gamma;alpha=delta" and the
patch was {alpha:"beta"}.   I am not sure that is what you want to be
saying.

4.  This paragraph is missing some text I believe:

If the PATCH payload results in the modification of link target,
   context, or relation values, that is "href", "rel", or "anchor", the
   request SHOULD be rejected with a "Conflict" result code.

Why is this a SHOULD and not a MUST.  If you keep it as a MUST some guidance
on which rejections SHOULD occur and when they are acceptable would be
highly desirable.  Making it a MUST means that a Conflict response would not
be able to occur if I have my logic correct for anything other than an
addition request.

Jim