A Practical Guide to SPDX

History of SPDX

In February 2010, a Linux Foundation working group (FOSSBazaar) began working on the first version of SPDX, though, at the time, the project was titled “Package Facts.” A few months later, in August 2010, the Linux Foundation announced that SPDX would be one of the pillars of its Open Compliance Program.

The first version of the SPDX specification (SPDX 1.0) was released in August 2011. The subsequent SPDX 1.1 (August 2012) and SPDX 1.2 (October 2013) addressed an issue with the specification’s verification algorithm and added support for additional data fields (such as author credits and project homepage).

Next came SPDX 2.0, which was released in May 2015. This was a significant update to the specification and included support for annotations, package-file relationships, and the ability to handle multiple packages. 

SPDX added significant security utility in 2016 with the release of SPDX 2.1 and support for external references, such as to security advisories and vulnerability feeds. SPDX 2.2 (published in 2020) introduced SPDX Lite (a subset of the specification with mandatory document creation and package information as well as certain other licensing data fields) and added several new supported file formats. The current 2.3 (published in August 2022) added more external reference types (to strengthen the security use case) and improved ease of use by making certain previously mandatory licensing properties optional, among other changes. 

The next version of SPDX will be 3.0. The publication date is still to be determined, but, in May 2023, SPDX announced the Release Candidate for the model. The most impactful innovation in SPDX 3.0 is that it will expand on the concept of “Profiles,” which are, essentially, condensed versions of the format intended for specific use cases. SPDX Lite is an example of an existing profile; SPDX 3.0 will separate licensing and security into separate profiles and introduce additional profiles for AI, data, and software build information.

‍

SPDX Document Structure

SPDX can be used to describe several types of software components: packages, files, and code snippets. The specification includes a wide variety of data fields for each type of component, including name, copyright information, licensing information, and many others. SPDX documents can also be created in a broad range of file formats: .xlsx spreadsheets, YAML, JSON, RDF, XML, and tag:value. (SPDX describes tag:value as a “flat text file,” and it’s a registered MIME type.)

The precise structure of an SPDX document can vary widely depending on the composition of  the software product, the way the SBOM is generated, and which data fields the document creator decides to include. For context, there are 27 data fields that can be used to describe packages, 16 for files (though several have deprecated), and 11 for snippets.

However, while most SPDX data fields are optional, several are mandatory and must be included in an SPDX SBOM for the document to be valid. 

It’s important to note that SPDX’s mandatory data fields differ from the U.S. federal government NTIA’s SBOM minimum required elements. (Though the NTIA’s minimum elements apply only to organizations selling into the U.S. federal government.) 

In other words, it’s possible to have a valid SPDX SBOM that doesn’t meet the NTIA requirements. And, it’s possible to have an SBOM that does meet the NTIA requirements but doesn’t pass SPDX validation. There is, however, a large overlap of the required fields.

Below, we’ll briefly discuss required data fields in a valid SPDX SBOM. Then, we’ll cover the NTIA minimum required data fields — and which SPDX data field maps to which NTIA requirement.  

(Note that the mandatory data fields discussed below are for software packages, except for Document Creation Information. There are other mandatory fields for SPDX SBOMs that describe software files or code snippets.)

‍

SPDX Mandatory Data Fields: Software Packages

Document Creation Information: This includes a data field for SBOM creator (which person, organization, or software tools created the SBOM). It also includes when the SBOM was created (date and time in UTC format), which version of SPDX the SBOM uses, document name, and more.  

Package Name

Package SPDX Identifier: This data field is used to enable references (from within the SPDX document, such as the “relationships” element, or from a different document) to the package being analyzed.  

Package Download Location: This communicates the URL (or specific location within a VCS like GitHub) where the package was downloaded at the time of SBOM creation.

Package Verification Code: This field is intended to help the SBOM consumer see whether files in the original package have been changed

NTIA Minimum Required Data Fields and SPDX Mapping

Author of SBOM Data: This maps to SPDX’s “Creator” data field (under “Document Creation Information”)

