SPDX Structure

[augelu-tng]

The SPDX standard provides namespaces each with its own classes and profiles that define rules for how to use these classes.
For now we focus on the Core and Software namespaces and profiles. However, the Core and Software profiles do not really specify strict rules which classes to use. To get a starting point the Lite profile is a useful reference but we won't adhere strictly to it.

The Getting Started Example used the Elements as follows:

graph TD
    
    Agent["Agent"]
    CreationInfo["CreationInfo"]
    Package["Software/Package"]
    File1["Software/File"<br>arch/x86/boot/bzImage]
    File2["Software/File"<br>arch/x86/boot/vmlinux.bin]
    Sbom1["Software/Sbom"]
    Document["SpdxDocument"]

    %% Relationships
    Document -->|rootElement| Sbom1
    Sbom1 -->|rootElement| Package
    Sbom1 -->|element| Package
    Sbom1 -->|element| File1
    Sbom1 -->|element| File2
    Package -->|contains| File1
    File2 -->|generates| File1

Loading

The overall element structure should be as described in the diagram above.

• SpdxDocument single main entry point of the document
• Software/Sbom one Sbom element having the Package as rootElement
• Software/Package one Package
• Software/File one File element for each node in the cmd graph

Relationships:

• Package contains Files The package contains all source and output files
• Files generates File An output file is generated from input files through a build step.

Open Questions:

1. What spdxId schema should be used?
   For reference the schema used in the Getting Started Example is https://spdx.ord/spdxdocs/{entity-type}-{uuid}
2. SpdxDocument/ElementCollection has element and rootElement. Should we set both to our single Software/Sbom Element? or should element include deeper elements as a flat list?
   A: rootElement should be the direct child. element should be a flat list of all transitive childs.
3. Software/Package
   • copyrightText
   • name
   • packageVersion
     A: Use kernel build number provided as command line argument.
   • downloadLocation / packageUrl (git link to the repo?)
   • Relationship hasConcludedLicense (what to set here?)
   • Relationship hasDeclaredLicense (here we probably list all licenses that we found in the license headers of each source file in the package)
4. Core/Agent
   • name (what should be used here?)
5. Whats the role of the Build/Build class?
   A: Each node in the cmd graph is modeled as a Software/File element. The transition from one file to another is modeled as a Build/Build element. Each build element has a hasInput and hasOutput relationship which connects the build with the input and output File. This approach would get too big.
   There will be only one single Build/Build element that has all sources as input and the roots of the cmd graph as outputs.

[swinslow]

Here are a few thoughts on the questions listed above -- please note that I'm not at all an expert on SPDX 3.0, so others with more experience should feel free to weigh in as well!

1. What spdxId schema should be used?

For the URI prefix (https://spdx.org/spdxdocs/), this is something that I would say should be a user-configurable option with a default of https://spdx.org/spdxdocs/ if not otherwise specified. SPDX 2.3 and earlier were perhaps a bit clearer about how https://spdx.org/spdxdocs/ can be used as a placeholder -- see for example https://spdx.github.io/spdx-spec/v2.3/document-creation-information/#652-intent for more details.

For the rest of the URI following the prefix, I believe any characters can be used as long as together with the prefix it forms a valid URI. Some options include:

• just a UUID -- this is probably the simplest route to get going
• something that includes the type of the object together with a UUID -- this is what is shown in the "Getting Started" example, e.g. Person/JoshuaWatt-141ec767-40f2-4aad-9658-ac2703f3a7d9. This can be helpful at least to orient the SPDX consumer to what the ID is representing.
• something even more specific -- e.g. in the Zephyr SBOM generation, we baked the actual filenames into the IDs themselves. This makes it more legible to readers, but also raises the complexity for generating it due to annoying edge cases.

I'd suggest taking one of the first two options initially.

(minor note that there's a small typo in the question above -- spdx.ord should be spdx.org)

2. SpdxDocument/ElementCollection has element and rootElement. Should we set both to our single Software/Sbom Element? or should element include deeper elements as a flat list?

Unfortunately I don't think I know the right answer here. I'd expect others from the SPDX tech community would have better guidance here.

3. Software/Package

For simplicity, I might suggest to begin with that you just create a single Package that represents the entirety of the kernel build. E.g., one Package that collectively includes the source code, the configuration files, and the built binaries / other artifacts.

After that is working, you could consider whether breaking it apart to be more granular would be beneficial (such as having separate Packages to represent the built binaries vs. the original sources).

• copyrightText

I'd suggest using "NOASSERTION" in the first instance.

• name

Perhaps make it user-configurable with a default of just "Linux kernel" if not otherwise specified.

• packageVersion

From the above it looks like you already have an answer for this one.

• downloadLocation / packageUrl (git link to the repo?)

This depends a bit on how you are modeling what is "the Package." If it's the unmodified sources pulled from e.g. git.kernel.org, then yes, a git link to the repo would make sense.

If "the Package" instead includes configuration and/or build artifact information, then I am not sure whether a downloadLocation or packageUrl can be specified.

Looking at https://spdx.github.io/spdx-spec/v3.0.1/model/Software/Classes/Package/ I see that each of these has a minCount of 0, meaning that they are not mandatory fields -- so I would suggest omitting them in the first instance.

• Relationship hasConcludedLicense (what to set here?)

For the minimum / starting point version, I would go with the model representation for NOASSERTION -- I believe this would be a Relationship of type hasConcludedLicense to a NoAssertionElement.

• Relationship hasDeclaredLicense (here we probably list all licenses that we found in the license headers of each source file in the package)

For the "declared license" at the Package level, based on https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/COPYING I would use the following:

GPL-2.0 WITH Linux-syscall-note

I wouldn't list all licenses for this one, as the "declared license" at the Package level is intended to reflect the following (see https://spdx.github.io/spdx-spec/v3.0.1/model/Licensing/Licensing/):

. . . for Packages, it would include license info for the Package as a whole, found in the Package itself (e.g., LICENSE file, README file, metadata in the Package, etc.), but it would not include any license information that is not in the Package itself (e.g., license information from the project's website or from a third party repository or website).

The "concluded license" could be the place to include the AND-combined values for all applicable licenses in the source files, but... that is going to be very complex and perhaps not worth baking in at this initial stage. Hence the suggestion to use NOASSERTION for hasConcludedLicense as mentioned above.

4. Core/Agent -- name (what should be used here?)

Based on the getting started guide I am guessing you're referring to the use of an Agent in the CreationInfo => createdBy field.

If so, then instead of defining a Person as Joshua does in the getting started guide, I would suggest maybe defining a SoftwareAgent to use for the createdBy field.

For the SoftwareAgent's name, you could use anything simple and descriptive -- maybe "KernelSbom" or "Linux kernel SBOM builder".

5. Whats the role of the Build/Build class?

This is one that unfortunately I would definitely have to defer to others in the SPDX tech community for more info.