SPDX3 Diff Tool

Overview

This tool compares two SPDX3 JSON documents and reports differences in:

• Software packages (name + version)
• Kernel configuration parameters (CONFIG_*)
• PACKAGECONFIG entries per package

The application separates human-readable and machine-readable outputs to improve automation and pipeline integration.

• By default, the tool emits structured JSON output, making it suitable for consumption by scripts and CI/CD pipelines.
• The default output format can be changed into a human-readable (text) using --human-readable optional argument.
• When a JSON filename parameter is provided, the JSON result is also written to the specified file.

Usage

./spdx-diff reference.json new.json [OPTIONS]

Required arguments:

• reference: Path to the baseline SPDX3 JSON file.
• new: Path to the newer SPDX3 JSON file.

Optional arguments:

• --json-output <file>: Save diff results to the given JSON file.
• --human-readable: Output results in a human-readable text format.

Text output filtering - category :

• --[no-]packages: show|hide package differences.
• --[no-]kernel-config: show|hide kernel config differences.
• --[no-]packageconfig: show|hide PACKAGECONFIG differences.
• --[no-]packages-proprietary: show|hide packages with LicenseRef-Proprietary.

Output

The script prints differences grouped into three sections:

1. Packages

   • Added packages
   • Removed packages
   • Changed versions

2. Kernel Config (CONFIG_*)

   • Added options
   • Removed options
   • Modified options

3. PACKAGECONFIG (per package)

   • Packages with added PACKAGECONFIG entries
   • Packages with removed PACKAGECONFIG entries
   • Packages with changed feature configurations
   • Shows package name and associated features

Symbols:

• added

• removed ~ changed

JSON Diff File
--------------
The output file (default: spdx_diff_<timestamp>.json) contains a structured diff:
```json
{
"package_diff": {
"added": { "pkgA": "1.2.3" },
"removed": { "pkgB": "4.5.6" },
"changed": { "pkgC": { "from": "1.0", "to": "2.0" } }
},
"kernel_config_diff": {
"added": { "CONFIG_XYZ": "y" },
"removed": { "CONFIG_ABC": "n" },
"changed": { "CONFIG_DEF": { "from": "m", "to": "y" } }
},
"packageconfig_diff": {
"added": {
"xz": { "doc": "enabled" }
},
"removed": {
"old-package": { "feature1": "disabled" }
},
"changed": {
"zstd-native": {
"added": { "zlib": "enabled" },
"removed": { "lz4": "disabled" },
"changed": {
"doc": { "from": "disabled", "to": "enabled" }
}
}
}
}
}

PACKAGECONFIG Structure

PACKAGECONFIG entries are tracked per package, showing which features are enabled/disabled for each specific package:

Console output example:

PACKAGECONFIG - Changed Packages:
~ xz:
+ doc: enabled
~ zstd-native:
~ lz4: disabled -> enabled
- lzma: disabled

This shows:

• xz package: doc feature was added and enabled
• zstd-native package: lz4 changed from disabled to enabled, lzma was removed

Logging

The script uses Python's logging module:

 INFO Normal operations (file opened, counts, etc.)
WARNING Missing sections (no build_Build objects found)
ERROR Invalid input or format issues

Examples

Basic comparison with default JSON output on stdout:

./spdx-diff reference.json new.json

Full details with proprietary packages excluded:

./spdx-diff reference.json new.json --no-packages-proprietary

Console output for CI/CD:

./spdx-diff reference.json new.json

Console output human-readable:

./spdx-diff reference.json new.json --human-readable

Console and JSON output with JSON file generated:

./spdx-diff reference.json new.json --json-output result.json

Exclude on console PACKAGECONFIG differences:

./spdx-diff reference.json new.json --no-packageconfig

Human readable console output example:

Packages - Added:
+ libfoo: 2.0
Packages - Changed:
~ zlib: 1.2.11 -> 1.2.13
Kernel Config - Removed:
- CONFIG_OLD_FEATURE
PACKAGECONFIG - Added Packages:
+ newpkg:
gtk: enabled
doc: disabled
PACKAGECONFIG - Changed Packages:
~ xz:
+ lzma: enabled