Introduction

The VSCode DeltaJSON Extension provides a DiffReport view in Visual Studio Code for diff files created by the specialist JSON comparison tool DeltaJSON.

DeltaJSON is both a REST service and an online web application. Changes marked up in DeltaJSON files (with special JSON properties) from JSON merge and compare operations may be reviewed and resolved from the DiffReport view - shown in the right-hand editor in the screenshot below:

DeltaJSON Format Detail

The JSON files generated by DeltaXML's DeltaJSON web app or REST API contain extra 'meta' JSON objects that describe differences or conflicts within the JSON file. This extension generates a virtual document that is styled in a similar way to Visual Studio Code's built-in diff-viewer.

Opening a DiffReport

This extension has an Auto-DiffReport setting which is 'On' by default. So, each time you open a DeltaJSON file in Visual Studio Code, the corresponding diff-view will be shown in an editor tab alongside the 'raw' DeltaJSON file. This setting can be toggled by clicking on 'Auto DiffReport' in the status bar. With Auto-DiffReport set to 'Off', you can choose to view the diff-view by clicking on the 𝚫 button.

Navigating a DiffReport

You can use the alt-up/alt-down shortcut-keys to navigate to the previous/next change in a DiffReport. There are also previous/next buttons alongside the editor tab. The number of changes and the currently selected item number are shown in the status bar at the bottom of the active DiffReport.

Accepting / Rejecting Changes

To accept or reject each change highlighted in the DiffReport view, the DeltaJSON 'CodeLens' feature should be enabled (Command DeltaJSON: Toggle codelens). A CodeLens inline with each change describes the change and provides the buttons: Accept Changes and Regject Changes.

Once the Accept Changes or Regject Changes is pressed, the DeltaJSON file will be updated to reflect the chosen 'resolve' action, the DiffReport view will update automatically.

The Resolved JSON

When the last change in the DeltaJSON file is resolved, the DiffReport view will close and a message will popup to confirm the DeltaJSON file has been converted back to the original JSON with all marked changes now resolved (all DeltaJSON properties are removed).

Undoing Accepted / Rejected Changes

If you change your mind about previsouly accepted or rejected changes and want to revert them, simply invoke the standard VS Code Undo command in the editor of the original DeltaJSON file.

The DiffReport view will update to reflect the Undo once you save the DeltaJSON file.

Feature Summary

• Shows a DiffReport coloured/formatted in a similar way to VSCode’s Diff Editor
• Produce a resolved JSON file by accepting or rejecting the highlighted changes
• The DiffReport is a Virtual Document - shown in the VSCode editor
• The DiffReport view is synchronised with the raw DeltaJSON file
• Buttons:
  • Accept Changes - Accept changes from the modified document version
  • Reject Changes - Reject changes and preserve data from the original document
• Status bar:
  • Currently selected change - click to set new change number
  • Shows total number of changes (click to show DiffReport metadata)
  • Auto DiffReport: On/Off (click to toggle setting)
• Commands:
  • Toggle Auto-open DiffReport
  • Toggle Codelens (annotations on changes)
  • Goto change number
  • Show DiffReport
  • Next Change
  • Previous Change

Sample DeltaJSON

After installing the extension into VS Code, copy and paste the sample DeltaJSON content below into a new file with a .json extension. Then open the file in VS Code.

{
  "dx_deltaJSON": {
    "dx_data_sets": "A!=B",
    "dx_deltaJSON_type": "diff",
    "dx_deltaJSON_metadata": {
      "operation": {
        "type": "compare",
        "input-format": "multi_part",
        "output-format": "JSON"
      },
      "parameters": {
        "dxConfig": [],
        "arrayAlignment": "orderless",
        "wordByWord": true
      }
    },
    "dx_deltaJSON_delta": {
      "parameters": {
        "dxConfig": {
          "dx_delta": {
            "A": []
          }
        },
        "arrayAlignment": {
          "dx_delta_string": [
            "orderless",
            {
              "dx_delta": {
                "B": " new"
              }
            }
          ]
        },
        "wordByWord": true,
        "new": {
          "dx_delta": {
            "B": 25
          }
        }
      }
    }
  }
}