Clarify how PatchBuilder replaceInsert is supposed to work

[nikos]

As an ML8 application developer I would like to patch an JSON document no matter if a node does exist or not. Therefore I tried to use the PatchBuilder#replaceInsertFragment functionality, unfortunately I was not able to get it to work in a manner which works wether a node does exist or not yet. Please see my Pull Request #280 for a code sample.

[sammefford]

For others who find this issue, here is a summary of the issue (using REST API not Java):
original document:

{
    "stringKey": "string value",
    "numberKey": 7
}

PATCH:

{
    "pathlang": "xpath",
    "patch": [
        {
            "replace-insert": {
                "select": "/foo",
                "context": "/numberKey",
                "position": "after",
                "content": {
                    "somethingNew": "the bar for the foo"
                }
            }
        },
        {
            "replace-insert": {
                "select": "/stringKey",
                "context": "/numberKey",
                "position": "after",
                "content": {
                    "somethingReplaced": "please make me not nested"
                }
            }
        }
    ]
}

AFTER:

{
    "stringKey": {
        "somethingReplaced": "please make me not nested"
    },
    "numberKey": 7,
    "somethingNew": "the bar for the foo"
}

And the explanation:
You've run into a known problem with replace-insert when patching JSON documents.

Background: document patch is built on the xdmp.node_() / xdmp:node_() functions. Those functions operate on nodes. In JSON, a node is a value, not a key -- the key is a name associated with values and not a node in its own right. The replace operation operates on the value, using the existing key name for the new value.

Thus, at the xdmp.node*() level, the best way to replace a value if it exists or insert the key and value if it doesn't is with two separate operations where the value for the replace operation doesn't have a key name and the value for the insert operation does.

Currently, however, the REST API can't support those two operations in a single document patch because the predicates necessary to apply only one operation are rejected.

Per the following RFE, the REST API needs to relax XPath validation: https://rfetrack.marklogic.com/detail/3268

Until that RFE is approved and implemented, the workaround for replace-insert in the REST API is to read the document, modify it on the client, and write the document.

If there are patch use cases you need that are currently not supported, you might want to add them to this RFE: https://rfetrack.marklogic.com/detail/3124

[sammefford]

Niko, based on the discussion thread I just shared, it sounds like you were able to get an answer on why the behavior is that way, and a viable workaround. Do you agree we should close this issue?