You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: faq.rst
+55-22Lines changed: 55 additions & 22 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,19 +6,28 @@ Scheme
6
6
7
7
**QUESTION**: Can the ``scheme`` component be followed by a colon and two slashes, like a URI?
8
8
9
-
**ANSWER**: No. Since a ``purl`` never contains a URL Authority, its ``scheme`` should not be suffixed with double slash as in 'pkg://' and should use 'pkg:' instead. Otherwise this would be an invalid URI per RFC 3986 at https://tools.ietf.org/html/rfc3986#section-3.3::
9
+
**ANSWER**: No. Since a ``purl`` never contains a URL Authority, its ``scheme`` should not be
10
+
suffixed with double slash as in 'pkg://' and should use 'pkg:' instead. Otherwise this would be an
11
+
invalid URI per RFC 3986 at https://tools.ietf.org/html/rfc3986#section-3.3::
10
12
11
13
If a URI does not contain an authority component, then the path
12
14
cannot begin with two slash characters ("//").
13
15
14
-
This rule applies to all slash '/' characters between the ``scheme``'s colon separator and the ``type`` component, e.g., ':/', '://', ':///' et al.
16
+
This rule applies to all slash '/' characters between the ``scheme``'s colon separator and the
17
+
``type`` component, e.g., ':/', '://', ':///' et al.
15
18
16
-
In its canonical form, a ``purl`` must not use any such ':/' ``scheme`` suffix and may only use ':' as a ``scheme`` suffix. This means that:
19
+
In its canonical form, a ``purl`` must not use any such ':/' ``scheme`` suffix and may only use ':'
20
+
as a ``scheme`` suffix. This means that:
17
21
18
-
- ``purl`` parsers must accept URLs such as 'pkg://' and must ignore and remove all such '/' characters.
19
-
- ``purl`` builders should not create invalid URLs with one or more slash '/' characters between 'pkg:' and the ``type`` component.
22
+
- ``purl`` parsers must accept URLs such as 'pkg://' and must ignore and remove all such '/'
23
+
characters.
20
24
21
-
For example, although these two purls are strictly equivalent, the first is in canonical form, while the second -- with a '//' between 'pkg:' and the ``type`` 'gem' -- is an acceptable purl but is an invalid URI/URL per RFC 3986::
25
+
- ``purl`` builders should not create invalid URLs with one or more slash '/' characters between
26
+
'pkg:' and the ``type`` component.
27
+
28
+
For example, although these two purls are strictly equivalent, the first is in canonical form, while
29
+
the second -- with a '//' between 'pkg:' and the ``type`` 'gem' -- is an acceptable purl but is an
30
+
invalid URI/URL per RFC 3986::
22
31
23
32
pkg:gem/ruby-advisory-db-check@0.12.4
24
33
@@ -27,34 +36,58 @@ For example, although these two purls are strictly equivalent, the first is in c
27
36
28
37
**QUESTION**: Is the colon between ``scheme`` and ``type`` encoded? Can it be encoded? If yes, how?
29
38
30
-
**ANSWER**: The "Rules for each ``purl`` component" section provides that the ``scheme`` MUST be followed by an unencoded colon ':'.
39
+
**ANSWER**: The "Rules for each ``purl`` component" section provides that the ``scheme`` MUST be
40
+
followed by an unencoded colon ':'.
31
41
32
-
In this case, the colon ':' between ``scheme`` and ``type`` is being used as a separator, and consequently should be used as-is, never encoded and never requiring any decoding. Moreover, it should be a parsing error if the colon ':' does not come directly after 'pkg'. Tools are welcome to recover from this error to help with malformed purls, but that's not a requirement.
42
+
In this case, the colon ':' between ``scheme`` and ``type`` is being used as a separator, and
43
+
consequently should be used as-is, never encoded and never requiring any decoding. Moreover, it
44
+
should be a parsing error if the colon ':' does not come directly after 'pkg'. Tools are welcome to
45
+
recover from this error to help with malformed purls, but that's not a requirement.
33
46
34
47
35
48
Type
36
49
~~~~
37
50
38
-
**QUESTION**: What behavior is expected from a purl spec implementation if a
39
-
``type`` contains a character like a slash '/' or a colon ':'?
51
+
**QUESTION**: What behavior is expected from a purl spec implementation if a ``type`` contains a
52
+
character like a slash '/' or a colon ':'?
40
53
41
-
**ANSWER**: The "Rules for each purl component" section provides that the
42
-
package ``type``
54
+
**ANSWER**: The "Rules for each purl component" section provides that the package ``type`` that list
55
+
allowed characters:
43
56
44
-
MUST be composed only of ASCII letters and numbers, period '.', plus '+',
45
-
and dash '-'.
57
+
MUST be composed only of ASCII letters and numbers, period '.', and dash '-'.
46
58
47
-
As a result, a purl spec implementation must return an error when encountering
48
-
a ``type`` that contains a prohibited character.
59
+
As a result, a purl spec implementation must return an error when encountering a ``type`` that
60
+
contains a prohibited character.
49
61
50
62
51
63
Version
52
64
~~~~~~~
53
65
54
-
**QUESTION**: How do package ``types`` handle the comparison and sorting of
55
-
versions?
66
+
**QUESTION**: How do package ``types`` handle the comparison and sorting of versions?
67
+
68
+
**ANSWER**: Some package ``types`` use versioning conventions such as SemVer for NPMs or NEVRA
69
+
conventions for RPMS. A ``type`` may define a procedure to compare and sort versions, but there is
70
+
no reliable and uniform way to do such comparison consistently.
71
+
72
+
73
+
Plus
74
+
~~~~
75
+
76
+
**QUESTION**: Can a PURL contain a plus character '+'?
77
+
78
+
**ANSWER**: Decoded individual components can contain a plus. The encoded, canonical form can never
79
+
contain an unencoded plus.
80
+
81
+
82
+
Qualifiers
83
+
~~~~~~~~~~~
84
+
85
+
**QUESTION**: What is the qualifier for a checksum like a SHA1?
86
+
87
+
**ANSWER**: The spec was originally ambiguous and used ``checksum`` (singular) in one place and
88
+
``checksums`` (plural) in other places. This has been discussed extensively in issues and PRs such as
89
+
https://github.com/package-url/purl-spec/issues/73 and https://github.com/package-url/purl-
90
+
spec/pull/209 and the official form is ``checksum`` (singular). When writing a lenient parser,
91
+
consider accepting both ``checksum`` (singular) and ``checksums`` (plural) when reading a PURL, and
92
+
always emit ``checksum`` (singular) when writing a PURL.
56
93
57
-
**ANSWER**: Some package ``types`` use versioning conventions such as SemVer
58
-
for NPMs or NEVRA conventions for RPMS. A ``type`` may define a procedure to
59
-
compare and sort versions, but there is no reliable and uniform way to do such
0 commit comments