Page Comparison

Issues & Decisions

CPS Delta feature Exceptions

Where ever possible the Delta Feature will throw the same exceptions as defined in CPS core. If any new exception for the delta feature are required the following will be updated here.

HTTP response codes for Delta between 2 Anchors API

The proposed API will be part of the CPS Data Interface. The following response codes will be returned by the API:

CPS Delta feature Exceptions

Wherever possible the Delta Feature will throw the same exceptions as defined in CPS core. If any new exception for the delta feature is required, the following will be updated here.

HTTP response codes for Delta between 2 Anchors API

The proposed API will be part of the CPS Data Interface. The following response codes will be returned by the API:

...

[
  {
    "action": "ADD",
    "xpath": "/bookstore/categories/[@code=3]",
    "target-data": {
      "code": 3,
      "name": "kidz"
    }
  },
  {
    "action": "DELETEREMOVE",
    "xpath": "/bookstore/categories/[@code=1]",
    "source-data": {
      "code": 1,
      "name": "Fiction"
    }
  },
  {
    "action": "UPDATE",
    "xpath": "/bookstore/categories/[@code=2]",
    "source-data": {
      "name": "Funny"
    },
    "target-data": {
      "name": "Comic"
    }
  }
]

...

Gliffy
size 600 displayName CPS Delta Flowchart name CPS Delta Flowchart pagePin 2

...

Additional Details

Format/Conventions to be used for Delta Report

There are several ways of representing the differences between JSON but here we discuss the JSON Patch format of representing these differences because the proposed Delta report closely represents JSON patch with a few differences. This approach focuses in producing another JSON document that represents the differences between the two JSON's that have been compared.The delta report format is based on two RFCs namely RFC 6902 and RFC 9144 . A detailed comparison of the RFCs can be found here.

RFC 6902 JSON Patch

JSON Patch defines a JSON document structure for expressing a sequence a sequence of operations to apply to a JavaScript Object Notation(JSON) document; it is suitable for use with the HTTP PATCH method. The "application/json-patch+json" media type is used to identify such patch documents.

But in it can also be used to get the differences between two JSON as the JSON patch document represents an array of objects. where each object represents a single operation(op), path and value.

Here the The notation of "operation" is used as because the same JSON Patch document can be used to perform HTTP Patch operations. But The the operations field can be used as a reference to decide how the "action" field should function in the implementation of Delta report.

...

...

RFC 9144 YANG data model that defines RPCs intended to be used in conjunction with NETCONF [RFC6241] or RESTCONF [RFC8040]. These RPCs RFCs allow a client to request a server to compare two NMDA datastores and report any differences.

...

• The core of the RFC 9144 solution is a new management operator, <compare>, that compares the data tree contents of two datastores. The operation checks whether there are any differences in values or in data nodes that are contained in either datastore and then returns any differences as output. The output is returned in the format specified below.
• The RFC6902 approach to Delta report generation follows the JSON patch format. A JSON Patch document represents an array of objects, where each object contains exactly one operation, path and associated values. The operation can have following values: add, remove, replace, move, copy and test. The path represents the JSON patch format and the values contain the difference in source and target values.

...

CPS Delta Report Format

Based on the RFC documentations mentioned above, CPS Delta Report is designed in the format specified in the following code block. This Delta Report takes the features from both RFCs that are best suited for CPS and fulfill it's requirementson the RFC documentations mentioned above, CPS Delta Report is designed in the format specified in the following code block. This Delta Report takes the features from both RFCs that are best suited for CPS and fulfill its requirements.

The format of Delta report has following key take aways from the above mentioned RFCs:

• The "op" field from RFC 6902 is replaced with "action" field becaus in CPS we want to report the action that was performed on the data. And this field can have 3 predefined values: ADD, REMOVE and UPDATE.
• The xpath is used in CPS to uniquely identify individual data nodes and is used in place of JSON path as defined in the two RFCs
• The source-data and target-data fields are used from RFC9144 to report the data that has been added, removed or updated. This approach properly categorizes the data instead of grouping it under the one "value" field as in RFC6902.

[
  {
    "action": "ADD",
    "xpath": "/bookstore/categories/[@code=3]",
    "target-data": {
      "code": "3,",
      "name": "kidz"
    }
  },
  {
    "action": "REMOVE",
    "xpath": "/bookstore/categories/[@code=1]",
    "source-data": {
      "code": "1,",
      "name": "Fiction"
    }
  },
  {
    "action": "UPDATE",
    "xpath": "/bookstore/categories/[@code=2]",
    "source-data": {
      "name": "Funny"
    },
    "target-data": {
      "name": "Comic"
    }
  }
]

...