From be50a0b1f7f18f455749d9201c727950da501a11 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Thu, 5 Oct 2023 15:33:53 -0400 Subject: [PATCH 01/24] Add `format` qualifier to pypi. This allows the PURL to specify the specific artifact that was used. Signed-off-by: Mark Lodato --- PURL-TYPES.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 27e747c..9450107 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -461,9 +461,11 @@ pypi - PyPI treats ``-`` and ``_`` as the same character and is not case sensitive. Therefore a PyPI package ``name`` must be lowercased and underscore ``_`` replaced with a dash ``-``. +- The ``filename`` qualifier selects a particular distribution file (case-sensitive). - Examples:: pkg:pypi/django@1.11.1 + pkg:pypi/django@1.11.1?filename=Django-1.11.1-py2.py3-none-any.whl pkg:pypi/django-allauth@12.23 rpm From c5681aecd119de7db0e044efedf0957fd0f1af0b Mon Sep 17 00:00:00 2001 From: Giuseppe Di Terlizzi Date: Sun, 5 May 2024 17:51:48 +0200 Subject: [PATCH 02/24] Added CPAN tests --- test-suite-data.json | 72 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/test-suite-data.json b/test-suite-data.json index a819fc8..689741a 100644 --- a/test-suite-data.json +++ b/test-suite-data.json @@ -550,5 +550,77 @@ "qualifiers": null, "subpath": null, "is_invalid": false + }, + { + "description": "cpan distribution name are case sensitive", + "purl": "pkg:cpan/DROLSKY/DateTime@1.55", + "canonical_purl": "pkg:cpan/DROLSKY/DateTime@1.55", + "type": "cpan", + "namespace": "DROLSKY", + "name": "DateTime", + "version": "1.55", + "qualifiers": null, + "subpath": null, + "is_invalid": false + }, + { + "description": "cpan module name are case sensitive", + "purl": "pkg:cpan/URI::PackageURL@2.11", + "canonical_purl": "pkg:cpan/URI::PackageURL@2.11", + "type": "cpan", + "namespace": null, + "name": "URI::PackageURL", + "version": "2.11", + "qualifiers": null, + "subpath": null, + "is_invalid": false + }, + { + "description": "cpan module name like distribution name", + "purl": "pkg:cpan/Perl-Version@1.013", + "canonical_purl": "pkg:cpan/Perl-Version@1.013", + "type": "cpan", + "namespace": null, + "name": "Perl-Version", + "version": "1.013", + "qualifiers": null, + "subpath": null, + "is_invalid": true + }, + { + "description": "cpan distribution name like module name", + "purl": "pkg:cpan/GDT/URI::PackageURL@2.11", + "canonical_purl": "pkg:cpan/GDT/URI::PackageURL", + "type": "cpan", + "namespace": "GDT", + "name": "URI::PackageURL", + "version": null, + "qualifiers": null, + "subpath": null, + "is_invalid": true + }, + { + "description": "cpan valid module name", + "purl": "pkg:cpan/DateTime@1.55", + "canonical_purl": "pkg:cpan/DateTime@1.55", + "type": "cpan", + "namespace": null, + "name": "DateTime", + "version": "1.55", + "qualifiers": null, + "subpath": null, + "is_invalid": false + }, + { + "description": "cpan valid module name without version", + "purl": "pkg:cpan/URI", + "canonical_purl": "pkg:cpan/URI", + "type": "cpan", + "namespace": null, + "name": "URI", + "version": null, + "qualifiers": null, + "subpath": null, + "is_invalid": false } ] From 0ac4b4864af03b1fb67f8ab8194249d927c68597 Mon Sep 17 00:00:00 2001 From: Giuseppe Di Terlizzi Date: Sat, 11 May 2024 01:41:00 +0200 Subject: [PATCH 03/24] Fix typo --- PURL-TYPES.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index a0df8e0..0ed69c3 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -172,7 +172,7 @@ cpan ---- ``cpan`` for CPAN Perl packages: -- The default respository is ``https://www.cpan.org/``. +- The default repository is ``https://www.cpan.org/``. - The ``namespace``: - To refer to a CPAN distribution name, the ``namespace`` MUST be present. In this case, the namespace is the CPAN id of the author/publisher. It MUST be written uppercase, followed by the distribution name in the ``name`` component. A distribution name may NEVER contain the string ``::``. - To refer to a CPAN module, the ``namespace`` MUST be absent. The module name MAY contain zero or more ``::`` strings, and the module name MUST NOT contain a ``-`` @@ -182,7 +182,7 @@ cpan - Optional qualifiers may include: - ``repository_url``: CPAN/MetaCPAN/BackPAN/DarkPAN repository base URL (default is ``https://www.cpan.org``) - - ``download_url``: URL of package or distibution + - ``download_url``: URL of package or distribution - ``vcs_url``: extra URL for a package version control system - ``ext``: file extension (default is ``tar.gz``) @@ -374,7 +374,7 @@ luarocks The full version number is required to uniquely identify a version. - Qualifier ``repository_url``: The LuaRocks rocks server to be used; useful in case a private server is used (optional). - If ommitted, ``https://luarocks.org`` as default server is assumed. + If omitted, ``https://luarocks.org`` as default server is assumed. Examples:: From 4de99493686a090f4bef4ea4ab12c4e3f6c8c7dd Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 27 Jul 2024 00:53:07 +0100 Subject: [PATCH 04/24] Known type definitions is in PURL-TYPES.rst Currently, the text said: > (See) PURL-SPECIFICATION.rst for known type definitions. which is not correct. - `PURL-SPECIFICATION.rst` is the core spec. - Type definitions are in `PURL-TYPES.rst` Edit to use similar sentence structure as one in [PURL-TYPES.rst](https://github.com/package-url/purl-spec/blob/master/PURL-TYPES.rst): > See also https://github.com/package-url/purl-spec and PURL-SPECIFICATION.rst for the Package URL specification. --- PURL-SPECIFICATION.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 19bcf9f..d182d99 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -14,8 +14,8 @@ packaging conventions, tools, APIs and databases. Such a package URL is useful to reliably reference the same software package using a simple and expressive syntax and conventions based on familiar URLs. -See https://github.com/package-url/purl-spec for the Package URL specification -and ``_ for known type definitions. +See also https://github.com/package-url/purl-spec and +and ``_ for known type definitions. Check also this short `purl` presentation (with video) at FOSDEM 2018 https://fosdem.org/2018/schedule/event/purl/ for an overview. From 6c5c34c8c431a43433242108d98b8a0f5406211c Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 27 Jul 2024 00:56:51 +0100 Subject: [PATCH 05/24] Update PURL-SPECIFICATION.rst --- PURL-SPECIFICATION.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index d182d99..1119411 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -14,7 +14,7 @@ packaging conventions, tools, APIs and databases. Such a package URL is useful to reliably reference the same software package using a simple and expressive syntax and conventions based on familiar URLs. -See also https://github.com/package-url/purl-spec and +See also https://github.com/package-url/purl-spec and ``_ for known type definitions. Check also this short `purl` presentation (with video) at FOSDEM 2018 From 1b30581384b7866befa2bd99b59d9e3596cf3090 Mon Sep 17 00:00:00 2001 From: Giuseppe Di Terlizzi Date: Tue, 27 Aug 2024 22:37:07 +0200 Subject: [PATCH 06/24] Use MUST NOT --- PURL-TYPES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 0ed69c3..22ab6c8 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -174,7 +174,7 @@ cpan - The default repository is ``https://www.cpan.org/``. - The ``namespace``: - - To refer to a CPAN distribution name, the ``namespace`` MUST be present. In this case, the namespace is the CPAN id of the author/publisher. It MUST be written uppercase, followed by the distribution name in the ``name`` component. A distribution name may NEVER contain the string ``::``. + - To refer to a CPAN distribution name, the ``namespace`` MUST be present. In this case, the namespace is the CPAN id of the author/publisher. It MUST be written uppercase, followed by the distribution name in the ``name`` component. A distribution name MUST NOT contain the string ``::``. - To refer to a CPAN module, the ``namespace`` MUST be absent. The module name MAY contain zero or more ``::`` strings, and the module name MUST NOT contain a ``-`` - The ``name`` is the module or distribution name and is case sensitive. From db452ca3a5cd696199ca360a670f2fa0acae066e Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Sat, 28 Sep 2024 23:33:18 +0700 Subject: [PATCH 07/24] Fix casing: semver -> SemVer; nevra -> NEVRA Use casing according to official document - https://semver.org/ - https://docs.fedoraproject.org/en-US/modularity/core-concepts/nsvca/ Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 0d043ed..69e5014 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -187,7 +187,7 @@ The rules for each component are: - A ``version`` must be a percent-encoded string - A ``version`` is a plain and opaque string. Some package ``types`` use versioning - conventions such as semver for NPMs or nevra conventions for RPMS. A ``type`` + conventions such as SemVer for NPMs or NEVRA conventions for RPMS. A ``type`` may define a procedure to compare and sort versions, but there is no reliable and uniform way to do such comparison consistently. From 50f3490716885993e6c4903404b562059d2bf433 Mon Sep 17 00:00:00 2001 From: Andrew Pollock Date: Wed, 2 Oct 2024 02:15:44 +0000 Subject: [PATCH 08/24] docs(vers): clarify what is (not) NVD There's unfortunately a lot of confusion about where the boundaries are between the CVE Program's CVE List and NIST's NVD. Ensure that the documentation here is not perpetuating misinformation and communicating unambiguously. https://xkcd.com/386/ --- VERSION-RANGE-SPEC.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index 945fd43..31c6dfb 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -115,7 +115,7 @@ conventions in use: version. And also provides a concrete enumeration of the available ranges as a daily feed. -- The version 5 of the NVD CVE JSON data format at +- The version 5 of the CVE JSON data format at https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0.schema#L303 defines version ranges with a starting version, a versionType, and an upper limit for the version range as lessThan or lessThanOrEqual; or an enumeration @@ -752,7 +752,7 @@ most vulnerable ranges yet: and vulnerable ranges when a version must be excluded and the set of existing versions is not yet known, -- this make some ranges more verbose such as with the NVD CVE v5 API ranges +- this make some ranges more verbose such as with the CVE v5 API ranges notation that can include their upper limit and would need two constraints. Another high level difference between the two specifications are the @@ -761,7 +761,7 @@ the Package URL package "type" used in ``vers``. This spec will provide a strict mapping between the OSV ecosystem and the ``vers`` versioning schemes values. -Why not use the NVD CVE v5 API Ranges? +Why not use the CVE v5 API Ranges? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See: @@ -769,7 +769,7 @@ See: - https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json#L303 - https://github.com/CVEProject/cve-schema/blob/master/schema/v5.0/CVE_JSON_5.0_schema.json#L123 -The version 5 of the NVD CVE JSON data format defines version ranges with a +The version 5 of the CVE JSON data format defines version ranges with a starting version, a versionType, and an upper limit for the version range as lessThan or lessThanOrEqual or as an enumeration of versions. The versionType and the package collectionURL possible values are only indicative and left out @@ -778,16 +778,16 @@ of this specification and both seem strictly equivalent to the Package URL The semantics and expressiveness of each range are similar and ``vers`` provides a compact notation rather than a more verbose JSON notation. ``vers`` supports -strictly the conversion of any NVD v5 range to its notation and further +strictly the conversion of any CVE v5 range to its notation and further provides a concrete list of well known versioning schemes. ``vers`` design was -informed by the NVD CVE v5 API schema spec and its authors. +informed by the CVE v5 API schema spec and its authors. -When NVD v5 becomes active, this spec will provide a strict mapping between the -NVD versionType and the ``vers`` versioning schemes values. Furthermore, this +When CVE v5 becomes active, this spec will provide a strict mapping between the +CVE ``versionType`` and the ``vers`` versioning schemes values. Furthermore, this spec and the Package URL "types" should be updated accordingly to provide -a mapping with the upcoming NVD collectionURL that will be effectively used. +a mapping with the upcoming CVE ``collectionURL`` that will be effectively used. -There is one issue with NVD v5: it introduces a new trailing "*" notation that +There is one issue with CVE v5: it introduces a new trailing "*" notation that does not exists in most version ranges notations and may not be computable easily in many cases. The description of the "lessThan" property is: @@ -806,7 +806,7 @@ The conversion to ``vers`` range should be: computed for ``semver`` versions as ``>=1.0|<2`` but is not accurate unless as versioning schemes have different rules. For instance, pre-release may be treated in some case as part of the v1. branch and in some other cases as part - of the v2. branch. It is not clear if with "2.*" the NVD spec means: + of the v2. branch. It is not clear if with "2.*" the CVE v5 spec means: - ``<2`` - or something that excludes any version string that starts with ``2.`` From 162e33ff65c5f42a1ea6ced1304fca49abe66843 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Sat, 19 Oct 2024 02:50:44 +0200 Subject: [PATCH 09/24] docs: add known implementations --- README.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.rst b/README.rst index 2781828..94f873a 100644 --- a/README.rst +++ b/README.rst @@ -156,15 +156,18 @@ type definitions: Known implementations ~~~~~~~~~~~~~~~~~~~~~ -- in Golang: https://github.com/package-url/packageurl-go - for .NET: https://github.com/package-url/packageurl-dotnet -- for the JVM: https://github.com/package-url/packageurl-java, +- in Elixir: https://github.com/jshmrtn/purl +- in Go: https://github.com/package-url/packageurl-go +- in Java: https://github.com/package-url/packageurl-java, https://github.com/sonatype/package-url-java +- in JavaScript: https://github.com/package-url/packageurl-js +- in Perl: https://github.com/giterlizzi/perl-URI-PackageURL +- in PHP: https://github.com/package-url/packageurl-php - in Python: https://github.com/package-url/packageurl-python +- in Ruby: https://github.com/package-url/packageurl-ruby - in Rust: https://github.com/package-url/packageurl.rs -- in JS: https://github.com/package-url/packageurl-js -- in Elixir: https://github.com/jshmrtn/purl -- in Perl: https://github.com/giterlizzi/perl-URI-PackageURL +- in Swift: https://github.com/package-url/packageurl-swift Users, adopters and links From c824b8bda0317fbbc20be724d31f8d4dd5619632 Mon Sep 17 00:00:00 2001 From: Jan Kowalleck Date: Mon, 21 Oct 2024 14:14:17 +0200 Subject: [PATCH 10/24] updated elixir implementation jshmrtn/purl redirects to maennchen/purl --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 94f873a..d520a5c 100644 --- a/README.rst +++ b/README.rst @@ -157,7 +157,7 @@ Known implementations ~~~~~~~~~~~~~~~~~~~~~ - for .NET: https://github.com/package-url/packageurl-dotnet -- in Elixir: https://github.com/jshmrtn/purl +- in Elixir: https://github.com/maennchen/purl - in Go: https://github.com/package-url/packageurl-go - in Java: https://github.com/package-url/packageurl-java, https://github.com/sonatype/package-url-java From d87a58102db61ba4d737c01976c85246ca58bece Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Thu, 7 Nov 2024 19:08:53 +0000 Subject: [PATCH 11/24] Update PURL-SPECIFICATION.rst Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 1119411..781765c 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -14,7 +14,7 @@ packaging conventions, tools, APIs and databases. Such a package URL is useful to reliably reference the same software package using a simple and expressive syntax and conventions based on familiar URLs. -See also https://github.com/package-url/purl-spec +See https://github.com/package-url/purl-spec for the Package URL specification and ``_ for known type definitions. Check also this short `purl` presentation (with video) at FOSDEM 2018 From 2fd6aca72a3f6a8124ead392c876a6e1364f4b05 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Thu, 7 Nov 2024 20:57:01 +0000 Subject: [PATCH 12/24] Update PURL-SPECIFICATION.rst Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 41f6d64..e425760 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -14,8 +14,7 @@ packaging conventions, tools, APIs and databases. Such a package URL is useful to reliably reference the same software package using a simple and expressive syntax and conventions based on familiar URLs. -See https://github.com/package-url/purl-spec for the Package URL specification -and ``_ for known type definitions. +See _ for known type definitions. Check also this short ``purl`` presentation (with video) at FOSDEM 2018 https://fosdem.org/2018/schedule/event/purl/ for an overview. From 38d16c438c37af094e4f02a126514ece83b9bb6d Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Thu, 7 Nov 2024 21:13:08 +0000 Subject: [PATCH 13/24] Fix typos/casing - vcs -> VCS - cannot contains -> cannot contain - Uppercase first characters of few bullet points to make it consistent with other bullets Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 08a635a..7b2a802 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -104,7 +104,7 @@ A ``purl`` is a URL - Version control system (VCS) URLs such ``git://``, ``svn://``, ``hg://`` or as defined in Python pip or SPDX download locations are NOT valid ``purl`` types. They are valid URL or URI schemes but they are not ``purl``. - They are a closely related, compact and uniform way to reference vcs URLs. + They are a closely related, compact and uniform way to reference VCS URLs. They may be used as references in separate attributes outside of a ``purl`` or in a ``purl`` qualifier. @@ -150,7 +150,7 @@ The rules for each component are: - The package ``type`` is composed only of ASCII letters and numbers, '.', '+' and '-' (period, plus, and dash) - The ``type`` cannot start with a number - - The ``type`` cannot contains spaces + - The ``type`` cannot contain spaces - The ``type`` must NOT be percent-encoded - The ``type`` is case insensitive. The canonical form is lowercase @@ -209,7 +209,7 @@ The rules for each component are: - A ``key`` cannot start with a number - A ``key`` must NOT be percent-encoded - A ``key`` is case insensitive. The canonical form is lowercase - - A ``key`` cannot contains spaces + - A ``key`` cannot contain spaces - A ``value`` must be a percent-encoded string - The '=' separator is neither part of the ``key`` nor of the ``value`` @@ -281,7 +281,7 @@ To build a ``purl`` string from its components: - Start a ``purl`` string with the "pkg:" ``scheme`` as a lowercase ASCII string -- Append the ``type`` string to the ``purl`` as a lowercase ASCII string +- Append the ``type`` string to the ``purl`` as a lowercase ASCII string - Append '/' to the ``purl`` @@ -318,15 +318,15 @@ To build a ``purl`` string from its components: - Append '?' to the ``purl`` - Build a list from all key/value pair: - - discard any pair where the ``value`` is empty. + - Discard any pair where the ``value`` is empty. - UTF-8-encode each ``value`` if needed in your programming language - If the ``key`` is ``checksums`` and this is a list of ``checksums`` join this list with a ',' to create this qualifier ``value`` - - create a string by joining the lowercased ``key``, the equal '=' sign and + - Create a string by joining the lowercased ``key``, the equal '=' sign and the percent-encoded ``value`` to create a qualifier - - sort this list of qualifier strings lexicographically - - join this list of qualifier strings with a '&' ampersand + - Sort this list of qualifier strings lexicographically + - Join this list of qualifier strings with a '&' ampersand - Append this string to the ``purl`` - If the ``subpath`` is not empty and not composed only of empty, '.' and '..' @@ -359,7 +359,7 @@ To parse a ``purl`` string in its components: - Strip the right side from leading and trailing '/' - Split this on '/' - Discard any empty string segment from that split - - Discard any '.' or '..' segment from that split + - Discard any '.' or '..' segment from that split - Percent-decode each segment - UTF-8-decode each segment if needed in your programming language - Join segments back with a '/' @@ -411,7 +411,7 @@ To parse a ``purl`` string in its components: - Discard any empty segment from that split - Percent-decode each segment - - UTF-8-decode the each segment if needed in your programming + - UTF-8-decode each segment if needed in your programming language - Apply type-specific normalization to each segment if needed - Join segments back with a '/' @@ -433,7 +433,7 @@ identification to ensure that a ``purl`` stays compact and readable in most case Additional, separate external attributes stored outside of a ``purl`` are the preferred mechanism to convey extra long and optional information such as a -download URL, vcs URL or checksums in an API, database or web form. +download URL, VCS URL or checksums in an API, database or web form. With this warning, the known ``key`` and ``value`` defined here are valid for use in From 6cafcec720f7a9822564af75d41476bdf5aca8c5 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 8 Nov 2024 08:58:10 +0000 Subject: [PATCH 14/24] Rubygems -> RubyGems - archlinux -> Arch Linux Signed-off-by: Arthit Suriyawongkul --- VERSION-RANGE-SPEC.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index 31c6dfb..b53ed5c 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -59,9 +59,9 @@ conventions in use: - ``semver`` https://semver.org/ is a popular specification to structure version strings, but does not provide a way to express version ranges. -- Rubygems strongly suggest using ``semver`` for version but does not enforce it. +- RubyGems strongly suggest using ``semver`` for version but does not enforce it. As a result some gem use semver while several popular package do not use - strict semver. Rubygems use their own notation for version ranges which + strict semver. RubyGems use their own notation for version ranges which looks like the ``node-semver`` notation with some subtle differences. See https://guides.rubygems.org/patterns/#semantic-versioning @@ -142,7 +142,7 @@ related topic: - For instance, ``semver`` is a prominent specification in this domain but this is just one of the many ways to structure a version string. -- Debian, RPM, PyPI, Rubygems, and Composer have their own subtly different +- Debian, RPM, PyPI, RubyGems, and Composer have their own subtly different approach on how to determine how two versions are compared as equal, greater or lesser. @@ -260,7 +260,7 @@ Note how the constraints are sorted: - ``vers:tomee/>=7.1.0|<=7.1.2`` - ``vers:tomee/>=8.0.0-M1|<=8.0.1`` -Conversing Rubygems custom syntax for dependency on gem. Note how the +Conversing RubyGems custom syntax for dependency on gem. Note how the pessimistic version constraint is expanded: - ``'library', '~> 2.2.0', '!= 2.2.1'`` @@ -603,9 +603,9 @@ These are a few known versioning schemes for some common Package URL Debian uses these comparators: <<, <=, =, >= and >>. - **rpm**: RPM distros https://rpm-software-management.github.io/rpm/manual/dependencies.html - The a simplified rmpvercmp version comparison routine is used by archlinux Pacman. + The a simplified rmpvercmp version comparison routine is used by Arch Linux Pacman. -- **gem**: Rubygems https://guides.rubygems.org/patterns/#semantic-versioning +- **gem**: RubyGems https://guides.rubygems.org/patterns/#semantic-versioning which is similar to ``node-semver`` for its syntax, but does not use semver versions. @@ -692,7 +692,7 @@ Why not reuse existing version range notations? Most existing version range notations are tied to a specific version string syntax and are therefore not readily applicable to other contexts. For example, -the use of elements such as tilde and caret ranges in Rubygems, npm or Dart +the use of elements such as tilde and caret ranges in RubyGems, npm or Dart notations implies that a certain structure exists in the version string (semver or semver- like). The inclusion of these additional comparators is a result of the history and evolution in a given package ecosystem to address specific needs. @@ -900,14 +900,14 @@ aspects specific to the versions used only in the Python ecosystem. difficult to express without an "OR" logic. -Why not use Rubygems requirements notation? +Why not use RubyGems requirements notation? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See: - https://guides.rubygems.org/patterns/#declaring-dependencies -The Rubygems specification suggests but does not enforce using semver. It uses +The RubyGems specification suggests but does not enforce using semver. It uses operators similar to the ``node-semver`` spec with the different of the "~>" aka. pessimistic operator vs. a plain "~" tilde used in node-semver. This operator implies some semver-like versioning, yet gem version are not strictly From 61fad6e7519c296269f2b470869ef54310a1ee02 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 8 Nov 2024 08:59:03 +0000 Subject: [PATCH 15/24] Fix typos Signed-off-by: Arthit Suriyawongkul --- PURL-TYPES.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 2e8086d..7fbd4f6 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -172,7 +172,7 @@ cpan ---- ``cpan`` for CPAN Perl packages: -- The default respository is ``https://www.cpan.org/``. +- The default repository is ``https://www.cpan.org/``. - The ``namespace``: - To refer to a CPAN distribution name, the ``namespace`` MUST be present. In this case, the namespace is the CPAN id of the author/publisher. It MUST be written uppercase, followed by the distribution name in the ``name`` component. A distribution name may NEVER contain the string ``::``. - To refer to a CPAN module, the ``namespace`` MUST be absent. The module name MAY contain zero or more ``::`` strings, and the module name MUST NOT contain a ``-`` @@ -182,7 +182,7 @@ cpan - Optional qualifiers may include: - ``repository_url``: CPAN/MetaCPAN/BackPAN/DarkPAN repository base URL (default is ``https://www.cpan.org``) - - ``download_url``: URL of package or distibution + - ``download_url``: URL of package or distribution - ``vcs_url``: extra URL for a package version control system - ``ext``: file extension (default is ``tar.gz``) @@ -252,7 +252,7 @@ docker gem --- -``gem`` for Rubygems: +``gem`` for RubyGems: - The default repository is ``https://rubygems.org``. - The ``platform`` qualifiers key is used to specify an alternative platform. @@ -374,7 +374,7 @@ luarocks The full version number is required to uniquely identify a version. - Qualifier ``repository_url``: The LuaRocks rocks server to be used; useful in case a private server is used (optional). - If ommitted, ``https://luarocks.org`` as default server is assumed. + If omitted, ``https://luarocks.org`` as default server is assumed. Examples:: From 0390d117300e53533daabfea01fd15113e2f3981 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 8 Nov 2024 09:01:28 +0000 Subject: [PATCH 16/24] Update PURL-SPECIFICATION.rst Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 7b2a802..08a635a 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -104,7 +104,7 @@ A ``purl`` is a URL - Version control system (VCS) URLs such ``git://``, ``svn://``, ``hg://`` or as defined in Python pip or SPDX download locations are NOT valid ``purl`` types. They are valid URL or URI schemes but they are not ``purl``. - They are a closely related, compact and uniform way to reference VCS URLs. + They are a closely related, compact and uniform way to reference vcs URLs. They may be used as references in separate attributes outside of a ``purl`` or in a ``purl`` qualifier. @@ -150,7 +150,7 @@ The rules for each component are: - The package ``type`` is composed only of ASCII letters and numbers, '.', '+' and '-' (period, plus, and dash) - The ``type`` cannot start with a number - - The ``type`` cannot contain spaces + - The ``type`` cannot contains spaces - The ``type`` must NOT be percent-encoded - The ``type`` is case insensitive. The canonical form is lowercase @@ -209,7 +209,7 @@ The rules for each component are: - A ``key`` cannot start with a number - A ``key`` must NOT be percent-encoded - A ``key`` is case insensitive. The canonical form is lowercase - - A ``key`` cannot contain spaces + - A ``key`` cannot contains spaces - A ``value`` must be a percent-encoded string - The '=' separator is neither part of the ``key`` nor of the ``value`` @@ -281,7 +281,7 @@ To build a ``purl`` string from its components: - Start a ``purl`` string with the "pkg:" ``scheme`` as a lowercase ASCII string -- Append the ``type`` string to the ``purl`` as a lowercase ASCII string +- Append the ``type`` string to the ``purl`` as a lowercase ASCII string - Append '/' to the ``purl`` @@ -318,15 +318,15 @@ To build a ``purl`` string from its components: - Append '?' to the ``purl`` - Build a list from all key/value pair: - - Discard any pair where the ``value`` is empty. + - discard any pair where the ``value`` is empty. - UTF-8-encode each ``value`` if needed in your programming language - If the ``key`` is ``checksums`` and this is a list of ``checksums`` join this list with a ',' to create this qualifier ``value`` - - Create a string by joining the lowercased ``key``, the equal '=' sign and + - create a string by joining the lowercased ``key``, the equal '=' sign and the percent-encoded ``value`` to create a qualifier - - Sort this list of qualifier strings lexicographically - - Join this list of qualifier strings with a '&' ampersand + - sort this list of qualifier strings lexicographically + - join this list of qualifier strings with a '&' ampersand - Append this string to the ``purl`` - If the ``subpath`` is not empty and not composed only of empty, '.' and '..' @@ -359,7 +359,7 @@ To parse a ``purl`` string in its components: - Strip the right side from leading and trailing '/' - Split this on '/' - Discard any empty string segment from that split - - Discard any '.' or '..' segment from that split + - Discard any '.' or '..' segment from that split - Percent-decode each segment - UTF-8-decode each segment if needed in your programming language - Join segments back with a '/' @@ -411,7 +411,7 @@ To parse a ``purl`` string in its components: - Discard any empty segment from that split - Percent-decode each segment - - UTF-8-decode each segment if needed in your programming + - UTF-8-decode the each segment if needed in your programming language - Apply type-specific normalization to each segment if needed - Join segments back with a '/' @@ -433,7 +433,7 @@ identification to ensure that a ``purl`` stays compact and readable in most case Additional, separate external attributes stored outside of a ``purl`` are the preferred mechanism to convey extra long and optional information such as a -download URL, VCS URL or checksums in an API, database or web form. +download URL, vcs URL or checksums in an API, database or web form. With this warning, the known ``key`` and ``value`` defined here are valid for use in From 54856ee38a458b6194968a709b0ba0c215bbfdfc Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 8 Nov 2024 09:05:12 +0000 Subject: [PATCH 17/24] cannot contains -> cannot contain Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 08a635a..09a8d22 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -104,7 +104,7 @@ A ``purl`` is a URL - Version control system (VCS) URLs such ``git://``, ``svn://``, ``hg://`` or as defined in Python pip or SPDX download locations are NOT valid ``purl`` types. They are valid URL or URI schemes but they are not ``purl``. - They are a closely related, compact and uniform way to reference vcs URLs. + They are a closely related, compact and uniform way to reference VCS URLs. They may be used as references in separate attributes outside of a ``purl`` or in a ``purl`` qualifier. @@ -150,7 +150,7 @@ The rules for each component are: - The package ``type`` is composed only of ASCII letters and numbers, '.', '+' and '-' (period, plus, and dash) - The ``type`` cannot start with a number - - The ``type`` cannot contains spaces + - The ``type`` cannot contain spaces - The ``type`` must NOT be percent-encoded - The ``type`` is case insensitive. The canonical form is lowercase @@ -209,7 +209,7 @@ The rules for each component are: - A ``key`` cannot start with a number - A ``key`` must NOT be percent-encoded - A ``key`` is case insensitive. The canonical form is lowercase - - A ``key`` cannot contains spaces + - A ``key`` cannot contain spaces - A ``value`` must be a percent-encoded string - The '=' separator is neither part of the ``key`` nor of the ``value`` @@ -281,7 +281,7 @@ To build a ``purl`` string from its components: - Start a ``purl`` string with the "pkg:" ``scheme`` as a lowercase ASCII string -- Append the ``type`` string to the ``purl`` as a lowercase ASCII string +- Append the ``type`` string to the ``purl`` as a lowercase ASCII string - Append '/' to the ``purl`` @@ -318,15 +318,15 @@ To build a ``purl`` string from its components: - Append '?' to the ``purl`` - Build a list from all key/value pair: - - discard any pair where the ``value`` is empty. + - Discard any pair where the ``value`` is empty. - UTF-8-encode each ``value`` if needed in your programming language - If the ``key`` is ``checksums`` and this is a list of ``checksums`` join this list with a ',' to create this qualifier ``value`` - - create a string by joining the lowercased ``key``, the equal '=' sign and + - Create a string by joining the lowercased ``key``, the equal '=' sign and the percent-encoded ``value`` to create a qualifier - - sort this list of qualifier strings lexicographically - - join this list of qualifier strings with a '&' ampersand + - Sort this list of qualifier strings lexicographically + - Join this list of qualifier strings with a '&' ampersand - Append this string to the ``purl`` - If the ``subpath`` is not empty and not composed only of empty, '.' and '..' @@ -359,7 +359,7 @@ To parse a ``purl`` string in its components: - Strip the right side from leading and trailing '/' - Split this on '/' - Discard any empty string segment from that split - - Discard any '.' or '..' segment from that split + - Discard any '.' or '..' segment from that split - Percent-decode each segment - UTF-8-decode each segment if needed in your programming language - Join segments back with a '/' @@ -433,14 +433,14 @@ identification to ensure that a ``purl`` stays compact and readable in most case Additional, separate external attributes stored outside of a ``purl`` are the preferred mechanism to convey extra long and optional information such as a -download URL, vcs URL or checksums in an API, database or web form. +download URL, VCS URL or checksums in an API, database or web form. With this warning, the known ``key`` and ``value`` defined here are valid for use in all package types: - ``repository_url`` is an extra URL for an alternative, non-default package - repository or registry. When a package does not come from the default public + repository or registry. When a package does not come from the default public package repository for its ``type`` a ``purl`` may be qualified with this extra URL. The default repository or registry of a ``type`` is documented in the "Known ``purl`` types" section. From e77675e909c6733f26f905fbb4c2edefccce0f89 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 8 Nov 2024 09:08:50 +0000 Subject: [PATCH 18/24] decode the each -> decode each Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 09a8d22..3ec1bc6 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -411,7 +411,7 @@ To parse a ``purl`` string in its components: - Discard any empty segment from that split - Percent-decode each segment - - UTF-8-decode the each segment if needed in your programming + - UTF-8-decode each segment if needed in your programming language - Apply type-specific normalization to each segment if needed - Join segments back with a '/' From c4b001ca35f1ba002b9e55b63db21e86b947c6c9 Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 8 Nov 2024 09:13:55 +0000 Subject: [PATCH 19/24] programing -> programming Signed-off-by: Arthit Suriyawongkul --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index d520a5c..84a0c16 100644 --- a/README.rst +++ b/README.rst @@ -56,7 +56,7 @@ A `purl` or package URL is an attempt to standardize existing approaches to reliably identify and locate software packages. A `purl` is a URL string used to identify and locate a software package in a -mostly universal and uniform way across programing languages, package managers, +mostly universal and uniform way across programming languages, package managers, packaging conventions, tools, APIs and databases. Such a package URL is useful to reliably reference the same software package From db9abce56106273eb4481bd9f227f3de18ee146d Mon Sep 17 00:00:00 2001 From: Arthit Suriyawongkul Date: Fri, 8 Nov 2024 09:17:58 +0000 Subject: [PATCH 20/24] Make line 414 the same as line 364 Signed-off-by: Arthit Suriyawongkul --- PURL-SPECIFICATION.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/PURL-SPECIFICATION.rst b/PURL-SPECIFICATION.rst index 3ec1bc6..ef28d4c 100644 --- a/PURL-SPECIFICATION.rst +++ b/PURL-SPECIFICATION.rst @@ -411,8 +411,7 @@ To parse a ``purl`` string in its components: - Discard any empty segment from that split - Percent-decode each segment - - UTF-8-decode each segment if needed in your programming - language + - UTF-8-decode each segment if needed in your programming language - Apply type-specific normalization to each segment if needed - Join segments back with a '/' - This is the ``namespace`` From ec6768e9940ea361331a596d4c700724990cfcc1 Mon Sep 17 00:00:00 2001 From: Mark Lodato Date: Fri, 15 Nov 2024 10:55:33 -0500 Subject: [PATCH 21/24] pypi: switch to standard file_name, add links docs - Use the standard `file_name` qualifier, not `filename`. - Link to the Python Packaging User Guide for filename conventions. Thanks to @pombredanne for the suggestions. Signed-off-by: Mark Lodato --- PURL-TYPES.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index f4292cf..85c6e99 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -519,10 +519,15 @@ pypi - PyPI treats ``-`` and ``_`` as the same character and is not case sensitive. Therefore a PyPI package ``name`` must be lowercased and underscore ``_`` replaced with a dash ``-``. -- The ``filename`` qualifier selects a particular distribution file (case-sensitive). +- The ``file_name`` qualifier selects a particular distribution file + (case-sensitive). For naming convention, see the Python Packaging User Guide on + `source distributions `_, + `binary distributions `_, + and `platform compatibility tags `_. - Examples:: pkg:pypi/django@1.11.1 + pkg:pypi/django@1.11.1?filename=Django-1.11.1.tar.gz pkg:pypi/django@1.11.1?filename=Django-1.11.1-py2.py3-none-any.whl pkg:pypi/django-allauth@12.23 From 2997e875f6e057e69c6f55e9c31fc036b856c214 Mon Sep 17 00:00:00 2001 From: Maximilian Huber Date: Tue, 12 Jul 2022 13:41:34 +0200 Subject: [PATCH 22/24] Revert "Fix missing percent-encoding in purl example with repository_url" This reverts commit 37626c43ace346f38f390f9266ef99eef654bf66. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 84a0c16..b4d483d 100644 --- a/README.rst +++ b/README.rst @@ -124,7 +124,7 @@ Some `purl` examples pkg:golang/google.golang.org/genproto#googleapis/api/annotations pkg:maven/org.apache.xmlgraphics/batik-anim@1.9.1?packaging=sources - pkg:maven/org.apache.xmlgraphics/batik-anim@1.9.1?repository_url=repo.spring.io%2Frelease + pkg:maven/org.apache.xmlgraphics/batik-anim@1.9.1?repository_url=repo.spring.io/release pkg:npm/%40angular/animation@12.3.1 pkg:npm/foobar@12.3.1 From 0ea062fcf33aec779730906065caf7d8736d9f6d Mon Sep 17 00:00:00 2001 From: Sebastian Schuberth Date: Fri, 22 Nov 2024 10:49:59 +0100 Subject: [PATCH 23/24] README: Sort the list of adopters alphabetically Do not imply importance by order. Signed-off-by: Sebastian Schuberth --- README.rst | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index b4d483d..e8886c7 100644 --- a/README.rst +++ b/README.rst @@ -170,24 +170,25 @@ Known implementations - in Swift: https://github.com/package-url/packageurl-swift -Users, adopters and links -~~~~~~~~~~~~~~~~~~~~~~~~~ +Users, adopters and links (alphabetical order) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- `CycloneDX `_: A lightweight software + bill-of-material (SBOM) specification - `GitHub Dependency Submission API `_: allows third-party tools to submit dependency data to GitHub for inclusion in a repository's dependency graph. -- `Scancode Toolkit `_: Reports - `purl` from parsed package manifests using https://github.com/package-url/packageurl-python -- `OWASP Dependency-Track `_: +- `OWASP Dependency-Track `_: Open source component analysis platform -- `CycloneDX `_: A lightweight software - bill-of-material (SBOM) specification -- `SPDX `_: A data exchange standard for human-readable and - machine-processable software bill-of-materials (SBOM) - `OSS Index `_: A free catalog of Open Source Components and scanning tools to help developers identify vulnerable components -- `Sonatype Nexus Lifecycle `_: - Enterprise grade Open Source component management - `OSV Schema `_ and `OSV.dev `_: Open Source Vulnerability Schema and distributed vulnerability database +- `Scancode Toolkit `_: Reports + `purl` from parsed package manifests using https://github.com/package-url/packageurl-python +- `Sonatype Nexus Lifecycle `_: + Enterprise grade Open Source component management +- `SPDX `_: A data exchange standard for human-readable and + machine-processable software bill-of-materials (SBOM) License ~~~~~~~ From 1951d217bde29590a73f075db4ab71cc00011459 Mon Sep 17 00:00:00 2001 From: Sebastian Schuberth Date: Fri, 22 Nov 2024 10:47:19 +0100 Subject: [PATCH 24/24] README: Strip "for" / "in" prefixes for known implementations Make this list a bit more compact and readable. Signed-off-by: Sebastian Schuberth --- README.rst | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index e8886c7..222a0f2 100644 --- a/README.rst +++ b/README.rst @@ -156,18 +156,18 @@ type definitions: Known implementations ~~~~~~~~~~~~~~~~~~~~~ -- for .NET: https://github.com/package-url/packageurl-dotnet -- in Elixir: https://github.com/maennchen/purl -- in Go: https://github.com/package-url/packageurl-go -- in Java: https://github.com/package-url/packageurl-java, +- .NET: https://github.com/package-url/packageurl-dotnet +- Elixir: https://github.com/maennchen/purl +- Go: https://github.com/package-url/packageurl-go +- Java: https://github.com/package-url/packageurl-java, https://github.com/sonatype/package-url-java -- in JavaScript: https://github.com/package-url/packageurl-js -- in Perl: https://github.com/giterlizzi/perl-URI-PackageURL -- in PHP: https://github.com/package-url/packageurl-php -- in Python: https://github.com/package-url/packageurl-python -- in Ruby: https://github.com/package-url/packageurl-ruby -- in Rust: https://github.com/package-url/packageurl.rs -- in Swift: https://github.com/package-url/packageurl-swift +- JavaScript: https://github.com/package-url/packageurl-js +- Perl: https://github.com/giterlizzi/perl-URI-PackageURL +- PHP: https://github.com/package-url/packageurl-php +- Python: https://github.com/package-url/packageurl-python +- Ruby: https://github.com/package-url/packageurl-ruby +- Rust: https://github.com/package-url/packageurl.rs +- Swift: https://github.com/package-url/packageurl-swift Users, adopters and links (alphabetical order)