Merge branch 'main' into main

Author: gmdavef

PURL-SPECIFICATION.rst

@@ -114,9 +114,11 @@ Rules for each ``purl`` component
 
 A ``purl`` string is an ASCII URL string composed of seven components.
 
-Some components are allowed to use other characters beyond ASCII: these
-components must then be UTF-8-encoded strings and percent-encoded as defined in
-the "Character encoding" section.
+Except as expressly stated otherwise in this section, each component:
+
+- MAY be composed of any of the characters defined in the "Permitted
+  characters" section
+- MUST be encoded as defined in the "Character encoding" section
 
 The rules for each component are:
 
@@ -140,38 +142,43 @@ The rules for each component are:
 
 - **namespace**:
 
-  - The optional ``namespace`` contains zero or more segments, separated by slash
-    '/'
-  - Leading and trailing slashes '/' are not significant and should be stripped
-    in the canonical form. They are not part of the ``namespace``
-  - Each ``namespace`` segment must be a percent-encoded string
+  - The ``namespace`` is optional, unless required by the package's ``type`` definition.
+  - If present, the ``namespace`` MAY contain one or more segments, separated
+    by a single unencoded slash '/' character.
+  - All leading and trailing slashes '/' are not significant and SHOULD be
+    stripped in the canonical form. They are not part of the ``namespace``.
+  - Each ``namespace`` segment MUST be a percent-encoded string.
   - When percent-decoded, a segment:
 
-    - must not contain a '/'
-    - must not be empty
+    - MUST NOT contain any slash '/' characters
+    - MUST NOT be empty
+    - MAY contain any Unicode character other than '/' unless the package's
+      ``type`` definition provides otherwise.
 
-  - A URL host or Authority must NOT be used as a ``namespace``. Use instead a
+  - A URL host or Authority MUST NOT be used as a ``namespace``. Use instead a
     ``repository_url`` qualifier. Note however that for some types, the
     ``namespace`` may look like a host.
 
 
 - **name**:
 
-  - The ``name`` is prefixed by a '/' separator when the ``namespace`` is not empty
-  - This '/' is not part of the ``name``
-  - A ``name`` must be a percent-encoded string
+  - The ``name`` is prefixed by a single slash '/' separator when the
+    ``namespace`` is not empty.
+  - All leading and trailing slashes '/' are not significant and SHOULD be
+    stripped in the canonical form. They are not part of the ``name``.
+  - A ``name`` MUST be a percent-encoded string.
+  - When percent-decoded, a ``name`` MAY contain any Unicode character unless
+    prohibited by the package's ``type`` definition in `<PURL-TYPES.rst>`_.
 
 
 - **version**:
 
-  - The ``version`` is prefixed by a '@' separator when not empty
-  - This '@' is not part of the ``version``
-  - 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``
-    may define a procedure to compare and sort versions, but there is no
-    reliable and uniform way to do such comparison consistently.
+  - The ``version`` is prefixed by a '@' separator when not empty.
+  - This '@' is not part of the ``version``.
+  - A ``version`` MUST be a percent-encoded string.
+  - When percent-decoded, a ``version`` MAY contain any Unicode character unless
+    the package's ``type`` definition provides otherwise.
+  - A ``version`` is a plain and opaque string.
 
 
 - **qualifiers**:
@@ -219,30 +226,24 @@ The rules for each component are:
   - The ``subpath`` MUST be interpreted as relative to the root of the package
 
 
-Character encoding
-~~~~~~~~~~~~~~~~~~
-
 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 '~').
+A canonical ``purl`` is composed of these permitted ASCII characters:
 
-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.
+- the Alphanumeric Characters: ``A to Z``, ``a to z``, ``0 to 9``,
+- the Punctuation Characters: ``.-_~`` (period '.',
+  dash '-', underscore '_' and tilde '~'),
+- the Plus Character: ``+`` (plus '+'),
+- the Percent Character: ``%`` (percent sign '%'), and
+- the Separator Characters ``:/@?=&#`` (colon ':', slash '/', at sign '@',
+  question mark '?', equal sign '=', ampersand '&' and pound sign '#').
 
 
 ``purl`` separators
--------------------
+~~~~~~~~~~~~~~~~~~~
 
-These ``purl`` separator characters MUST NOT be percent-encoded when used as
-``purl`` separators:
+This is how each of the Separator Characters is used:
 
 - ':' (colon) is the separator between ``scheme`` and ``type``
 - '/' (slash) is the separator between ``type``, ``namespace`` and ``name``
@@ -256,17 +257,34 @@ These ``purl`` separator characters MUST NOT be percent-encoded when used as
 - '#' (number sign) is the separator before ``subpath``
 
 
-Percent-encoding rules
-----------------------
+Character encoding
+~~~~~~~~~~~~~~~~~~
+
+- In the "Rules for each ``purl`` component" section, each component
+  defines when and how to apply percent-encoding and decoding to its content.
+- When percent-encoding is required by a component definition, the component
+  string MUST first be encoded as UTF-8.
+- In the component string, each "data octet" MUST be replaced by the
+  percent-encoded "character triplet" applying the percent-encoding mechanism
+  defined in RFC 3986 section 2.1 (https://datatracker.ietf.org/doc/html/rfc3986#section-2.1),
+  including the RFC definition of "data octet" and "character triplet",
+  and using these definitions for RFC's "allowed set" and "delimiters":
+
+  - "allowed set" is composed of the Alphanumeric Characters and the
+    Punctuation Characters
+  - "delimiters" is composed of the Separator Characters
 
-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).
+- The following characters MUST NOT be percent-encoded:
 
-Each component defines when and how to apply percent-encoding and decoding to
-its content.
+  - the Alphanumeric Characters,
+  - the Punctuation Characters,
+  - the Separator Characters when being used as ``purl`` separators,
+  - the colon ':', whether used as a Separator Character or otherwise, and
+  - the percent sign '%' when used to represent a percent-encoded character.
 
-When percent-encoding is required, all characters MUST be encoded except for
-the colon ':'.
+- Where the space ' ' is permitted, it MUST be percent-encoded as '%20'.
+- With the exception of the percent-encoding mechanism, the rules regarding
+  percent-encoding are defined by this specification alone.
 
 
 How to build ``purl`` string from its components
@@ -405,13 +423,17 @@ To parse a ``purl`` string in its components:
 - Split the ``remainder`` once from right on '/'
 
   - The left side is the ``remainder``
+  - Strip all leading characters (e.g., '/', '//' and so on)
+    from the right side
   - Percent-decode the right side. This is the ``name``
   - UTF-8-decode this ``name`` if needed in your programming language
   - Apply type-specific normalization to the ``name`` if needed
   - This is the ``name``
 
 - Split the ``remainder`` on '/'
 
+  - Strip all leading '/' characters (e.g., '/', '//' and so on)
+    from that split
   - Discard any empty segment from that split
   - Percent-decode each segment
   - UTF-8-decode each segment if needed in your programming language

faq.rst

@@ -46,3 +46,15 @@ package ``type``
 
 As a result, a purl spec implementation must return an error when encountering
 a ``type`` that contains a prohibited character.
+
+
+Version
+~~~~~~~
+
+**QUESTION**: How do package ``types`` handle the comparison and sorting of
+versions?
+
+**ANSWER**: Some package ``types`` use versioning 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.