Skip to main content
search

Using SPDX Documents

While the SPDX License List and license identifiers in source allow more precision when conveying a license, it is the SPDX document which provide the most detail on a per package/file basis.  This introduction we will instead give you an idea of what an SPDX document is and what it can be used for, along with key points and links to additional information to get you started. This article will not go into detail about generating or consuming SPDX documents. Instead, it will direct you to relevant articles for more detail.

What is an SPDX Document?

SPDX documents describe the licensing associated with a set of file or files. These files can be organized into what we call a “Package”. A package is merely a grouping of files, with some association to each other as defined by the creator of the document. In general, the association should be obvious, such as an SPDX document for a sofwtare library or application. SPDX Documents can use one of two formats:

You can use either format and there are SPDX tools to convert one format to another. The format you use will be based on your own factors, preference, tools and use.

Packages and Relationships

While the single package concept of files worked well, the notion of relationships was added beginning with SPDX 2.0. This allows SPDX documents to address more complex use cases by being able to refer to one another along with what the relationship is between them.

As an example, consider a binary only delivery or download as shown in the figure below:

In this particular example, the binary SPDX document has two relationships: 1) That it was “generated from” these source files; and 2) It dynamically links, say at run time, with this particular library. This now gives a more complete licensing picture as you know the licenses of the sources used to build the application and then what it links with at run time as well.

Let’s look at another example where using relationships describes the licensing of all the items with an application and how they “fit” together.

In this example the application has some test software and documentation that comes with it. The application SPDX points to each of these to show that they are all “related” to this application and came with it. In turn each of the other SPDX documents (binary, source, test and documents) describes how they fit it in and what the licensing of that specific piece is.

Many real world use cases were analyzed and captured when adding the notion of relationships into the 2.0 specification.

Contents of a Document

SPDX Documents are composed of one or more sections. Some of these sections are required, while others are optional. If you examine the figure to the right, you will see the following sections as of the 2.1 Specification.

  • Document Creation Information – Denotes who created the document, how it was created and other useful information related to its creation.
  • Package Information – This section provides information about the “package”. A package can be one or more files. These files could be one or more files of any type including but not limited to source, documents, binaries, and so forth. The package information contains the originator, where it was sourced from, a download URL, a checksum and so forth. it also contains summary licensing for the package.
  • File Information –  This is information about a specific file. It can contain the file copyrights found in the file (if any), the license of the file, a checksum for the file, file contributors  and so forth.
  • Snippet Information – Snippet information can be used to define licensing for ranges within files.
  • Other Licensing Information – Other licensing information provides a way to describe licenses that are not on the SPDX License List. You can create a local (to the SPDX document) identifier for the license and place the license text itself in the document as a well and then reference it for files just like you would a license from the license list.
  • Relationships –  Relationships were introduced in the 2.0 specification and are a very powerful way of expressing how SPDX documents relate to one another. See explanation and example above.
  • Annotations – Annotations are comments made by people on various entities and elements within the document. For example, someone reviewing the document may make an annotation about a file and its license. Annotations are useful for reviews of SPDX documents and for conveying specific information about the package, file, creation, license, file(s), etc.

Where to use it

SPDX documents can be

  • used both internally and externally for an organization, group or community.
  • can be a part of your internal compliance program providing detailed license information
  • can be generated for files you make available to others
  • can be used to describe the licensing of files your receive.

Automated generation and scanning of SPDX documents for large open source code bases can be quite powerful.

Pre-Requisites

​You need to put some thought into how you will use and produce/consume SPDX documents.  Often it is best to start small and then grow your usage. In particular you should have a good understanding of the SPDX Specification, the SPDX License List, what tooling is available, and tool capabilities.

Further Information

The following links are meant to provide further information to references and resources you will likely need when working with SPDX Documents..

Examples

The following list is not meant to be exhaustive but to rather give you an idea of what some people/organizations are doing.

Close Menu