Merge pull request package-url#589 from package-url/581-rename-rst-to-md

Rename PURL-SPECIFICATION.rst to md package-url#581

Author: pombredanne

docs/how-to-build.md

@@ -0,0 +1,72 @@
+## How to build a `purl` string from its components
+
+Building a `purl` ASCII string works from left to right, from `type` to
+`subpath`.
+
+Note: some extra type-specific normalizations are required.
+See the "Registered types section" for details.
+
+To build a `purl` string from its components:
+
+
+- Start a `purl` string with the "pkg:" `scheme` as a lowercase ASCII string
+
+- Append the `type` string to the `purl` as an unencoded lowercase ASCII string
+
+  - Append '/' to the `purl`
+
+- If the `namespace` is not empty:
+
+  - Strip the `namespace` from leading and trailing '/'
+  - Split on '/' as segments
+  - Apply type-specific normalization to each segment if needed
+  - UTF-8-encode each segment if needed in your programming language
+  - Percent-encode each segment
+  - Join the segments with '/'
+  - Append this to the `purl`
+  - Append '/' to the `purl`
+  - Strip the `name` from leading and trailing '/'
+  - Apply type-specific normalization to the `name` if needed
+  - UTF-8-encode the `name` if needed in your programming language
+  - Append the percent-encoded `name` to the `purl`
+
+- If the `namespace` is empty:
+
+  - Apply type-specific normalization to the `name` if needed
+  - UTF-8-encode the `name` if needed in your programming language
+  - Append the percent-encoded `name` to the `purl`
+
+- If the `version` is not empty:
+
+  - Append '@' to the `purl`
+  - UTF-8-encode the `version` if needed in your programming language
+  - Append the percent-encoded version to the `purl`
+
+- If the `qualifiers` are not empty and not composed only of key/value pairs
+  where the `value` is empty:
+
+  - Append '?' to the `purl`
+  - Build a list from all key/value pair:
+
+    - Discard any pair where the `value` is empty.
+    - UTF-8-encode each `value` if needed in your programming language
+    - If the `key` is `checksum` and this is a list of checksums join this
+      list with a ',' to create this qualifier `value`
+    - Create a string by joining the lowercased `key`, the equal '=' sign and
+      the percent-encoded `value` to create a qualifier
+
+  - Sort this list of qualifier strings lexicographically
+  - Join this list of qualifier strings with a '&' ampersand
+  - Append this string to the `purl`
+
+- If the `subpath` is not empty and not composed only of empty, '.' and '..'
+  segments:
+
+  - Append '#' to the `purl`
+  - Strip the `subpath` from leading and trailing '/'
+  - Split this on '/' as segments
+  - Discard empty, '.' and '..' segments
+  - Percent-encode each segment
+  - UTF-8-encode each segment if needed in your programming language
+  - Join the segments with '/'
+  - Append this to the `purl`

docs/how-to-parse.md

