Annex H SPDX File Tags (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. 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 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 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 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 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.

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.