Timestamp: This maps to SPDX’s “Created” data field (under “Document Creation Information”)

Supplier Name: Which person or organization supplied the package to the producer. This should be an individual or entity rather than a host website. “Supplier Name” maps to SPDX’s “Package Supplier” data field.

Component Name: This maps to SPDX’s “Package Name” data field.

Version of the Component: This maps to SPDX’s “Package Version” data field.

Other Unique Identifiers: This maps to Package SPDX Identifier/SPDX Document Namespace and the External Reference field for Packages.

Dependency Relationship: This is used to describe the relationship between different elements, such as one being a dependency of another (or one containing another). This maps to SPDX’s “Relationship” data field.

‍

SPDX Use Cases

Today, SPDX has multiple important use cases, including security, open source license compliance, software transparency and maintainability, and regulatory compliance. As mentioned, when selling into the federal government, software suppliers are required to produce an SBOM in a human- and machine-readable format (like SPDX) to accompany each product. 

Here, we’ll briefly explore two of the most popular SPDX use cases: security and open source license compliance.

Security

SPDX began directly supporting the security use case in 2016 with the release of v2.1. This version of the spec added “External References,” which offer the ability to link to external security information. Today, SPDX supports references to:

• Security (such as a CVE)
• Package-Manager (such as npm or nuget)
• Persistent-id (such as SoftWare Heritage persistent Identifiers, SWHID)
• Other

You can use these external references to link to a CVE advisory, Common Security Advisory Framework (CSAF)-formatted security information, CycloneDX-formatted security information, Open Source Vulnerability (OSV)-formatted security information, a vulnerability disclosure document or feed, and more. (We recommend referencing Annex K of SPDX 2.3 for a full list and additional context, including which specific external reference to use for which reference type.) 

You can also link to a specific code fix that addresses a certain security issue. 

Open Source License Compliance

License compliance has been an SPDX use case since the standard was created over a decade ago, and it remains the case today. The specification has several data fields that can be used to communicate licensing information. This includes “copyright text” (to identify the component’s copyright holder and any applicable dates) and “package attribution text” to provide other required acknowledgements. 

There are also “concluded” and “declared” license fields, which differ in the following ways:

Declared license: The license(s) stated by the component author (i.e. file author or package author)

Concluded license: The license as determined by the SPDX document creator (or, in many cases, a scanning tool that document creator uses). The concluded license can differ from the declared license for any number of reasons, including the possibility that the component author mistakenly assigned a permissive license when they should have assigned a copyleft license. If the concluded and declared licenses don’t match, there’s another field (“Comments on license”) where the SBOM creator can add context or an explanation.

‍

Generating SPDX SBOMs

There are multiple ways to generate an SPDX SBOM, but we recommend organizations do so during the build process. Creating your SBOM during the build will generally result in a more accurate component inventory. 

With FOSSA, you can easily generate an SPDX SBOM in the JSON or tag:value file formats. Here’s how:

New FOSSA users

Step 1: Get started by creating a free FOSSA account.

Step 2: Import your project(s) by integrating with a VCS like GitHub or using our CLI 

Generating SPDX SBOMs from the FOSSA App

Step 1: Click on “Projects” in the header menu

Step 2: Select the Project for your SBOM

Step 3: Click on the “Generate a Compliance Report” button in the “Actions” menu 

Step 4: Check the box for your preferred SPDX export format 

Step 5: Decide which elements to include in your report — you can do this by checking (or unchecking) boxes in the “Customize Report Information” and “Edit Dependency Info” menus.

Step 6: Generate your report — either download a copy to distribute yourself, or create a public link for your file

Generating SPDX SBOMs from the FOSSA CLI

To generate an SPDX SBOM from the FOSSA CLI, you’ll need to run an additional report command after analyzing your project. For example:

export FOSSA_API_KEY=XXXXXXXX (needs to be a full API key)

fossa analyze && fossa report attribution --format spdx > file.json

In addition to SPDX, FOSSA supports CycloneDX and several other SBOM formats. For information (or to access our full suite of SBOM features with a paid account), please reach out to our team.