@@ -0,0 +1,77 @@
+## How to parse a `purl` string into its components
+
+Parsing a `purl` ASCII string into its components works from right to left,
+from `subpath` to `type`.
+
+Note: some extra type-specific normalizations are required.
+See the "Registered types section" for details.
+
+To parse a `purl` string in its components:
+
+- Split the `purl` string once from right on '#'
+
+  - The left side is the `remainder`
+  - Strip the right side from leading and trailing '/'
+  - Split this on '/'
+  - Discard any empty string segment from that split
+  - Percent-decode each segment
+  - Discard any '.' or '..' segment from that split
+  - UTF-8-decode each segment if needed in your programming language
+  - Join segments back with a '/'
+  - This is the `subpath`
+
+- Split the `remainder` once from right on '?'
+
+  - The left side is the `remainder`
+  - The right side is the `qualifiers` string
+  - Split the `qualifiers` on '&'. Each part is a `key=value` pair
+  - For each pair, split the `key=value` once from left on '=':
+
+    - The `key` is the lowercase left side
+    - The `value` is the percent-decoded right side
+    - UTF-8-decode the `value` if needed in your programming language
+    - Discard any key/value pairs where the value is empty
+    - If the `key` is `checksum`, split the `value` on ',' to create
+      a list of checksums
+
+  - This list of key/value is the `qualifiers` object
+
+- Split the `remainder` once from left on ':'
+
+  - The left side lowercased is the `scheme`
+  - The right side is the `remainder`
+
+- Strip all leading and trailing '/' characters (e.g., '/', '//', '///' and
+  so on) from the `remainder`
+
+  - Split this once from left on '/'
+  - The left side lowercased is the `type`
+  - The right side is the `remainder`
+
+- Split the `remainder` once from right on '@'
+
+  - The left side is the `remainder`
+  - Percent-decode the right side. This is the `version`.
+  - UTF-8-decode the `version` if needed in your programming language
+  - This is the `version`
+
+- 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
+  - Apply type-specific normalization to each segment if needed
+  - Join segments back with a '/'
+  - This is the `namespace`

docs/known-qualifiers.md

@@ -0,0 +1,45 @@
+## Known `purl` `qualifiers` key/value pairs
+
+Note: Do not abuse `qualifiers`: it can be tempting to use many qualifier
+keys but their usage should be limited to the bare minimum for proper package
+identification to ensure that a `purl` stays compact and readable in most cases.
+
+Additional, separate external attributes stored outside of a `purl` are the
+preferred mechanism to convey extra long and optional information such as a
+download URL, VCS URL or checksums in an API, database or web form.
+
+With this warning, the known `key` and `value` defined here are valid for use in
+all package types:
+
+- `vers` allows the specification of a version range.
+  The value MUST adhere to the `Version Range Specification`.
+  This qualifier is mutually exclusive with the `version` component.
+  For example:
+
+    pkg:pypi/django?vers=vers:pypi%2F%3E%3D1.11.0%7C%21%3D1.11.1%7C%3C2.0.0
+
+- `repository_url` is an extra URL for an alternative, non-default package
+  repository or registry. When a package does not come from the default public
+  package repository for its `type` a `purl` may be qualified with this extra
+  URL. The default repository or registry of a `type` is documented in the
+  "Registered `purl` types" section.
+
+- `download_url` is an extra URL for a direct package web download URL to
+  optionally qualify a `purl`.
+
+- `vcs_url` is an extra URL for a package version control system URL to
+  optionally qualify a `purl`. The syntax for this URL should be as defined in
+  Python pip or the SPDX specification. See
+  https://github.com/spdx/spdx-spec/blob/cfa1b9d08903/chapters/3-package-information.md#37-package-download-location
+
+  - TODO: incorporate the details from SPDX here.
+
+- `file_name` is an extra file name of a package archive.
+
+- `checksum` is a qualifier for one or more checksums stored as a
+  comma-separated list. Each item in the `value` is in form of
+  `lowercase_algorithm:hex_encoded_lowercase_value` such as
+  `sha1:ad9503c3e994a4f611a4892f2e67ac82df727086`.
+  For example (with checksums truncated for brevity):
+
+    checksum=sha1:ad9503c3e994a4f,sha256:41bf9088b3a1e6c1ef1d

docs/purl-spec-toc.md

