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

[Stefano Tondo <stondo@gmail.com>]

From: Stefano Tondo <stefano.tondo.ext@siemens.com>

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