Using SPDX

 

Overview

Getting started with SPDX is easier than you think.  There are three different ways in which you can engage with SPDX. They are mutually exclusive, meaning you do not have to do one to do another. That said, each one is valuable in its own way for helping with license identification and ultimately compliance. The easiest things to start with are the SPDX License List or by using the license identifiers in your code. Just start using them wherever it is appropriate or makes sense for you to do so.  The pinnacle of SPDX is producing and/or consuming SPDX Documents.  Let’s look at each of these in turn.

In addition to the resources here you are encouraged to:

  • Attend the General Monthly Meeting. Frequently we have a guest speaker from business or the community who presents on their use of SPDX. Its a great way to see what others are doing and to share and ask questions.

 


 

License List

  

The SPDX License List is a list of commonly found licenses and exceptions used for open soruce and other collaborative software. The purpose of the SPDX License List is to enable easy and efficient identification of such licenses and exceptions in an SPDX document or elsewhere. The SPDX License List includes a standardized short identifier, full name, vetted license text, other basic information, and a canonical permanent URL for each license and exception. By providing a short identifier, users can efficiently refer to a license without having to redundantly reproduce the full license. License exceptions can be used with the SPDX License Expression operator, "WITH" to identify a license with an exception.   

Here are some relevant points about the list:

  • ~300 Licenses and exceptions as of July 2016
  • Short license identifiers for easy reference (see the identifier column in the figure to the right)
  • Exact text of licenses
  • Available on SPDX website – URLs won’t change
  • License Matching Guidelines - for matching licenses against those included on the SPDX License List
  • License Templates denote license text which is optional or replaceable per the license matching guidelines
  • Simple expression language for expressing conjunctive and disjunctive licensing

Where to use it

There are many possible uses of the SPDX License List and its collateral. Here are just a few key ones:

  • Use the standardized short identifier anywhere you would display or exchange the identity of an open source license. You can even link back to the SPDX License List for the text of the license. The license list links are immutable and the links will not change, ever. Note: Only use the identifier if the license text you are matching agrees with the text in the SPDX License List per the list matching guidelines. The power of the short identifier is that when you see it, you know exactly what the license text is!
  • Use the License List itself for internal reference or processes.
  • Use the matching guidelines and templates provided by the SPDX License List to help determine if the license text you see is the license. 

Pre-Requisites

Familiarity with the SPDX License List and where and how you will use it.

Further Information

The following links are meant to provide further information to references and resources you may need when working with the license list.

Examples 

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

 


 

SPDX License Identifiers in Source

The need to identify the license for open source software is critical for both reporting purposes and license compliance. However, determining the license can be difficult due to a lack of information or ambiguous information. Even when licensing information is present, a lack of consistent notation for providing license information can make automating the task of license detection very difficult, thus requiring vast amounts of human effort.  The SPDX Work-group proposes to use  SPDX license identifiers to indicate the license at the file level. The advantages of doing this are numerous but include:

  • It is precise; there is no ambiguity due to variations in license header text
  • It is language neutral
  • It is easy to machine process
  • It is concise
  • The license travels with the file (as sometimes not entire projects are used or license files are removed)
  • It is simple and can be used without much cost in interpreted environments like java Script, etc.
  • An SPDX license identifier is immutable.
  • It provides simple guidance for developers who want to make sure the license for their code is respected

Where to use it

Use in source files you create. Here is an example of a C style source licensing header using the Identifier. As you can see it is quite simple to do.

/*********

SPDX-License-Identifier: BSD-3-Clause

 

Copyright (c) 2016 Acme. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

*******/

Pre-Requisites

Before using the identifiers in your source you should be familiar with the license short identifiers from the SPDX License List and the license expression syntax. You can find reference to both in the Further Information Section.

Further Information

The following links are meant to provide further information to references and resources you may need when working with identifiers in your source.

Examples

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

 


 

Producing/Consuming 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 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 a 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.

Lets 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.