Subject: [apps-discuss] merge-patch in APPSA and i-json in JSON

From: Larry Masinter <[email-masked]>
Date: Tue, 8 Jul 2014 17:27:10 +0000

I don't like to cross-post, but it seems appropriate for this narrow topic:

JSON WG is defining i-json profile in draft-ietf-json-i-json
APPSA WG is defining merge operation data structure in draft-ietf-appsawg-json-merge-patch 
Both are nearing WG last call.

Reading in prep for Toronto, I have questions I can't readily answer looking at the two documents:
- Does application/merge-patch+json require/default to the i-json profile?
- Is merge operation defined for target JSON that isn't i-json?
- If so, does it preserve i-json? (is the result i-json if the original was  i-json?
- Or is merge required to, or allowed to, ALWAYS produce i-json?

You'd think it should be easy to answer these questions given the two documents. Perhaps I'm missing the obvious. If there's a problem, I'm not sure which one would need to change. Possibly both. Could we see some editorial collaboration to make the answers clearer? 

Larry
--
http://larry.masinter.net

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 8 Jul 2014 10:36:35 -0700

> - Does application/merge-patch+json require/default to the i-json profile?

No. draft-ietf-appsawg-json-merge-patch doesn't mention I-JSON.

> - Is merge operation defined for target JSON that isn't i-json?

Yes. The merge operation is defined for all targets, regardless of the targets' profile of JSON.

> - If so, does it preserve i-json? (is the result i-json if the original was  i-json?

There is no assurance of that; it is orthogonal. draft-ietf-appsawg-json-merge-patch doesn't do anything special for any profile of JSON.

> - Or is merge required to, or allowed to, ALWAYS produce i-json?

No. draft-ietf-appsawg-json-merge-patch doesn't mention I-JSON.

> You'd think it should be easy to answer these questions given the two documents.

It is easy: draft-ietf-appsawg-json-merge-patch doesn't mention I-JSON.

> Perhaps I'm missing the obvious.

It seems that you are. draft-ietf-appsawg-json-merge-patch doesn't mention I-JSON.

> If there's a problem, I'm not sure which one would need to change. Possibly both. Could we see some editorial collaboration to make the answers clearer? 

There is no reason for draft-ietf-appsawg-json-merge-patch to consider any profile of JSON.

--Paul Hoffman

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 8 Jul 2014 12:11:34 -0700

On Jul 8, 2014, at 12:06 PM, John Cowan <[email-masked]> wrote:

> Paul Hoffman scripsit:
> Actually, it isn't.  It is far from clear from
> draft-ietf-appsawg-json-merge-patch-04 what to do if a key appearing in
> the patch matches more than one key appearing in the target.  This has
> nothing to do with I-JSON as such, but is a deficiency in the merge-patch
> algorithm, the relevant part of which I reproduce here:
> 
>       for each Key/Value pair in Patch:
>         if Value is null:
>           if Key exists in Target:
>             remove the Key/Value pair from Target
>         else:
>           Target[Key] = MergePatch(Target[Key], Value)
> 
> What is meant by "the Key/Value pair" if there is more than one?
> Are all such pairs to be removed or mutated, or only one of them?

The horse's carcass is so decomposed that you can't even find what to kick anymore. RFC 7159 says "When the names within an object are not unique, the behavior of software that receives such an object is unpredictable." It would be actively harmful for draft-ietf-appsawg-json-merge-patch to say "we can make it predictable in our own unique fashion".

--Paul Hoffman

---

From: John Cowan <[email-masked]>
Date: Tue, 8 Jul 2014 15:06:36 -0400

-- 
John Cowan          http://www.ccil.org/~cowan        [email-masked]
What asininity could I have uttered that they applaud me thus?
        --Phocion, Greek orator

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 9 Jul 2014 19:57:05 +0200

> Are all such pairs to be removed or mutated, or only one of them?

It may have been intuitively obvious to the authors and reviewers, but may still be worthwhile mentioning in a sentence, that the merge-patch operation is defined at the level of the JSON data model.  Specifically, there is no expectation that merge-patch preserves representation level features such as white space, member ordering etc.

Grüße, Carsten

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 9 Jul 2014 17:59:25 -0700

> It may have been intuitively obvious to the authors and reviewers, but may still be worthwhile mentioning in a sentence, that the merge-patch operation is defined at the level of the JSON data mode…

Does the following language work for you?

The MergePatch operation is defined at the level of the JSON data model. Specifically, there is no expectation that the MergePatch operation will preserve representation-level features such as white space, member ordering, and so on. If an object in the target has more than one name/value pair with the same name, the result of the patch operation is unpredictable.

--Paul Hoffman

---

From: Larry Masinter <[email-masked]>
Date: Thu, 10 Jul 2014 15:06:06 +0000

> The MergePatch operation is defined at the level of the JSON data
> model.

This seems reasonable, but where do I find the "JSON data model"
described? I've looked in all of the JSON publications, RFCs, 
internet drafts, ECMA 262, 404.

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 10 Jul 2014 08:42:27 -0700

> internet drafts, ECMA 262, 404.

RFC 7159. Might you instead suggest better wording for what you think we should say about what the MergePatch operation works on?

--Paul Hoffman

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 10 Jul 2014 17:46:16 +0200

> internet drafts, ECMA 262, 404.

I agree with Paul here, this is described in RFC 7159 (introduction plus some details in sections 4 to 7), even if we were too pusillanimous to call it that way.

Grüße, Carsten

---

From: Larry Masinter <[email-masked]>
Date: Thu, 10 Jul 2014 17:47:39 +0000

> RFC 7159. Might you instead suggest better wording for what you think
> we should say about what the MergePatch operation works on?

Here's an attempt:
===
  The MergePatch operation is defined to operate at an object level,
not a textual level. There is no expectation that the MergePatch operation 
will preserve  textual representation-level features such as white space, 
member ordering, number precision beyond what is available in the
target's implementation, and so forth. 
 
In addition, even if the target implementation allows multiple name/value pairs
with the same name, the result of the patch operation on such
objects is not defined.
===

You could instead say that patch changes one of the values, all of
the values, or consolidates them, nailing it down in the spirit of
interoperability.

I also think it would be advisable to disallow duplicate names
in application/merge-patch+json, but that requiring the other
features of I-json is unnecessary.

Larry

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 10 Jul 2014 11:53:14 -0700

> with the same name, the result of the patch operation on such

The first sentence uses "object" incorrectly because JSON uses that term for something else. It could bee better worded as "The MergePatch operation is defined to operate at the level of data items, not at the level of data representation." 

> the values, or consolidates them, nailing it down in the spirit of

Nope, still not going there. The wording in RFC 7159 is still relevant here.

> features of I-json is unnecessary.

There is no need to re-argue what RFC 7159 says about this.

--Paul Hoffman

---

From: Larry Masinter <[email-masked]>
Date: Thu, 10 Jul 2014 20:40:40 +0000

> There is no need to re-argue what RFC 7159 says about this.

I don't want to re-argue the decision. I'm just wondering
"if i-json is useful, why isn't it useful for this?"

i-json is being proposed as an IETF RFC describing a particularly
interesting profile of JSON, giving it a special name, "I-JSON"
based on the claim that this profile is more interesting
than most other combinations of restrictions.

But here's an application (application/ merge-patch+json)
which -- as you point out -- doesn't mention I-JSON,
even though some of the constraints of "which instances
are meaningful to apply" would seem to be more easily
expressed as a well-known profile of JSON. Just not
I-JSON. The restriction on duplicate names is fine, but
there's no need to restrict numbers to IEEE precision
in the patch request.

Mergepatch is one data point, are there other JSON
application specs that COULD use i-json as a
normative reference?

If most cases of JSON application specifications that
need 'clean JSON input required for results to be
meaningful' profiles can't use I-JSON as a basis
for 'clean', it casts doubts as to defining I-JSON as
a category, rather than just a set of best practices.

Larry

---

From: "Joe Hildebrand (jhildebr)" <[email-masked]>
Date: Fri, 11 Jul 2014 05:41:18 +0000

>a category, rather than just a set of best practices.

+1

I'd support having merge/patch both be valid I-JSON as well as only
operating on valid I-JSON (which are two separate requirements).

I don't care if that means you can't patch crufty JSON.

-- 
Joe Hildebrand

---

From: "Martin J. Dürst" <[email-masked]>
Date: Fri, 11 Jul 2014 14:51:13 +0900

> The first sentence uses "object" incorrectly because JSON uses that term for something else. It could bee better worded as "The MergePatch operation is defined to operate at the level of data items…

Very much agreed about the "object" bit, but can we do
s/data representation/textual representation/,
please? "data items" and "data representation" sound too much like the 
same to me.

Regards,   Martin.

---

From: "Martin J. Dürst" <[email-masked]>
Date: Fri, 11 Jul 2014 14:51:20 +0900

> "if i-json is useful, why isn't it useful for this?"

Thinking about it, it looks to me as if i-json and merge-patch are 
orthogonal, in the following sense:

If the original document and the patch data are i-json, then the result 
of applying the patch is guaranteed to be i-json.

I haven't checked this fully, but it seems to be the case at least for 
the lack of duplicate keys, and for restricted value ranges.

If that's the case, then that would provide a data point that these two 
specs are well designed, just not in the way Larry was looking for.

Regards,   Martin.

> _______________________________________________
> json mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/json
>

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 11 Jul 2014 08:02:00 +0200

On 11 Jul 2014, at 07:51, Martin J. Dürst <[email-masked]> wrote:

> orthogonal

Good point.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 11 Jul 2014 08:10:27 +0200

> operating on valid I-JSON (which are two separate requirements).

I don’t see a gain from creating a normative dependency here.

Grüße, Carsten