?um/p1-90`This Annex documents standard PURL qualifiers that may be used across many PURL type definitions.
The PURL qualifiers component provides flexibility to define important PURL information at the PURL type level. This flexibility is provided by key=value pairs. It may be tempting to use many key=value pairs to document many package attributes, but their usage should be limited to the minimal set of key=value pairs that are necessary for accurate package identification or location. This restraint is necessary to ensure that PURLs stay compact and human-readable.
Tools that build PURLs should sort multiple qualifiers lexicographically by key, but this is not expected behaviour for a tool to parse or validate a PURL.
The standards for the PURL qualifiers component and the key=value pairs are defined in two ECMA-427 clauses:
Many qualifiers are applicable to multiple PURL types. These qualifiers should be used according to the following definitions.
| key | Definition |
|---|---|
| checksum | One or more checksums stored as a comma-separated list |
| download_url | A URL for a direct package download URL |
| file_name | The file name of a package archive |
| repository_url | A URL for a package or software repository |
| vcs_url | A URL for a version control system (VCS) location |
| vers | A |
Each item in the value for a 'checksum' qualifier is in the form of 'lowercase_algorithm:hex_encoded_lowercase_value' such as 'sha1:ad9503c3e994a4f611a4892f2e67ac82df727086'. Multiple 'checksum' values are separated by an encoded comma ('%2C').
The following standard 'checksum' keys should be used where applicable. This is not an exclusive list.
| algorithm | key | used by |
|---|---|---|
| BLAKE2b-256 | blake2b-256 | pypi |
| BLAKE3 | blake3 | |
| MD5 | md5 | maven, pypi |
| RIPEMD-160 | ripemd160 | |
| SHAKE256 | shake256 | |
| SHA1 | sha1 | maven, npm |
| SHA2-224 | sha224 | |
| SHA2-256 | sha256 | cargo, gem, maven, npm |
| SHA2-384 | sha384 | npm |
| SHA2-512 | sha512 | npm, nuget |
| SHA3-224 | sha3-224 | |
| SHA3-256 | sha3-256 | |
| SHA3-384 | sha3-384 | |
| SHA3-512 | sha3-512 |
pkg:generic/openssl@1.1.10g?checksum=sha1:ad9503c3e994a4f%2Csha256:41bf9088b3a1e6c1ef1dMost package managers provide a mechanism to derive a 'download-url' from PURL data. Use this qualifier for use cases where the download URL for a package cannot be derived from the PURL or otherwise provided by the package manager. A 'download_url' value shall be
pkg:generic/openssl@1.1.10g?download_url=https:%2F%2Fopenssl.org%2Fsource%2Fopenssl-1.1.0g.tar.gzThis qualifier is intended for the use case where you need to specify the name of a package archive or other file. Use the subpath component for the use case where you need to specify a PURL at the file level.
pkg:pypi/django@1.11.1?file_name=Django-1.11.1.tar.gzpkg:pypi/django@1.11.1?file_name=Django-1.11.1-py2.py3-none-any.whlThis qualifieris intended for the use cases where:
type definition,
type.
A 'repository_url' value shall be
pkg:bazel/curl@8.8.0?repository_url=https:%2F%2Fexample.org%2Fbazel-registrypkg:huggingface/microsoft/deberta-v3-base@559062ad13d311b87b2c455e67dcd5f1c8f65111?repository_url=https:%2F%2Fhub-ci.huggingface.copkg:maven/groovy/groovy@1.0?repository_url=https:%2F%2Fmaven.google.comThis qualifier is intended for the use case where you need to specify a PURL at its Version Control System location. The syntax for 'vcs_url' is based on Python pip syntax at: https://pip.pypa.io/en/stable/topics/vcs-support/ The syntax is:
<vcs_tool>+<transport>://<host_name>[/<path_to_repository>][@<revision_tag_or_branch>]#<sub_path>]
This compact VCS location notation supports referencing locations in version control systems such as Git, Mercurial, Subversion and Bazaar, and specifies the type of VCS tool using url prefixes: 'git+', 'hg+', 'bzr+', 'svn+' and specific transport schemes such as SSH or HTTPS.
Using usernames and password in the host_name is not supported and should be reported by tools as an error.
Specifying sub-paths, branch names, a commit hash, a revision or a tag name is recommended, and supported, using the '@' delimiter for a commit version and the '#' delimiter for a sub-path.
In VCS location compact notations, the trailing slashes in host_name, and path_to_repository are not significant. Leading and trailing slashes in sub_path are not significant.
A 'vcs_url' value shall be
pkg:generic/bitwarden?vcs_url=git%2Bhttps:%2F%2Fgit.fsfe.org%2Fdxtr%2Fbitwarden%40cc55108da32pkg:npm/mypackage@12.4.5?vcs_url=git:%2F%2Fhost.com%2F%2Fpath%2Fto%2Frepo.git%404345abcd34343The primary use cases for this qualifier are to identify a version range for dependency analysis or vulnerability reporting. Use of this qualifier is mutually exclusive with use of the version component. The value for a 'vers' key shall adhere to the Version Range Specification.
pkg:pypi/django?vers=vers:pypi%2F%3E%3D1.11.0%7C%21%3D1.11.1%7C%3C2.0.0