[PATCH v2 18/18] spdx-common: Clarify documentation and make SPDX_LICENSES extensible

Stefano Tondo
2026-02-21T05:10:43Z

This commit improves the SPDX variable documentation and enhances
SPDX_LICENSES to support layer-based license extensions.

1. SPDX_NAMESPACE_PREFIX documentation clarification:
- Clarify that this should be organization-specific
- Explain the default is for compatibility only
- Provide example of production override
- Make it consistent with SPDX_UUID_NAMESPACE guidance

2. SPDX_LICENSES documentation enhancement:
- Clarify when this variable needs to be set
- Document the new list behavior
- Provide example usage with += operator

3. SPDX_LICENSES implementation as extensible list:
- Change from single file to space-separated list of files
- Support layer-based license extensions without file copying
- Later files override earlier ones for duplicate license IDs
- Backward compatible (single file path still works)
- Add error handling for missing/invalid files

This enhancement allows layers to add custom licenses without
maintaining a copy of the base spdx-licenses.json file:

SPDX_LICENSES += "${LAYERDIR}/files/custom-licenses.json"

This is particularly useful for organizations with proprietary or
custom licenses that need to be tracked in SBOMs.

Signed-off-by: Stefano Tondo <stefano.tondo.ext@siemens.com>
---
meta/classes/spdx-common.bbclass | 13 +++++++++----
meta/lib/oe/spdx_common.py | 31 +++++++++++++++++++++++++++----
2 files changed, 36 insertions(+), 8 deletions(-)

diff --git a/meta/classes/spdx-common.bbclass b/meta/classes/spdx-common.bbclass
index 3d13650962..a6872fb55b 100644
--- a/meta/classes/spdx-common.bbclass
+++ b/meta/classes/spdx-common.bbclass
@@ -42,7 +42,10 @@ SPDX_UUID_NAMESPACE[doc] = "The namespace used for generating UUIDs in SPDX \

SPDX_NAMESPACE_PREFIX ??= "http://spdx.org/spdxdocs"
SPDX_NAMESPACE_PREFIX[doc] = "The URI prefix used for SPDX document namespaces. \
- Combined with other identifiers to create unique document URIs."
+ This should be a domain name or URI prefix unique to your organization to ensure \
+ globally unique document URIs. The default 'http://spdx.org/spdxdocs' is provided \
+ for compatibility but should be overridden in production environments (e.g., \
+ 'https://sbom.example.com')."

SPDX_PRETTY ??= "0"
SPDX_PRETTY[doc] = "If set to '1', generate human-readable formatted JSON output \
@@ -50,9 +53,11 @@ SPDX_PRETTY[doc] = "If set to '1', generate human-readable formatted JSON output
Pretty formatting makes files larger but easier to read."

SPDX_LICENSES ??= "${COREBASE}/meta/files/spdx-licenses.json"
-SPDX_LICENSES[doc] = "Path to the JSON file containing SPDX license identifier \
- mappings. This file maps common license names to official SPDX license \
- identifiers."
+SPDX_LICENSES[doc] = "Space-separated list of JSON files containing SPDX license \
+ identifier mappings. Files are processed in order, with later entries overriding \
+ earlier ones. This allows layers to extend the base license set without copying \
+ the entire file. Set this variable in your layer when using licenses not known \
+ to oe-core (e.g., 'SPDX_LICENSES += \"${LAYERDIR}/files/custom-licenses.json\"')."

SPDX_CUSTOM_ANNOTATION_VARS ??= ""
SPDX_CUSTOM_ANNOTATION_VARS[doc] = "Space-separated list of variable names whose \
diff --git a/meta/lib/oe/spdx_common.py b/meta/lib/oe/spdx_common.py
index 72c24180d5..8a6cf70fc1 100644
--- a/meta/lib/oe/spdx_common.py
+++ b/meta/lib/oe/spdx_common.py
@@ -42,10 +42,33 @@ def is_work_shared_spdx(d):

def load_spdx_license_data(d):
- with open(d.getVar("SPDX_LICENSES"), "r") as f:
- data = json.load(f)
- # Transform the license array to a dictionary
- data["licenses"] = {l["licenseId"]: l for l in data["licenses"]}
+ """
+ Load SPDX license data from one or more JSON files.
+ SPDX_LICENSES can be a space-separated list of files.
+ Later files override earlier ones for duplicate license IDs.
+ """
+ license_files = d.getVar("SPDX_LICENSES").split()
+
+ # Initialize with empty structure
+ data = {"licenses": {}}
+
+ # Load and merge each file
+ for license_file in license_files:
+ try:
+ with open(license_file, "r") as f:
+ file_data = json.load(f)
+ # Transform the license array to a dictionary and merge
+ if "licenses" in file_data:
+ for lic in file_data["licenses"]:
+ data["licenses"][lic["licenseId"]] = lic
+ # Copy over other top-level keys from the last file
+ for key in file_data:
+ if key != "licenses":
+ data[key] = file_data[key]
+ except FileNotFoundError:
+ bb.warn(f"SPDX license file not found: {license_file}")
+ except json.JSONDecodeError as e:
+ bb.warn(f"Invalid JSON in SPDX license file {license_file}: {e}")

return data

--
2.53.0