Subject: [alto] Suresh Krishnan's No Objection on draft-ietf-alto-incr-update-sse-20: (with COMMENT)

From: Suresh Krishnan via Datatracker <[email-masked]>
Date: Wed, 11 Mar 2020 09:20:07 -0700

Suresh Krishnan has entered the following ballot position for
draft-ietf-alto-incr-update-sse-20: No Objection

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-alto-incr-update-sse/

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Section 3.1.1.:
  I feel strongly that this document should not restate the pseudo-code for the
  JSON merge patch algorithm and should instead use a reference to Section 2 of
  RFC7396 instead. This will avoid inconsistencies (e.g. note that the pseudo
  code in this draft is *already different* from that in RFC7396 even though
  the difference is only the braces) and be amenable to updates to RFC7396.

References:

Is there a reason this document is using the obsoleted JSON reference to
RFC7159? Suggest updating the reference to RFC8259.

---

From: "Y. Richard Yang" <[email-masked]>
Date: Wed, 11 Mar 2020 16:49:19 -0400

Dear Suresh,

Thanks for the review! Please see inline.

> https://datatracker.ietf.org/doc/draft-ietf-alto-incr-update-sse/
This is an interesting discussion point. In an earlier version, the authors
had some back-and-forth on including the pseudo-code or not. The "include"
argument "won" because it makes the document more self-contained and a
potentially more pleasant read---a reader does not need to track down a
separate document to find the pseudo-code, and we are referring to a
"fixed" document---I can see your argument that there can be Errata/Update
to the RFC7396 pseudocode. It is amazing that you caught the difference in
braces vs : ! One proposal is that we change to the exact format
(replace braces with {) as in RFC 7396 and keep the pseudocode. Or let the
coauthors discuss a bit more and get a conclusion in the next couple of
days. How does this sound?

> RFC7159? Suggest updating the reference to RFC8259.
Good catch. We are updating to RFC 8259. Thanks!

Thanks again.
Richard

---

From: Mirja Kuehlewind <[email-masked]>
Date: Thu, 12 Mar 2020 11:23:17 +0100

Hi Richard,

The concern is that RFC7396 could be updated by another RFC or even obsoleted. Therefore duplicating any formal specification should be avoided and it’s actually a feature that people have to look up RFC7396. I recommend to remove the pseudo code and replace it by a few sentences that loosely described the scheme.

Mirja

> On 11. Mar 2020, at 21:49, Y. Richard Yang <[email-masked]> wrote:
> 
> Dear Suresh,
> 
> On Wed, Mar 11, 2020 at 12:20 PM Suresh Krishnan via Datatracker <[email-masked]> wrote:
> This is an interesting discussion point. In an earlier version, the authors had some back-and-forth on including the pseudo-code or not. The "include" argument "won" because it makes the document more self-contained and a potentially more pleasant read---a reader does not need to track down a separate document to find the pseudo-code, and we are referring to a "fixed" document---I can see your argument that there can be Errata/Update to the RFC7396 pseudocode. It is amazing that you caught the difference in braces vs : ! One proposal is that we change to the exact format (replace braces with {) as in RFC 7396 and keep the pseudocode. Or let the coauthors discuss a bit more and get a conclusion in the next couple of days. How does this sound? 
>  
> References:
>

---

From: Jensen Zhang <[email-masked]>
Date: Thu, 12 Mar 2020 11:29:44 -0400

Hi Suresh, Mirja and Richard,

To make the content consistent, I agree that we should not duplicate the
formal specification. But I don't think it should be a loose dependency.
Personally, I think we should strictly refer to RFC7396, even though it
could be updated or obsoleted. If it is a loose dependency, an ALTO client
adopting the old specification may not be compatible with the ALTO server
adopting the new specification. We should make sure all the clients/servers
based on this document are compatible in any case. If RFC7396 is updated or
obsoleted in the future, we can also update this document.

Jensen

On Thu, Mar 12, 2020 at 6:23 AM Mirja Kuehlewind <[email-masked]>
wrote:

> Hi Richard,
>
> The concern is that RFC7396 could be updated by another RFC or even
> obsoleted. Therefore duplicating any formal specification should be avoided
> and it’s actually a feature that people have to look up RFC7396. I
> recommend to remove the pseudo code and replace it by a few sentences that
> loosely described the scheme.
>
> Mirja
>
>
>
> > Please refer to
> https://www.ietf.org/iesg/statement/discuss-criteria.html
> > This is an interesting discussion point. In an earlier version, the
> authors had some back-and-forth on including the pseudo-code or not. The
> "include" argument "won" because it makes the document more self-contained
> and a potentially more pleasant read---a reader does not need to track down
> a separate document to find the pseudo-code, and we are referring to a
> braces vs : ! One proposal is that we change to the exact format (replace
> braces with {) as in RFC 7396 and keep the pseudocode. Or let the coauthors
> discuss a bit more and get a conclusion in the next couple of days. How
> does this sound?
> >
> > References:
> >
> _______________________________________________
> alto mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/alto
>

---

From: "Y. Richard Yang" <[email-masked]>
Date: Thu, 12 Mar 2020 12:13:16 -0400

- add Adam explicitly.

Hi Jensen,

Not sure by loose dependency, what you meant. The current approach is to
revise the current document to include key features/notes of the algorithm.
We will plan to use the change below:

Old

   To avoid always sending complete data, a server needs mechanisms to
   encode incremental changes.  This design uses JSON merge patch as one
   mechanism.  Below is a non-normative summary of JSON merge patch; see
   [RFC7396 <https://tools.ietf.org/html/rfc7396>] for the normative definition.

   JSON merge patch is intended to allow applications to update server
   resources via the HTTP patch method [RFC5789
<https://tools.ietf.org/html/rfc5789>].  This document adopts

   the JSON merge patch message format to encode incremental changes,
   but uses a different transport mechanism.

   Informally, a JSON merge patch object is a JSON data structure that
   defines how to transform one JSON value into another.  Specifically,
   JSON merge patch treats the two JSON values as trees of nested JSON
   objects (dictionaries of name-value pairs), where the leaves are
   values (e.g., JSON arrays, strings, numbers) other than JSON objects
   and the path for each leaf is the sequence of keys leading to that
   leaf.  When the second tree has a different value for a leaf at a
   path, or adds a new leaf, the JSON merge patch tree has a leaf, at
   that path, with the new value.  When a leaf in the first tree does
   not exist in the second tree, the JSON merge patch tree has a leaf
   with a JSON "null" value.  The JSON merge patch tree does not have an
   entry for any leaf that has the same value in both versions.

   As a result, if all leaf values are simple scalars, JSON merge patch
   is a quite efficient representation of incremental changes.  It is
   less efficient when leaf values are arrays, because JSON merge patch
   replaces arrays in their entirety, even if only one entry changes.

   Formally, the process of applying a JSON merge patch is defined by
   the following recursive algorithm, as specified in [RFC7396
<https://tools.ietf.org/html/rfc7396>]:

     define MergePatch(Target, Patch) {
       if Patch is an Object {
         if Target is not an Object {
           Target = {} # Ignore the contents and
                       # set it to an empty Object
         }
         for each Name/Value pair in Patch {
           if Value is null {
             if Name exists in Target {
               remove the Name/Value pair from Target
             }
           } else {
             Target[Name] = MergePatch(Target[Name], Value)
           }
         }
         return Target
       } else {
         return Patch
       }
     }

   Note that null as the value of a name/value pair will delete the
   element with "name" in the original JSON value.

New

   To avoid always sending complete data, a server needs mechanisms to
   encode incremental changes.  This design uses JSON merge patch as one
   mechanism.  Below is a non-normative summary of JSON merge patch; see
   [RFC7396 <https://tools.ietf.org/html/rfc7396>] for the normative definition.

   JSON merge patch is intended to allow applications to update server
   resources via the HTTP patch method [RFC5789
<https://tools.ietf.org/html/rfc5789>].  This document adopts

   the JSON merge patch message format to encode incremental changes,
   but uses a different transport mechanism.

   Informally, a JSON merge patch message consists of a JSON merge patch
   object (referred to as a patch in [RFC7396]), which defines
   how to transform one JSON value into another using a recursive
   merge patch algorithm.
   Specifically, the patch is computed by treating two JSON values (first one
   being the original, and the second being the updated) as trees
   of nested JSON objects (dictionaries of name-value pairs), where the
   leaves are values (e.g., JSON arrays, strings, numbers) other than
   JSON objects and the path for each leaf is the sequence of keys leading
   to that leaf.  When the second tree has a different value for a leaf at a

   path, or adds a new leaf, the patch has a leaf, at
   that path, with the new value.  When a leaf in the first tree does
   not exist in the second tree, the JSON merge patch tree has a leaf
   with a JSON "null" value. Hence, in the patch, null as the value of
   a name/value pair will delete the element with "name" in the original
   JSON value. The patch does not have an entry for any leaf that has the same
   value in both versions. See the MergePatch pseudocode

   at the beginning of Section 2 of [RFC7396] for the formal specification of
   how to apply a given patch.

   As a result, if all leaf values are simple scalars, JSON merge patch
   is a quite efficient representation of incremental changes.  It is
   less efficient when leaf values are arrays, because JSON merge patch
   replaces arrays in their entirety, even if only one entry changes.

====

If there is an objection, please do let us know.

Thanks,
Richard

---

From: Jensen Zhang <[email-masked]>
Date: Thu, 12 Mar 2020 12:34:23 -0400

Hi Richard,

The current revision sounds good to me.

Sorry for the confusion. The "loose dependency" refers to what Mirja said
("... replace it by a few sentences that loosely described the scheme.")
Maybe I misunderstood it. I thought Mirja suggested when the RFC7396 is
updated in the future, the sentences in this document should also imply the
updated specification. What I suggest is that we should use a fixed
specification, not an adaptive one.

Thanks,
Jensen

On Thu, Mar 12, 2020 at 12:13 PM Y. Richard Yang <[email-masked]> wrote:

>    resources via the HTTP patch method [RFC5789 <https://tools.ietf.org/html/rfc5789>].  This document adopts
>
>    the following recursive algorithm, as specified in [RFC7396 <https://tools.ietf.org/html/rfc7396>]:
>
>    resources via the HTTP patch method [RFC5789 <https://tools.ietf.org/html/rfc5789>].  This document adopts
>