Annex H Specifying SPDX information in source files (Informative)
SPDX short-form license identifiers using the
SPDX-License-Identifier: tag, as described in Annex E, provide a mechanism for developers to easily convey information about the licenses they declare on a file-by-file basis. That mechanism is intentionally very easy for software tools to identify and detect, since it includes a standard text string that is unlikely to occur in other contexts, and since it uses license identifiers from the SPDX License List or from user-defined
The SPDX specification defines various other fields in the File Information section (Clause 8) that are also useful for conveying information on a file-by-file basis, as well as snippet-level information in Snippet Information section (Clause 9). For example, the REUSE Software guidelines community expressed interest in having a similar method to recommend that developers use to express their copyright notices in a machine-readable manner.
This appendix describes a mechanism, similar to
SPDX-License-Identifier, for developers to convey such other file-based and snippet-based information easily in comments in their files. This in turn enables software tools to easily find and extract that information, and to insert it into the corresponding fields of an SPDX document generated by those tools.
An SPDX file tag consists of a single line, generally as part of a comment near the top of the file, in the following format:
where tagname is replaced by the 'tag' defined for tag-value SPDX documents for that field, according to the File Information section of the SPDX specification. The meaning and semantics of any SPDX file tag are intended to be identical to those described in the File Information (Clause 8) section of the SPDX specification.
File type (see 8.3):
SPDX-FileType: SOURCE SPDX-FileType: DOCUMENTATION SPDX-FileType: TEXT
Copyright text (see 8.8):
SPDX-FileCopyrightText: 2019 Jane Doe <firstname.lastname@example.org> SPDX-FileCopyrightText: Copyright 2008-2010 John Smith SPDX-FileCopyrightText: Copyright Example Company SPDX-FileCopyrightText: Copyright contributors to the Foo project.
File contributors (see 8.14):
SPDX-FileContributor: Modified by Jane Doe SPDX-FileContributor: The Regents of the University of California
SPDX file tags of a particular type may appear one or multiple times in a file, depending on the corresponding cardinality defined for that field in the File Information section of the SPDX specification.
Multiple-line values are not recommended, because doing so will make it harder for simple search tools to extract all data by looking only for lines beginning with the relevant tag.
Version 3.0 of the REUSE Software guidelines implements this format, via a recommendation to use the tag
SPDX-FileCopyrightText: to include copyright notices as part of a file's comment headers.
If certain SPDX tags are to apply only to a certain snippet instead of the whole file, SPDX snippet tags should be used.
SPDX snippet tags should start with
SPDX-SnippetBegin to mark the beginning of the snippet and end with
SPDX-SnippetEnd to mark its end, in the following format:
SPDX-SnippetBegin SPDX-tagname: <value> ... SPDX-SnippetEnd
where tagname is replaced by the 'tag' defined for tag-value SPDX documents for that field, according to the Snippet Information section of the SPDX specification, and
... represents the code snippet itself. The meaning and semantics of any SPDX snippet tag are intended to be identical to those described in the Snippet Information (Clause 9) section of the SPDX specification.
Snippets may nest, and this is denoted by having
SPDX-SnippetEnd pairs within other pairs, in the same way that parentheses nest in mathematical expressions. In the case of nested snippets, the SPDX file tags are considered to apply to the inner-most snippet.
Simple stand-alone example:
SPDX-SnippetBegin SPDX-License-Identifier: MIT SPDX-SnippetCopyrightText: 2022 Jane Doe <email@example.com> ... SPDX-SnippetEnd
Two snippets with a different license and additional information in the broader context of a file:
SPDX-License-Identifier: GPL-2.0-or-later SPDX-FileCopyrightText: Copyright contributors to the Foo project. ... SPDX-SnippetBegin SPDX-License-Identifier: MIT SPDX-SnippetCopyrightText: 2022 Jane Doe <firstname.lastname@example.org> SDPX—SnippetName: functionX from project Bar SPDX-SnippetComment: A complex function X that was copy-pasted from project Bar ... SPDX-SnippetEnd ... SPDX-SnippetBegin SPDX-License-Identifier: BSD-2-Clause SPDX-SnippetCopyrightText: Copyright Example Company ... SPDX-SnippetEnd
SPDX-SnippetBegin SPDX-License-Identifier: MIT SPDX-SnippetCopyrightText: 2022 Jane Doe <email@example.com> ... SPDX-SnippetBegin SPDX-License-Identifier: BSD-2-Clause SPDX-SnippetCopyrightText: Copyright Example Company ... SPDX-SnippetEnd ... SPDX-SnippetEnd
A creator of an SPDX document may elect to disregard any or all file tags in any file. SPDX document creators should determine for themselves the extent to which they will rely upon the information specified in a file tag.
Not all fields in the File Information section will be useful or relevant to use as file tags. For example,
SPDX-FileName is unnecessary as it can be easily derived from the actual file name;
SPDX-SPDXID is likely to be ignored by an SPDX document creator who may need to define their own SPDXRef- ID system for their document; etc.
Another more complex example are
SPDX-SnippetEnd where the line number these two tags are found in could be stored to start and end the range in
SnippetLineRange (see 9.4).
The short-form license identifiers described in Annex E do not follow the file tag convention described above. The
SPDX-License-Identifier emerged from the broader community prior to being defined in the SPDX specification, so it does not map to a
License-Identifier field in the File Information section.