Annex H Specifying SPDX information in source files (Informative)

H.1 Rationale

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 LicenseRef- statements.

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.

H.2 File tags format

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:

SPDX-tagname: <value>

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.

Examples:

File type (see 8.3):

SPDX-FileType: SOURCE
SPDX-FileType: DOCUMENTATION
SPDX-FileType: TEXT

Copyright text (see 8.8):

SPDX-FileCopyrightText: 2019 Jane Doe <jane@example.com>
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.

H.3 Snippet tags format

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.

Any Snippet Information (Clause 9) and short-form license identifiers (Annex E) tags found between begin and end tags mentioned above apply only to such snippet.

Snippets may nest, and this is denoted by having SPDX-SnippetBegin/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.

Examples:

Simple stand-alone example:

SPDX-SnippetBegin
SPDX-License-Identifier: MIT
SPDX-SnippetCopyrightText: 2022 Jane Doe <jane@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 <jane@example.com>
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

Nesting snippets:

SPDX-SnippetBegin
SPDX-License-Identifier: MIT
SPDX-SnippetCopyrightText: 2022 Jane Doe <jane@example.com>

...

SPDX-SnippetBegin
SPDX-License-Identifier: BSD-2-Clause
SPDX-SnippetCopyrightText: Copyright Example Company

...

SPDX-SnippetEnd

... 

SPDX-SnippetEnd

H.4 Caveats

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-SnippetBegin and 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.