Update 'qualifiers' rule in core spec #382

PURL-SPECIFICATION.rst

@@ -176,25 +176,30 @@ The rules for each component are:
 
 - **qualifiers**:
 
-  - The ``qualifiers`` string is prefixed by a '?' separator when not empty
-  - This '?' is not part of the ``qualifiers``
-  - This is a query string composed of zero or more ``key=value`` pairs each
-    separated by a '&' ampersand. A ``key`` and ``value`` are separated by the equal
-    '=' character
-  - These '&' are not part of the ``key=value`` pairs.
-  - ``key`` must be unique within the keys of the ``qualifiers`` string
-  - ``value`` cannot be an empty string: a ``key=value`` pair with an empty ``value``
-    is the same as no key/value at all for this key
-  - For each pair of ``key`` = ``value``:
-
-    - The ``key`` must be composed only of ASCII letters and numbers, '.', '-' and
-      '_' (period, dash and underscore)
-    - 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 ``value`` must be a percent-encoded string
-    - The '=' separator is neither part of the ``key`` nor of the ``value``
+  - The ``qualifiers`` component MUST be prefixed by an unencoded question
+    mark '?' separator when not empty.  This '?' separator is not part of the
+    ``qualifiers`` component.
+  - The ``qualifiers`` component is a query string composed of one or more
+    ``key=value`` pairs.  Multiple ``key=value`` pairs MUST be separated by an
+    unencoded ampersand '&'.  This '&' separator is not part of the
+    ``qualifiers`` component.
+
+  - A ``key`` and ``value`` MUST be separated by the unencoded equal sign '='
+    character.  This '=' separator is not part of the ``key`` or ``value``.
+  - A ``value`` MUST NOT be an empty string: a ``key=value`` pair with an
+    empty ``value`` is the same as if no ``key=value`` pair exists for this
+    ``key``.
+
+  - For each ``key=value`` pair:
+
+    - The ``key`` MUST be composed only of lowercase ASCII letters and numbers,
+      period '.', dash '-' and underscore '_'.
+    - A ``key`` MUST start with an ASCII letter.
+    - A ``key`` MUST NOT be percent-encoded.
+    - Each ``key`` MUST be unique among all the keys of the ``qualifiers``
+      component.
+    - A ``value`` MAY be composed of any character and all characters MUST be
+      encoded as described in the "Character encoding" section.
 
 
 - **subpath**:
@@ -206,46 +211,62 @@ The rules for each component are:
     in the canonical form
   - Each ``subpath`` segment MUST be a percent-encoded string
   - When percent-decoded, a segment:
+
     - MUST NOT contain a '/'
     - MUST NOT be any of '..' or '.'
     - MUST NOT be empty
+
   - The ``subpath`` MUST be interpreted as relative to the root of the package
 
 
 Character encoding
 ~~~~~~~~~~~~~~~~~~
 
-For clarity and simplicity a ``purl`` is always an ASCII string. To ensure that
-there is no ambiguity when parsing a ``purl``, separator characters and non-ASCII
-characters must be UTF-encoded and then percent-encoded as defined at::
+Permitted characters
+--------------------
+
+A canonical ``purl`` is an ASCII string composed of these characters:
+
+- alphanumeric characters ``A to Z``, ``a to z``, ``0 to 9``,
+- the ``purl`` separators ``:/@?=&#`` (colon ':', slash '/', at sign '@',
+  question mark '?', equal sign '=', ampersand '&' and pound sign '#'), and
+- these punctuation marks ``%.-_~`` (percent sign '%', period '.', dash '-',
+  underscore '_' and tilde '~').
 
-    https://en.wikipedia.org/wiki/Percent-encoding
+All other characters MUST be encoded as UTF-8 and then percent-encoded.
+In addition, each component specifies its permitted characters and
+its percent-encoding rules.
 
-Use these rules for percent-encoding and decoding ``purl`` components:
 
-- the ``type`` must NOT be encoded and must NOT contain separators
+``purl`` separators
+-------------------
 
