Update doc to match ECMA-427

The changes are:
- Update docs/standard files to match ECMA-427 first edition text
- Removed docs/purl-spec-toc.md, docs/standard/header.md and purl-specification.md; and updated PURL-SPECIFICATION.rst to reflect publication of ECMA-427
- Added docs/README-docs.md to explain the organization of the docs folder and the mapping to ECMA-427 text

Author: mjherzog

PURL-SPECIFICATION.rst

@@ -1,5 +1,4 @@
 The contents of this file: purl-spec/PURL-SPECIFICATION.rst have been moved
-to markdown files in `purl-spec/docs/ <docs/>`__. See the file: `purl-specification.md <purl-specification.md>`__ at
-the root of this repository for the most current version of content equivalent
-to PURL-SPECIFICATION.rst as generated from the current documentation files in
-purl-spec/docs/ .
+to markdown files in `purl-spec/docs/ <docs/>`__. See also the Package-URL
+Specification 1st Edition standard at: 
+https://ecma-international.org/publications-and-standards/standards/ecma-427/.

docs/README-docs.md

@@ -0,0 +1,40 @@
+This README explains the organization of documentation files for the PURL 
+specification.
+
+## ECMA-427 documentation
+The `purl-spec/docs/standard` folder has markdown files with text that match the content of [ECMA-427](https://ecma-international.org/publications-and-standards/standards/ecma-427/) which is the first edition of the Package-URL 
+Specification standard. These files map to ECMA-427 document as follows:
+
+- About this specification: `about.md`
+- Introduction: `introduction.md`
+- Clause 1 Scope: `scope.md`
+- Clause 2 Conformance: `conformance.md`
+- Clause 3 Normative references: `refererences.md`
+- Clause 4 Overview: `overview.md`
+- Clause 5 Package-URL specification: `specification.md`
+- Clause 6 Package-URL Type Definition Schema: `type-definition-schema.md`
+
+ECMA-427 is the official documention for the 1st edition of the PURL
+Specification standard. The source for this documentation is located at:
+https://github.com/Ecma-TC54/ECMA-427/blob/main/spec.html. The text stored in
+purl-spec/docs/standard/` matches the official text with following exceptions:
+- The text does not include the clause numbering from ECMA-427. This 
+numbering is automatically added by the Ecma tools for publishing an Ecma
+standard.
+- `docs/standard/type-definition-schema.md` only has the introductory text
+from ECMA-427 Clause 6 because Clause 6 presents the PURL Type Definition 
+Schema in a "human-friendly" format that is difficult to reproduce in
+markdown. The equivalent information is in this repository in JSON Schema 
+format: at `purl-spec/schemas/purl-type-definition.schema-1.0.json`
+
+The purpose of keeping a copy of the ECMA-427 text here is to make it easier
+to track any proposed changes to the PURL specification that will affect
+the ECMA-427 standard. Any such changes need to be tracked and approved for
+a future 2nd edition of the ECMA-427 standard.
+
+## PURL specification documentation
+The other files in `purl-spec/docs` are also specification documentation, but 
+they are not part of the ECMA-427 1st edition standard. Most of the documents
+provide information to support implementation of the PURL Specification in 
+other software or databases.
+

docs/purl-spec-toc.md

@@ -1,22 +1,22 @@
 # About this Specification
 
-The document at [https://tc54.org/ecmaXXX/](https://tc54.org/ecmaXXX/) is the
+The document at [https://tc54.org/ecm427/](https://tc54.org/ecma427/) 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/).
+This document is available as [a single page](https://ecma-tc54.github.io/ECMA-427/)
+and as [multiple pages](https://ecma-tc54.github.io/ECMA-427/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)
+* GitHub Repository: [https://github.com/Ecma-TC54/ECMA-xxx-PURL](https://github.com/Ecma-TC54/ECMA-427)
+* Issues: [All Issues](https://github.com/Ecma-TC54/ECMA-427/issues),
+  [File a New Issue](https://github.com/Ecma-TC54/ECMA-427/issues/new)
+* Pull Requests: [All Pull Requests](https://github.com/Ecma-TC54/ECMA-427/pulls),
+  [Create a New Pull Request](https://github.com/Ecma-TC54/ECMA-427/pulls/new)
 * Editors:
   * [John Horan](mailto:jmhoran@aboutcode.org)
   * [Michael Herzog](mailto:mjherzog@aboutcode.org)
@@ -25,5 +25,5 @@ this specification:
 * Community:
   * Chat: [Slack Channel](https://cyclonedx.slack.com/archives/C06KTE3BWEB)
 
-Refer to the [colophon](https://ecma-tc54.github.io/ECMA-xxx-PURL/#sec-colophon)
+Refer to the [colophon](https://ecma-tc54.github.io/ECMA-427/#sec-colophon)
 for more information on how this document was created.

docs/standard/about.md

@@ -1,26 +1,4 @@
-# 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
+# Conformance
 
 A conforming implementation of Package-URL (PURL) must fully implement and
 support all elements defined within this specification, including the syntax,
@@ -60,15 +38,4 @@ 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.
+PURLs across tools, platforms, or ecosystems are strictly disallowed.

docs/standard/characters-and-encoding.md

@@ -1,6 +1,6 @@
-# 4 Overview
+# Overview
 
-This section contains a non-normative overview of the Package-URL
+This Clause contains a non-normative overview of the Package-URL
 specification.
 
 The Package-URL (PURL) specification defines a lightweight, universal syntax
@@ -11,19 +11,16 @@ 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,
+This Standard 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 artefact exchange.
+The primary audience for this Standard 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 artefact exchange.
 
 While this document serves as the authoritative reference for implementing
 PURL, it is complemented by various ecosystem-specific guidance documents,
@@ -32,4 +29,4 @@ 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.
+conformance criteria, refer to the normative sections of this Standard.