Convert .rst files to .md package-url#581

johnmhoran · pombredanne · commit cfa4585e4321 · 2025-08-13T19:56:39.000+02:00
This matches the tree structure described in package-url#581 with a few extra. Summary and combined files are generated using pypandoc at purl-specification.md and purl-standard.md. Reference: package-url#581 Signed-off-by: John M. Horan <johnmhoran@gmail.com> Signed-off-by: Philippe Ombredanne <pombredanne@aboutcode.org>
diff --git a/docs/standard/about.md b/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.
+
diff --git a/docs/standard/conformance.md b/docs/standard/conformance.md
@@ -0,0 +1,34 @@
+# 2 Conformance
+
+## 2.1 Requirements Terminology
+
+In this standard, the words that are used to define the significance of each requirement are detailed below. These words are used in accordance with their definitions in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt), and their respective meanings are reproduced below:
+
+* Must: This word, or the adjective “required” and the auxiliary verb "shall", means that the item is an absolute requirement of the standard.
+* Should: This word, or the adjective “recommended”, means that there might exist valid reasons in particular circumstances to ignore this item, but the full implications should be understood and the case carefully weighed before making an implementation decision.
+* May: This word, or the adjective “optional”, means that this item is truly optional.
+
+The words "must not", "shall not", "should not", and "not recommended", are the negative forms of "must", "shall", "should", and "recommended", respectively. There is no negative form of "may".
+
+## 2.2 Implementation Conformance
+
+A conforming implementation of Package-URL (PURL) must fully implement and support all elements defined within this specification, including the syntax, components, and semantic requirements for constructing and interpreting valid PURLs.
+
+A conforming implementation of PURL must adhere to the syntax defined in this specification, ensuring that all PURLs are parsed, constructed, and validated according to the prescribed rules. The implementation must provide full support for ecosystem-agnostic behaviour, enabling PURLs to function consistently and reliably across diverse environments.
+
+All required components of a PURL, such as the scheme, type, and name, must be present and validated according to the rules defined in this specification. Additionally, optional components, including qualifiers and subpaths, must be handled appropriately if provided, in full compliance with their specified behaviours.
+
+Implementations must ensure that equivalent PURLs are consistently resolved to the same canonical representation. This includes strict adherence to normalisation and equivalence rules. Furthermore, implementations must process URI encoding and decoding for PURL components according to the standards outlined in RFC 3986.
+
+Invalid PURLs that fail to conform to the specification must be identified and rejected by any conforming implementation. This guarantees the integrity and reliability of PURLs in all supported contexts.
+
+A conforming implementation of PURL may extend its functionality by providing ecosystem-specific validation, processing, or metadata handling, as long as these extensions do not violate the core specification. Additionally, implementations may offer auxiliary tools or features, such as utilities for constructing or validating PURLs, provided they align with the standard's requirements.
+
+A conforming implementation must not redefine or alter the core syntax, components, or semantics defined by this specification. Any prohibited extensions explicitly identified in the specification must not be implemented. Furthermore, behaviours that compromise the interoperability of PURLs across tools, platforms, or ecosystems are strictly disallowed.
+
+A conforming implementation of Package-URL may choose to implement or not implement Normative Optional subclauses. If any Normative Optional behaviour is implemented, all of the behaviour in the containing Normative Optional clause must be implemented. A Normative Optional clause is denoted in this specification with the words "Normative Optional" in a coloured box, as shown below.
+
+## 2.3 Example Normative Optional Clause Heading
+
+Example clause contents.
+
diff --git a/docs/standard/header.md b/docs/standard/header.md
@@ -0,0 +1,10 @@
+<!--
+# PLEASE READ
+
+*This file is automatically generated from files found in purl-spec/docs/.
+It will be overwritten in future updates.*
+
+*Please do not submit a pull request to change this file - changes are only
+applied to the files located in purl-spec/docs.*
+
+-->
diff --git a/docs/standard/introduction.md b/docs/standard/introduction.md
@@ -0,0 +1,16 @@
+# Introduction
+
+Software ecosystems have evolved into highly interconnected networks of components, packages, and dependencies. Managing this complexity demands a robust, uniform mechanism to identify and track software packages across diverse ecosystems and tools. Package-URL (PURL) was developed to address this challenge by providing a simple, consistent, and flexible approach to identifying software packages with precision and clarity.
+
+PURL introduces a standardized URL-based syntax that uniquely identifies software packages, independent of their ecosystem or distribution channel. Unlike traditional identification methods, PURL embeds critical metadata directly into its structure, enabling efficient, accurate package identification at scale. This standardization ensures interoperability between tools and ecosystems, fostering greater collaboration and reducing ambiguity in software supply chain management.
+
+Challenges addressed by PURL:
+
+- **Ambiguity in Package Identification:** With diverse naming conventions across ecosystems, identifying software packages reliably has historically been a challenge. PURL eliminates this ambiguity by creating a universal identifier with a predictable structure.
+- **Cross-Ecosystem Interoperability:** Developers, organizations, and tools often work across multiple ecosystems, each with its own package management systems. PURL harmonizes these differences, enabling seamless interoperability.
+- **Enhanced Traceability and Risk Management:** In an era where supply chain security is critical, PURL provides the foundation for identifying and tracing packages to their origins, dependencies, and potential vulnerabilities.
+- **Tooling and Automation:** By standardizing package identification, PURL simplifies tooling development, automation, and integration for tasks such as software composition analysis, vulnerability management, and license compliance.
+
+As software supply chain security becomes a global priority, formalizing PURL as an international standard ensures its adoption and consistent implementation. Standardization under Ecma International Technical Committee 54 (TC54) positions PURL as a foundational building block for secure, transparent, and efficient software ecosystems worldwide.
+
+By enabling a universally recognized and implementable specification, PURL aligns with global efforts to improve the security, reliability, and accountability of software supply chains. Its adoption ensures that organizations and developers can rely on a common language to manage software packages across the diverse and rapidly evolving software landscape.
diff --git a/docs/standard/overview.md b/docs/standard/overview.md
@@ -0,0 +1,13 @@
+# 4 Overview
+
+This section contains a non-normative overview of the Package-URL specification.
+
+The Package-URL (PURL) specification defines a lightweight, universal syntax for identifying software packages. By leveraging a URL-based format, PURL provides a consistent and interoperable mechanism for referencing software packages across a wide range of ecosystems and tools. Its design addresses the challenges of ambiguity, inconsistency, and fragmentation in software package identification, enabling better interoperability and traceability in modern software supply chains.
+
+This specification focuses on the core aspects of PURL, including its syntax, required components, optional attributes, and conformance requirements. It does not cover ecosystem-specific types or extensions such as PURL Version Ranges (VERS). However, the flexibility of PURL allows it to be extended to meet the needs of diverse package ecosystems without compromising its universal applicability.
+
+The primary audience for this specification includes developers, tool implementers, and organisations involved in software composition analysis, dependency management, and supply chain security. PURL is foundational to a variety of use cases, from software bill of materials (SBOM) generation and license compliance to vulnerability tracking and software artifact exchange.
+
+While this document serves as the authoritative reference for implementing PURL, it is complemented by various ecosystem-specific guidance documents, examples, and related standards. These resources provide additional context and practical insights for leveraging PURL effectively.
+
+This overview is non-normative and serves to provide context for the specification’s intent, purpose, and audience. For detailed requirements and conformance criteria, refer to the normative sections of this specification.
diff --git a/docs/standard/references.md b/docs/standard/references.md
@@ -0,0 +1,12 @@
+# 3 Normative References
+
+The following referenced documents are indispensable for the application of this document.
+For dated references, only the edition cited applies. For undated references, the latest
+edition of the referenced document (including any amendments) applies.
+
+ASCII, *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
+
+RFC 3986, ​*Uniform Resource Identifier (URI): Generic Syntax*​.
+[https://datatracker.ietf.org/doc/html/rfc3986](https://datatracker.ietf.org/doc/html/rfc3986)
