DeltaCode Output: Format, Fields and Structure

Output Formats

DeltaCode provides two output formats for the results of running a DeltaCode codebase comparison: JSON and CSV.

The default output format is JSON. If the user does not include an output flag (-j or --json-file) followed by the path to the output file in the command-line input, the results of the DeltaCode comparison are displayed in the console. The results are saved in a .json file if the user includes the -j or --json-file flag and the output file's path, e.g.

deltacode -n [path to the 'new' codebase] -o [path to the 'old' codebase] -j [path to the JSON output file]

Once a user has generated a JSON output file with DeltaCode, he or she can also convert that JSON output to CSV format by running a command with this structure:

 python etc/scripts/json2csv.py [path to the JSON input file] [path to the CSV output file]

See also JSON to CSV Conversion.

Overall Structure

JSON

Top-Level JSON

At the top level, DeltaCode's JSON output comprises the following fields/keys:

• deltacode_notice -- A string of the terms under which the DeltaCode output is provided.

• deltacode_options -- This field consists of a JSON object containing three key/value pairs:

  • new_scan_path -- A string identifying the path to the JSON file containing the ScanCode output of the codebase the user wants DeltaCode to treat as the 'new' codebase.
  • old_scan_path -- A string identifying the path to the JSON file containing the ScanCode output of the codebase the user wants DeltaCode to treat as the 'old' codebase.
  • --all-delta-types -- A true or false value. A true value indicates that the user's command-line input has included the -a or --all-delta-types flag, in which case the DeltaCode output -- in the deltas field described below -- will include details for unmodified files as well as all changed files. If the user does not include the -a or --all-delta-types flag, the value will be false and unmodified files will be omitted from the DeltaCode output.

• deltacode_version -- A string representing the version of DeltaCode on which the codebase comparison was run.

• deltacode_errors -- A list of one or more strings identifying errors that occurred during the codebase-comparison process. (This list will usually be empty.)

• deltas_count -- An integer representing the number of Delta objects -- the file-level comparisons of the two codebases -- contained in the DeltaCode output. If the user's command-line input does not include the -a or --all-delta-types flag (see the discussion above of the --all-delta-types field/key), the DeltaCode output will omit details for unmodified files and consequently the deltas_count field will not include unmodified files.

• deltas -- [coming next]

Example of Detailed JSON output

Last but not least, here's an abbreviated example of the detailed DeltaCode output in JSON format -- in this case, the JSON output of a DeltaCode comparison of zlib-1.2.11 and zlib-1.2.9:

{
  "deltacode_notice": "Generated with DeltaCode and provided on an \"AS IS\" BASIS, WITHOUT WARRANTIES\nOR CONDITIONS OF ANY KIND, either express or implied. No content created from\nDeltaCode should be considered or used as legal advice. Consult an Attorney\nfor any legal advice.\nDeltaCode is a free software codebase-comparison tool from nexB Inc. and others.\nVisit https://github.com/nexB/deltacode/ for support and download.",
  "deltacode_options": {
    "new_scan_path": "C:/scans/zlib-1.2.11.json",
    "old_scan_path": "C:/scans/zlib-1.2.9.json",
    "--all-delta-types": false
  },
  "deltacode_version": "1.0.0.post49.e3ff7be",
  "deltacode_errors": [],
  "deltas_count": 40,
  "deltas": [
    {
      "factors": [
        "modified"
      ],
      "score": 20,
      "new": {
        "path": "trees.c",
        "type": "file",
        "name": "trees.c",
        "size": 43761,
        "sha1": "ab030a33e399e7284b9ddf9bba64d0dd2730b417",
        "original_path": "zlib-1.2.11/trees.c",
        "licenses": [
          {
            "key": "zlib",
            "score": 60.0,
            "short_name": "ZLIB License",
            "category": "Permissive",
            "owner": "zlib"
          }
        ],
        "copyrights": [
          {
            "statements": [
              "Copyright (c) 1995-2017 Jean-loup Gailly"
            ],
            "holders": [
              "Jean-loup Gailly"
            ]
          }
        ]
      },
      "old": {
        "path": "trees.c",
        "type": "file",
        "name": "trees.c",
        "size": 43774,
        "sha1": "1a554d4edfaecfd377c71b345adb647d15ff7221",
        "original_path": "zlib-1.2.9/trees.c",
        "licenses": [
          {
            "key": "zlib",
            "score": 60.0,
            "short_name": "ZLIB License",
            "category": "Permissive",
            "owner": "zlib"
          }
        ],
        "copyrights": [
          {
            "statements": [
              "Copyright (c) 1995-2016 Jean-loup Gailly"
            ],
            "holders": [
              "Jean-loup Gailly"
            ]
          }
        ]
      }
    },
    [additional Delta objects if any]
  ]
}

[to come]

CSV

[to come]