Subject: [apps-discuss] AD Review of draft-ietf-appsawg-json-merge-patch-05

From: Barry Leiba <[email-masked]>
Date: Wed, 23 Jul 2014 10:17:40 -0400

This looks good and solid: thanks, James, and thanks to Paul for picking it up.

I have just a few very minor comments, below.  They're tiny, and they
won't hold anything up.  I'll request last call on Friday.  But if you
want to post an -06 before then, please do.

Barry

--------------------------------------------
The only place there's a 2119 key word is in Section 2:

   To apply the merge patch document to a target resource, the system
   MUST realize the effect of the following function, described in
   pseudocode.

I suggest that you word that without the "MUST" (remembering that text
doesn't have to say "MUST" in order to specify a requirement), and
remove the 2119 boilerplate and reference.  I think simply changing
"MUST realize" to "realizes" will work fine.

-- Section 2 --
"Textural" has to do with texture.  Please replace it with "textual".

-- Section 3 --

   A user-agent wishing to change the value of the "title" member from
   "Goodbye!" to the value "Hello!", add a new "phoneNumber" member,
   remove the "familyName" from the "author" object, and remove the word
   sample from the "tags" Array, would send the following request:

I wonder whether it'd be better to phrase the last change differently:
you're not actually removing an array element; you're replacing the
array with a new array that does not contain that element.  It's a
subtle difference, but I think it's useful to avoid implying that you
can use this to alter an array without replacing the whole array
(consider a case where someone had a large array, and wanted to remove
the first element).

Maybe this?:

NEW
   A user-agent wishing to change the value of the "title" member from
   "Goodbye!" to the value "Hello!", add a new "phoneNumber" member,
   remove the "familyName" member from the "author" object, and replace
   the "tags" Array so that it doesn't include the word "sample", would
   send the following request:
END
--------------------------------------------

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 23 Jul 2014 18:00:25 -0400

I'll work on this on Thursday morning and get the new draft in. We already got a few nits, including "textural".

--Paul Hoffman