Home » Specification

Usage Guidelines

Frequently Asked Questions

A list of SPDX Frequently Asked Questions can be found here: FAQ Link.

SPDX Usage Guidelines

The SPDX specification is a standard data representation of licensing and copyright information found in a software package. There are two different kinds of users of SPDX data – Producers and Consumers. Producers generate or export well structured SPDX files that adhere to the terms of the SPDX specification. Consumers read and use the SDPX data typically to comply with the licensing terms of the different files contain within a software package. We focus on Consumer usage of SPDX data here. SPDX data is stored in a single file using one of two possible syntax formats: Resource Description Framework (RDF) or as an annotate tag value flat text file. The usage discussion is independent of the syntax format used.

There are two different kinds of users of SPDX data – Producers and Consumers. Producers generate or export well structured SPDX files that adhere to the terms of the SPDX specification. Consumers read or import and use the SDPX data typically to comply with the licensing terms of the different files contain within a software package. We focus on Consumer usage of SPDX data.

  • An SPDX file (document) is composed of six main sections that include:
  • SPDX Document/File Information
  • Creation Information
  • Package Information
  • Other Licensing Information
  • File Information
  • Review Information

 

SPDX data is intended to be human readable. One useful way to think about the structure of an SPDX file is to view each of the six sections as separate worksheet contained within a single spreadsheet where each worksheet (section) represents one or more records (rows). For example, the Package Information section (worksheet) contains general information about the package and is represented as a single record (row) that includes the package name, version, description, declared license and so forth. The File Information section (worksheet) contains general information about each file in a package and is represented as a set of records (rows), one per file, where each record includes the file name, file type, checksum, licensing terms, copyright info and so forth. We discuss the usage of each of the six main sections below.

SPDX Document/File Information Section

This section includes two basic pieces of information that are specific to the attributes of the SPDX file itself. 1) The version of the SPDX specification followed to produce the SPDX data and 2) the license covering the data within the file.  SPDX version 1.0 requires that the SPDX file data be licensed under the Open Data Commons Public Domain Dedication and License 1.0 (“PDDL-1.0”). Later versions changed the license to the Create Commons Zero license. It is also possible to receive an SPDX file under confidential terms. You should check this Data License field and consult with your legal counsel with respective to the terms covering the of the SPDX file you are using. There is just one instance of the SPDX document/File Information record.

Creation Information

This section represents one instance of a record that includes three fields of information with respect to the SPDX file’s creation: who originally created the file, when it was created and any comments the creator may want to provide the consumer of the file. These three fields are self explanatory. Come uses of the Creator Comment field is to provide disclaimers, rules of thumb used in determining the licensing or which compiler was used to create the binary files found within the package.

Package Information

A software package is the highest level single unit that is being represented by an SPDX file. That is, an SPDX file represents all the licensing and copyright information found within the package including the licensing that governs the entire package as a whole along with licensing of the individual files included in the package. This section provides just a single record of general information about the package as a whole. It includes the following:

  • Formal name of the package
  • Version of the package
  • Package File Name
  • Description of the package
  • Download location
  • Package Unique Identifier
  • Package Checksum
  • Source Information
  • Package Declared License
  • License Concluded by the creator of the SPDX file
  • List of all licenses found in the package at the file level
  • Copyright text and dates

Most of the above fields are self explanatory. The ones that typical require additional clarification are:  Package Unique Identifier, Package Declared License vs License concluded by the creator.

Package Unique Identifier is a specially designed checksum value computed to unique identify given specific instance of a package. It allows two things: One - the ability to verify that a specific instance of a package contains the exact same contents at the time the initial SPDX analysis was performed. That no modifications (additions or subtractions) were made since the initial analysis was performed. Two – the package has the same exact contents except possibly for the additional inclusion of the SPDX file into the package. That is, the Unique Identifier should be the same provide nothing else changed within the package except possibly for the addition of the SPDX file in the package.

 The Declared Package License field lists the licenses that have been declared by the authors of the package to govern the package. Any license information that does not originate from the package authors, e.g. license information from a third party repository, would not be included in this field.

The License Concluded  field contains the license the SPDX file creator has concluded as governing the package or an alternative value, if the governing license could not be determined (e.g., NOASSERTION or NONE). When the Declared License and Concluded license fields are different the creator should describe why in the License Comments field. This field should also include information or analysis that went in to arriving at the Concluded License for a package. If the Concluded License does not match the Declared License or License Information from Files, this should be explained by the SPDX file creator. It is also preferable to include an explanation here when the Concluded License is NOASSERTION.

Other Licensing Information

SPDX provides a standard license list to be used to fill in the various license fields in other sections of an SPDX file. During the creation of an SPDX file, one may encounter a license or set of licensing terms that are not represented by one or more licenses in the standard license list. The SPDX creator creates a new license reference record for every unique license or set of licensing terms detected in package that does not match one of the licenses on the SPDX License List. Each new license reference can be found in this section. This section contains one or more instances of new license references.

Each license instance has the following two fields: Identifier Assigned and Extracted Text. The Identifier Assigned (License ID) has the following format:

LicenseRef-"N

where N is a unique numeric value.  The License ID may be found in any field that would expect a standard license ID. The Extracted Text field provides a copy of the actual text of the license reference extracted from the package or file that is associated with the License ID.

File Information

One of the big benefits of SPDX is it potential provides licensing information for each file in a software package. This section contains a record for each file in the package. The record contains the following information fields:

  • File Name (including full path)
  • File Type (source, binary, archive, other)
  • File Checksum
  • License Information contained in File
  • Concluded License (by SPDX creator)
  • Comments on License
  • Copyright owners (if listed)
  • Copyright dates (if listed)
  • Associated project from which the file may have come

Most of the above fields are self explanatory. We discuss the fields that typical require additional clarification are.

License Information contained in File field includes license information actually found in the file, if any. Any license information not actually in the file, e.g., “COPYING.txt” file in a top level directory, should not be reflected in this field. This information is most commonly found in the header of the file, although it may be in other areas of the actual file. This field is typically filled in with some combination of license names from the SPDX standard list or package defined license references. When no information is found in the file the value NONE is assigned. NOASSERTION is used if the SPDX file creator has not examined the contents of the actual file or the SPDX file creator has intentionally provided no information (no meaning should be implied by doing so).

The Concluded License field contains the license the SPDX file creator has concluded as governing the package or an alternative value, if the governing license could not be determined (e.g., NOASSERTION or NONE). When the values License Information contained in File field and Concluded License fields are different, the creator should describe why in the Comments on License field. This field should also include information or analysis that went in to arriving at the Concluded License for a package. If the Concluded License does not match the Declared License or License Information from Files, this should be explained by the SPDX file creator. It is also preferable to include an explanation here when the Concluded License is NOASSERTION.

Review Information

Review information can be added after the initial SPDX file has been created. The set of fields are optional and multiple instances can be added. The fields include:

  • Reviewer
  • Reviewer Date
  • Review Comments

 

Once a Reviewer entry is added, the Review Date associated with the review is mandatory. The Created date should not be modified as a result of the addition of information regarding the conduct of a review.