Clarify spec for version

[pombredanne]

We some key issues to tackle wrt. version encoding:

• Clarifications, in particular about version encoding #35 - Must space ' ' in a version be percent-encoded?
• Percent encoding spec and : and / #39 - Must ':' in a version be percent-encoded?
• test: character encoding #364 - Must ':' in a version (e.g., 'dockerimage@sha256:244f...') be percent-encoded?

And this PR:

• Add RFC 2119/8174 note and convert terms to uppercase as needed #373

---

just a site note: for version ranges, we have

• PURL add well-known qualifier vers #433

[pombredanne]

@mprpic This is yours since your volunteered. Do you want to join the project?

[mprpic]

@pombredanne Yes please.

[davidB]

Yes please clarify, because the doc says version is percent-encoded. But it's only for some characters => it's a pain, because if I always percent-encode the version before building the URL:

sha256:adf450ad2a44e7cf94a9ba15378ad66f3b906ebd88d541f980d3b3e2b33f2399 => sha256%3Aadf450ad2a44e7cf94a9ba15378ad66f3b906ebd88d541f980d3b3e2b33f2399 as expected

0.3.0 => 0%2E3%2E0 (ok for tag in query parameter by mismatch version in samples with ...@0.3.0)

UPDATE: encoding/decoding of the version should be simple and bijective to be able to build and parse purl in lot of programming language.

[matt-phylum]

The encoding is only supposed to be applied to characters that require encoding to be unambiguous in the position they are used in: https://github.com/package-url/purl-spec/blob/master/PURL-SPECIFICATION.rst#character-encoding It's suggested that plus signs are also encoded to avoid interoperability problems: #261

Unfortunately, there is a lot of confusion about percent encoding and x-www-form-urlencoded and RFC3986 reserved characters, all of which are distinct topics. Percent encoding is the mechanism of encoding, and does not specify which characters are to be encoded, although obviously you have to encode % itself or its meaning will change during decoding. Based on the results you're seeing, you're probably encoding all characters except ascii alphanumeric characters, which is valid and should be understood by any PURL implementation, but it's not the canonical form.

I think at some other time on another issue I suggested having explicit rules that clearly specify which characters are or are not expected to be encoded. WHATWG URL has a nice format where it defines different encode sets and then specifies the encode set to be used for the different parts of the URL: https://url.spec.whatwg.org/#percent-encoded-bytes

As far as I know, these sets are correct for PURL: https://github.com/phylum-dev/purl/blob/151168733f75a9802556e4b07eb577b9d99f7cea/purl/src/format.rs#L9-L27

[dwalluck]

The encoding is only supposed to be applied to characters that require encoding to be unambiguous in the position they are used in

But, the spec says to always encode '@', '?', '#' elsewhere, even though something like @angular as the name component isn't ambiguous, and using the Java standard class java.net.URI with that as the path does not seem to encode this character.

[matt-phylum]

The PURL pkg:generic/a@b@c does have a well defined expected parse result, but it may not be what you expect. pkg:npm/@angular/whatever@1.0.0 and pkg:npm/@angular/whatever differ by more than their versions.

java.net.URI would not encode it because it only has a special meaning to PURL.

[dwalluck]

java.net.URI would not encode it because it only has a special meaning to PURL.

What is causing the purl to encode the '@' in the name if it's not ambiguous there, only within the version fragment?

[matt-phylum]

The version is optional. If there's no version component then any unescaped @ in the name would change into the delimiter.

[dwalluck]

Thanks. I understand.