-- the '#', '?', '@' and ':' characters must NOT be encoded when used as
-  separators. They may need to be encoded elsewhere
+These ``purl`` separator characters MUST NOT be percent-encoded when used as
+``purl`` separators:
 
-- the ':' ``scheme`` and ``type`` separator does not need to and must NOT be encoded.
-  It is unambiguous unencoded everywhere
+- ':' (colon) is the separator between ``scheme`` and ``type``
+- '/' (slash) is the separator between ``type``, ``namespace`` and ``name``
+- '/' (slash) is the separator between ``subpath`` segments
+- '@' (at sign) is the separator between ``name`` and  ``version``
+- '?' (question mark) is the separator before ``qualifiers``
+- '=' (equals) is the separator between a ``key`` and a ``value`` of a
+  ``qualifier``
+- '&' (ampersand) is the separator between ``qualifiers`` (each being a
+  ``key=value`` pair)
+- '#' (number sign) is the separator before ``subpath``
 
-- the '/' used as ``type``/``namespace``/``name`` and ``subpath`` segments separator
-  does not need to and must NOT be percent-encoded. It is unambiguous unencoded
-  everywhere
 
-- the '@' ``version`` separator must be encoded as ``%40`` elsewhere
-- the '?' ``qualifiers`` separator must be encoded as ``%3F`` elsewhere
-- the '=' ``qualifiers`` key/value separator must NOT be encoded
-- the '#' ``subpath`` separator must be encoded as ``%23`` elsewhere
+Percent-encoding rules
+----------------------
 
-- All non-ASCII characters must be encoded as UTF-8 and then percent-encoded
+When applying percent-encoding or decoding to a string, use the rules of RFC
+3986 section 2 (https://datatracker.ietf.org/doc/html/rfc3986#section-2).
 
-It is OK to percent-encode ``purl`` components otherwise except for the ``type``.
-Parsers and builders must always percent-decode and percent-encode ``purl``
-components and component segments as explained in the "How to parse" and "How to
-build" sections.
+Each component defines when and how to apply percent-encoding and decoding to
+its content.
+
+When percent-encoding is required, all characters MUST be encoded except for
+the colon ':'.
 
 
 How to build ``purl`` string from its components
@@ -486,3 +507,12 @@ License
 ~~~~~~~
 
 This document is licensed under the MIT license
+
+Definitions
+~~~~~~~~~~~
+
+[ASCII]  See, e.g.,
+
+  - American National Standards Institute, "Coded Character Set -- 7-bit
+    American Standard Code for Information Interchange", ANSI X3.4, 1986.
+  - https://en.wikipedia.org/wiki/ASCII.

faq.rst

@@ -6,7 +6,7 @@ Scheme
 
 **QUESTION**: Can the ``scheme`` component be followed by a colon and two slashes, like a URI?
 
-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::
+**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::
 
     If a URI does not contain an authority component, then the path
     cannot begin with two slash characters ("//").
@@ -24,9 +24,10 @@ For example, although these two purls are strictly equivalent, the first is in c
 
     pkg://gem/[email protected]
 
+
 **QUESTION**: Is the colon between ``scheme`` and ``type`` encoded? Can it be encoded? If yes, how?
 
-The "Rules for each ``purl`` component" section provides that "[t]he ``scheme`` MUST be followed by an unencoded colon ':'.
+**ANSWER**: The "Rules for each ``purl`` component" section provides that the ``scheme`` MUST be followed by an unencoded colon ':'.
 
 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.
 
@@ -37,10 +38,11 @@ Type
 **QUESTION**: What behavior is expected from a purl spec implementation if a
 ``type`` contains a character like a slash '/' or a colon ':'?
 
-The "Rules for each purl component" section provides that
+**ANSWER**: The "Rules for each purl component" section provides that the
+package ``type``
 
-    [t]he package ``type`` MUST be composed only of ASCII letters and numbers,
-    '.', '+' and '-' (period, plus, and dash)
+    MUST be composed only of ASCII letters and numbers, '.', '+' and '-'
+    (period, plus, and dash).
 
 As a result, a purl spec implementation must return an error when encountering
 a ``type`` that contains a prohibited character.