Yocto SPDX Output: Diagnose Missing Documents and Source Archives

A consumer can parse a Yocto SPDX JSON file successfully and still fail to resolve the components it references. Another consumer may expect source archives that were never requested. These are different failures: one concerns a document bundle's internal links; the other concerns which additional deliverables the build generated.

For Yocto Project 5.0.12, start by identifying the output family before changing a validator or enabling every SPDX option. The following checks are proposed inspections, not results from an executed build.

Know which files belong to the output family

The create-spdx class reference documents global enablement with INHERIT += "create-spdx". Its top-level JSON is named IMAGE-MACHINE.spdx.json under tmp/deploy/images/MACHINE/. Related files also exist under tmp/deploy/spdx.

The SBOM generation guide separately identifies IMAGE-MACHINE.spdx.tar.zst, an archive containing the index and individual recipe documents. These names describe the documented output pattern; substitute the actual image and machine, then inspect the generated directory rather than assuming a literal filename.

List the archive before extracting it into an empty inspection directory. Compare its members with the index and the top-level document's references. If a handoff contains only one JSON file, first establish whether its referenced documents were omitted during collection. Rebuilding every recipe will not repair a packaging step that copies an incomplete file set.

Source descriptions and source bytes are separate choices

Three settings answer different requests:

• SPDX_INCLUDE_SOURCES adds descriptions of source files used for host tools and target packages.
• SPDX_ARCHIVE_SOURCES adds archives containing source files themselves and requires SPDX_INCLUDE_SOURCES = "1".
• SPDX_ARCHIVE_PACKAGED adds archives of generated target-package contents.

SPDX_PRETTY changes JSON readability. It does not add missing source payloads. The documented ancillary locations include recipes/recipe-packagename.tar.zst for source archives and packages/packagename.tar.zst for package-content archives under the SPDX deployment area.

When a consumer reports “sources missing,” ask whether it expects file-level metadata or downloadable file contents. Check the effective settings and the corresponding output type. A package archive is also not a whole-disk image: partition tables, free space, and other image assembly details are outside that archive's stated purpose.

Resolve references by identity, not a guessed URL

Read the generated document's declared SPDX version before selecting validation tooling. The SPDX 2.3 document-creation specification defines an external document reference using an identifier, the referenced document's namespace, and a checksum. Its namespace is an identity and is not required to be a retrievable web address.

Consequently, an HTTP failure when opening a namespace does not alone prove that an SPDX bundle is broken. Locate the referenced document in the delivered collection, compare its namespace, and verify the declared checksum using the recorded algorithm. Report these separately: missing document, wrong namespace, and checksum mismatch require different repairs.

Avoid reformatting individual JSON documents during collection. Even a whitespace-only rewrite changes document bytes and can invalidate a reference checksum. If a downstream transformation is necessary, use tooling that maintains the cross-document relationships and verify the transformed collection again.

Preserve relationship meaning during import

The SPDX relationship definitions distinguish containment, build dependencies, runtime dependencies, and generation relationships. Follow the types actually emitted by the build; do not assume every supported type will appear.

For a representative package, resolve both endpoints of each inspected relationship. Check that an importer retains the relationship direction and external-document qualification. Two local identifiers that look alike in different documents are not automatically the same element.

A flattened package-name spreadsheet can hide these distinctions. If the consumer needs a runtime inventory, define which relationships it follows rather than treating every recipe document in the archive as installed software. Missing relationships also do not automatically assert that no such dependencies exist.

The practical handoff test is specific: the intended document set opens, references resolve to matching documents, optional archives satisfy the stated request, and the importer preserves the relationships it uses. Bind that verified set to the release through the existing artifact manifest; there is no need to reinvent the release-hashing process inside the SBOM parser.