Add root SBOM directory terminology, more tweaks

Author: sethmlarson

peps/pep-0770.rst

@@ -15,14 +15,20 @@ Post-History:
 Abstract
 ========
 
+Almost all Python packages today are accurately measurable by software
+composition analysis (SCA) tools and therefore do not need additional metadata
+to improve measurability. For projects that are not accurately measurable, there
+is no existing mechanism to annotate a Python package with composition data to
+improve measurability.
+
 Software Bill-of-Materials (SBOM) is a technology-and-ecosystem-agnostic
 method for describing software composition, provenance, heritage, and more.
-SBOMs are used as inputs for software composition analysis (SCA) tools,
-such as scanners for vulnerabilities and licenses, and have been gaining
-traction in global software regulations and frameworks.
+SBOMs are used as inputs for SCA tools, such as scanners for vulnerabilities and
+licenses, and have been gaining traction in global software regulations and
+frameworks.
 
 This PEP proposes using SBOM documents included in Python packages as a
-means to improve software measurability for Python packages.
+means to improve automated software measurability for Python packages.
 
 The changes will update the
 `Core Metadata specification <coremetadataspec_>`__ to version 2.5.
@@ -141,6 +147,24 @@ In addition to the above, an informational PEP will be created for tools
 consuming included SBOM documents and other Python package metadata to
 generate complete SBOM documents for Python packages.
 
+Terminology
+-----------
+
+This section describes terminology used later in the document:
+
+* **Root SBOM directory**: This is the directory within a Python project source
+  tree or package archive that SBOM documents are stored in. For
+  :term:`Project source trees <Project source tree>` and
+  :term:`Source Distributions <Source Distribution (or "sdist")>` the root SBOM
+  directory is the same directory containing ``pyproject.toml`` or other "root"
+  metadata file like ``PKG-INFO``/``setup.py``.
+
+  For :term:`Built Distribution`s and
+  :term:`Installed projects <Installed project>` the root SBOM directory is
+  defined as ``.dist-info/sboms``. The new ``Sbom-File`` Core Metadata
+  field defined below always specifies SBOM documents relative to the root SBOM
+  directory for the specific project format.
+
 .. _770-spec-core-metadata:
 
 Core Metadata
@@ -149,9 +173,9 @@ Core Metadata
 Add ``Sbom-File`` field
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-The ``Sbom-File`` is an optional Core Metadata field. Each instance contains a
-string representation of the path of an SBOM document. The path is located
-within the project source tree, relative to the project root directory. It is a
+The ``Sbom-File`` is a new optional Core Metadata field. Each instance contains a
+string representation of the path to an SBOM document. The path is specified
+relative to the root SBOM directory for all project types. It is a
 multi-use field that MAY appear zero or more times and each instance lists the
 path to one such file. Files specified under this field are SBOM documents
 that are distributed with the package.
@@ -170,8 +194,7 @@ If an ``Sbom-File`` is listed in a
   relative path.
 * Inside the root SBOM directory, packaging tools MUST reproduce the directory
   structure under which the source files are located relative to the project
-  root. The root SBOM directory is
-  `specified in a later section <#770-spec-project-formats>`__.
+  root.
 * Path delimiters MUST be the forward slash character (``/``), and parent
   directory indicators (``..``) MUST NOT be used.
 
@@ -191,10 +214,10 @@ This PEP specifies changes to the project's source metadata under a
 Add ``sbom-files`` key
 ~~~~~~~~~~~~~~~~~~~~~~
 
-A new ``sbom-files`` key is added to the ``[project]`` table for specifying
-paths in the project source tree relative to ``pyproject.toml`` to file(s)
-containing SBOMs to be distributed with the package. This key corresponds to the
-``Sbom-File`` fields in the Core Metadata.
+A new optional ``sbom-files`` key is added to the ``[project]`` table for
+specifying paths in the project source tree relative to ``pyproject.toml`` to
+file(s) containing SBOMs to be distributed with the package. This key
+corresponds to the ``Sbom-File`` fields in the Core Metadata.
 
 Its value is an array of strings which MUST contain valid glob patterns, as
 specified below:
@@ -384,8 +407,8 @@ added to the Python Packaging User Guide for how to specify and maintain
 SBOM documents for Python packages in source code.
 
 There are two groups of projects that contain other software, those from
-a "packaging ecosystem" (PyPI, Linux distros, Crates.io, NPM, etc) and those from
-outside a packaging ecosystem (vendored C, C++, Fortran). Software that is
+a "packaging ecosystem" (PyPI, Linux distros, Crates.io, NPM, etc) and those
+from outside a packaging ecosystem (vendored C, C++, Fortran). Software that is
 a part of a packaging ecosystem is much easier to identify meaning
 that package maintainers may have their package SBOM data annotated
 automatically by common build tools (
@@ -480,7 +503,8 @@ Open Issues
 Conditional project source SBOM files
 -------------------------------------
 
-How can a project specify an SBOM file that is conditional? Under what circumstances would an SBOM document be conditional?
+How can a project specify an SBOM file that is conditional? Under what
+circumstances would an SBOM document be conditional?
 
 Selecting a single SBOM standard
 --------------------------------