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