@@ -0,0 +1,25 @@
+# Package-URL Specification
+
+The Package URL core specification defines a versioned and formalized format,
+syntax, and rules used to represent and validate `purl`.
+
+A `purl` or package URL is an attempt to standardize existing approaches to
+reliably identify and locate software packages.
+
+A `purl` is a URL string used to identify and locate a software package in a
+mostly universal and uniform way across programming languages, package managers,
+packaging conventions, tools, APIs and databases.
+
+A `purl` is useful to reliably reference the same software package
+using a simple and expressive syntax and conventions based on familiar URLs.
+
+
+The Package-URL specification is organized in these documents:
+
+- What is `purl` aka. package URL? -- https://github.com/package-url/purl-spec/blob/docs/standard/summary.md
+- Rules for each `purl` component -- https://github.com/package-url/purl-spec/blob/docs/standard/components.md
+- Character encoding -- https://github.com/package-url/purl-spec/blob/docs/standard/characters-and-encoding.md
+- How to build a `purl` string from its components -- https://github.com/package-url/purl-spec/blob/docs/how-to-build.md
+- How to parse a `purl` string into its components -- https://github.com/package-url/purl-spec/blob/docs/how-to-parse.md
+- Known `purl` `qualifiers` key/value pairs -- https://github.com/package-url/purl-spec/blob/docs/known-qualifiers.md
+- Tests -- https://github.com/package-url/purl-spec/blob/docs/tests.md

docs/standard/about.md

@@ -0,0 +1,23 @@
+# About this Specification
+
+The document at [https://tc54.org/ecmaXXX/](https://tc54.org/ecmaXXX/) is the most accurate and up-to-date Package-URL specification.
+
+This document is available as [a single page](https://ecma-tc54.github.io/ECMA-xxx-PURL/) and as [multiple pages](https://ecma-tc54.github.io/ECMA-xxx-PURL/multipage/).
+
+# Contributing to this Specification
+
+This specification is developed on GitHub with the help of the Package-URL community. There are a number of ways to contribute to the development of this specification:
+
+* GitHub Repository: [https://github.com/Ecma-TC54/ECMA-xxx-PURL](https://github.com/Ecma-TC54/ECMA-xxx-PURL)
+* Issues: [All Issues](https://github.com/Ecma-TC54/ECMA-xxx-PURL/issues), [File a New Issue](https://github.com/Ecma-TC54/ECMA-xxx-PURL/issues/new)
+* Pull Requests: [All Pull Requests](https://github.com/Ecma-TC54/ECMA-xxx-PURL/pulls), [Create a New Pull Request](https://github.com/Ecma-TC54/ECMA-xxx-PURL/pulls/new)
+* Editors:
+  * [John Horan](mailto:jmhoran@aboutcode.org)
+  * [Michael Herzog](mailto:mjherzog@aboutcode.org)
+  * [Philippe Ombredanne](mailto:pombredanne@aboutcode.org)
+  * [Steve Springett](mailto:steve.springett@owasp.org)
+* Community:
+  * Chat: [Slack Channel](https://cyclonedx.slack.com/archives/C06KTE3BWEB)
+
+Refer to the [colophon](https://ecma-tc54.github.io/ECMA-xxx-PURL/#sec-colophon) for more information on how this document is created.
+

docs/standard/characters-and-encoding.md

@@ -0,0 +1,64 @@
+## Permitted characters
+
+A canonical `purl` is composed of these permitted ASCII characters:
+
+- the Alphanumeric Characters: `A to Z`, `a to z`, `0 to 9`,
+- the Punctuation Characters: `.-_~` (period '.',
+  dash '-', underscore '_' and tilde '~'),
+- the Percent Character: `%` (percent sign '%'), and
+- the Separator Characters `:/@?=&#` (colon ':', slash '/', at sign '@',
+  question mark '?', equal sign '=', ampersand '&' and pound sign '#').
+
+
+## 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`
+- '/' (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`
+
+## 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
+
+- The following characters MUST NOT be percent-encoded:
+
+  - 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.
+
+- 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.
+
+## Case folding
+
+References to "lowercase" in this specification refer to the **culture-invariant**
+full case mapping defined in
+[Section 3.13.2 of the Unicode Standard](https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/#G34078).
+
+When applied to the ASCII character set, this operation converts uppercase
+Latin letters (`A to Z`) to their corresponding lowercase forms (`a to z`).
+All other ASCII characters remain unchanged.