Open APIs

 View Only
  • 1.  TMF622 Patch product order operation appears to be incompatible with the RFC defining JSON Merge Patch

    TM Forum Member
    Posted Nov 18, 2020 11:30
    TMF622 Release 19 States that support for json/merge (https://tools.ietf.org/html/rfc7386) is mandatory (called JSON Merge Patch in the RFC).

    See pp65 of the TMF 622 spec
    "This operation allows partial updates of a product order entity. Support of json/merge (https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is optional."

    I have read through RFC 7386 (and RFC 7396 which replaces it) and it states that patching an array results in the verbatim replacement of the existing array with the patch array. I.e. there is no matching and recursive merging of objects in the array. See RFC 7396 [Page 4].

    This means the example starting on TMF622 page 71 (Change value for billing account id) does not comply with the RFC. The example implies a patching behaviour where the OrderItems in the productOrderItem array are matched on id and then the JSON Merge algorithm applied to each one. But this is not the behaviour in the RFC, the RFC behaviour would be to replace the productOrderItem array in its' entirety with the array as it appears in the patch, without merging.

    Have I miss-understood? I know tools like the python jsonmerge can do this sort of thing, but that is not what the RFC describes.

    I can see various options:
    • The example in the spec should be changed to align with JSON Merge Patch RFC 7396 (which updates RFC 7386)
    • The spec should not reference the RFC but instead define its' own behaviour, some other RFC I have missed?
    • The TMF could suggest updates to RFC 7396

    In addition, RFC 5789 is not the spec for JSON Patch but the spec for HTTP Patch. I think the spec meant to reference RFC 6902 JavaScript Object Notation (JSON) Patch?

    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------


  • 2.  RE: TMF622 Patch product order operation appears to be incompatible with the RFC defining JSON Merge Patch

    TM Forum Member
    Posted Nov 19, 2020 01:25
    Hi Alasdair

    Thanks for calling this to our attention.
    It is possible that we have been a bit sloppy in some of our PATCH examples :( . I have raised an issue for this particular user guide, but it is possible that PATCH examples in other guides may also be at fault.
    Additionally you are of course correct, we should have referenced 6902, JSON Patch. This part of the user guide is generated by tooling, so affects all the user guides. I have raised an issue to correct the common text that is used in this generation to refer to the correct RFC numbers.
    Apologies.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------



  • 3.  RE: TMF622 Patch product order operation appears to be incompatible with the RFC defining JSON Merge Patch

    TM Forum Member
    Posted Nov 19, 2020 06:44
    Jonathon,

    Thanks for the clarification.

    What is the thinking behind the use of RFC 7386 and RFC 6902? I see the former is mandatory and the latter is optional.
    Is this simply the case of mandatory common features and optional extra features or is 7386 the strategic direction and 6902 is there for historical reasons/deprecated?

    I ask as 6902 lets you do more "surgical" updates than 7386 and might have value to offer to our customers, but not if it's in the spec just as a backwards-compatibility offering that will be removed at some point.

    Alasdair


    ------------------------------
    Alasdair MacLeod
    BT Group plc
    ------------------------------



  • 4.  RE: TMF622 Patch product order operation appears to be incompatible with the RFC defining JSON Merge Patch

    TM Forum Member
    Posted Nov 19, 2020 09:23
    Before my time, I'm afraid, could be that 6902 was not well-known when the API effort started.
    I completely agree with you that 6902 is more valuable, since it is inherently "unreliable" to rely on merge. But of course it is more difficult to implement by an API provider.
    Thanks again for surfacing this issue.

    ------------------------------
    Jonathan Goldberg
    Amdocs Management Limited
    Any opinions and statements made by me on this forum are purely personal, and do not necessarily reflect the position of the TM Forum or my employer.
    ------------------------------