QUIP 7 | qt_attribution.json File Format

QUIP:7
Title:qt_attribution.json File Format
Version:61fb930f11cabdb50559faa1ee777aaeb9800463
Last-Modified:2019-02-14
Author:Kai Köhne
Status:Active
Type:Implementation
Created:2017-02-15
Post-History:https://lists.qt-project.org/pipermail/development/2017-March/029198.html

Overview

From Qt 5.8, Qt modules document their 3rd party code in qt_attribution.json files. The format is JSON-based and can be processed with the qtattributionscanner tool.

This QUIP is about the file format of the qt_attribution.json files. See QUIP 4 for the process on how to add and update 3rd party code to Qt.

File Format

A qt_attribution.json file needs to contain one JSON object or an array of such objects. Each object's properties have the following meanings:

Id
Unique name for component, without spaces. All lower case. Mandatory.
Name
Descriptive name of the component, without version number. Camel case. Mandatory.
QDocModule
The qch file the documentation of the component should be part of. Mandatory.
QtParts
Array with possible entries "examples", "tests", "tools", or "libs". Components that will be included in Qt libraries or plugins should set "libs", components that will be included in executables like Qt Designer or are part of the build infrastructure "tools". Optional, default is [ "libs" ].
QtUsage
Free text on where the Third-Party Component in Qt is used, when it is included (e.g. if it's limited to a specific platform), how to avoid it (e.g. by using configure options), and what functionality is missing in this case. Mandatory.
Path
(Relative) path to the sources. Default is same directory as the file. Optional.
Description
A short description of what the component is and is used for. Optional.
Homepage
Homepage of the upstream project. Optional.
Version
Version used from the upstream project. This can also be a revision number or commit hash from a version control system. Optional.
DownloadLocation
Link to exact upstream version. Optional.
License
The license under which the component is distributed, preferably with the names from SPDX [1] 'Full Name'. Mandatory.
LicenseId
SPDX License Identifier [1], or an SPDX Expression [2]. Optional.
LicenseFile
Relative path to file containing the license text. Optional for code in the Public Domain, otherwise needed.
Copyright

Aggregated list of copyright lines. Mandatory.

The list can be edited for brevity by, for example, combining different copyright years for the same author. Terms like "All rights reserved" can be removed, too.

If there are too many copyright lines in the sources, aggregating them into:

Copyright YYYY The x project contributors

or:

Copyright YYYY <main author> and contributors

is also acceptable.