Move SBOM data recommendations, address review comments

Author: sethmlarson

peps/pep-0770.rst

@@ -101,20 +101,26 @@ package archive or information about the top-level software in the package that
 can't be encoded into Core Metadata but is relevant for the SBOM use-case
 ("software identifiers", "purpose", "support level", etc).
 
-Zero-or-more SBOM documents per package
----------------------------------------
+Zero-or-more opaque SBOM documents
+----------------------------------
 
 Rather than requiring at most one included SBOM document per Python package,
 this PEP proposes that one or more SBOM documents may be included in a Python
 package. This means that code attempting to annotate a Python package with SBOM
 data may do so without being concerned about corrupting data already contained
 within other SBOM documents.
 
-This decision also means this PEP is capable of supporting multiple SBOM
-standards without favoring one, instead deferring support to SBOM consuming
-tools. This decision also means that the merging of SBOM documents never needs
-to be handled by Python tools, instead deferring this to SBOM consuming tools
-who are better placed to handle cross-standard conversions.
+Additionally, this PEP treats SBOM document data opaquely instead relying on
+final end-users of the SBOM data to process the contained SBOM data.
+This choice acknowledges that SBOM standards are an active area of development
+where there is not yet (and may never be) a single definitive SBOM standard
+and that SBOM standards can continue to evolve independent of Python packaging
+standards. Already tools that consume SBOM documents support a multitude of
+SBOM standards to handle this reality.
+
+These decisions mean this PEP is capable of supporting any SBOM standard
+and does not favor one over the other, instead deferring the decision to
+producing projects and tools and consuming user tooling.
 
 .. _770-spec:
 
@@ -159,36 +165,20 @@ If an ``Sbom-File`` is listed in a
 :term:`Built Distribution`'s Core Metadata:
 
 * That file MUST be included in the :term:`distribution archive` at the
-  specified path relative to the root license directory.
-* That file MUST be installed with the :term:`project` at that same relative
-  path.
+  specified path relative to the root SBOM directory.
+* Installers MUST install the file with the :term:`project` at that same
+  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>`__.
 * Path delimiters MUST be the forward slash character (``/``), and parent
   directory indicators (``..``) MUST NOT be used.
-* SBOM document contents MUST be UTF-8 encoded JSON according to :rfc:`8259`.
-* SBOM document contents MUST use an SBOM standard, and for better
-  interoperability SHOULD be a well-known SBOM standard such as
-  `CycloneDX <cyclonedxspec_>`_ or `SPDX <spdxspec_>`_.
-* The "primary" component being described in included SBOM documents MUST be the
-  Python package. This is achieved in CycloneDX using the ``metadata.component``
-  field and in SPDX using the ``DESCRIBES`` relationship.
-* SBOM documents MUST include metadata for the timestamp when the SBOM document
-  was created. This information helps consuming tools understand the order that
-  multiple SBOM documents were created to untangle conflicts between various
-  stages building the Python package.
-* SBOM documents SHOULD include metadata describing the tool creating the SBOM
-  document. This information helps users find which tool needs to be fixed in
-  the case of defects.
 
 For all newly-uploaded distribution archives that include one or more
 ``Sbom-File`` fields in their Core Metadata and declare a ``Metadata-Version``
-of ``2.5`` or higher, PyPI SHOULD validate that all specified files are present
-in the distribution archives, are valid UTF-8 encoded JSON, and for well-known
-SBOM standards provide the minimum required fields by those standards and this
-PEP.
+of ``2.5`` or higher, PyPI and other indices SHOULD validate that all files
+specified with ``Sbom-File`` are present in the distribution archives.
 
 .. _770-spec-project-source-metadata:
 
@@ -252,7 +242,7 @@ Examples of valid SBOM files declarations:
     sbom-files = ["bom.json"]
 
     [project]
-    sbom-files = ["sboms/openssl.cdx.json", "licenses/openssl.spdx.json"]
+    sbom-files = ["sboms/openssl.cdx.json", "sboms/openssl.spdx.json"]
 
     [project]
     sbom-files = ["sboms/*"]
@@ -316,6 +306,36 @@ A few additions will be made to the existing specifications.
   relative to the ``sboms`` directory, and that any files in this directory MUST
   be copied from wheels by install tools.
 
+SBOM data interoperability
+--------------------------
+
+This PEP treats data contained within SBOM documents as opaque, recognizing
+that SBOM standards are an active area of development. However, there are some
+considerations for SBOM data producers that when followed will improve the
+interoperability and usability of SBOM data made available in Python packages:
+
+* SBOM documents SHOULD use a widely-accepted SBOM standard, such as
+  `CycloneDX <cyclonedxspec_>`_ or `SPDX <spdxspec_>`_.
+* SBOM documents SHOULD use UTF-8-encoded JSON (:rfc:`8259`) when available
+  for the SBOM standard in use.
+* SBOM documents SHOULD include all required fields for the SBOM standard in
+  use.
+* SBOM documents SHOULD include a "time of creation" and "creating tool" field
+  for the SBOM standard in use. This information is important for users
+  attempting to reconstruct different stages for a Python package being built.
+* The primary component described by the SBOM document SHOULD be the top-level
+  software within the Python package (for example,
+  "pkg:pypi/pillow" for the "Pillow" package).
+* All non-primary components SHOULD have one or more paths in the relationship
+  graph showing the relationship between components. If this information isn't
+  included, SCA tools might exclude components outside of the relationship graph.
+* All software components SHOULD have a name, version, and one or more software
+  identifiers (PURL, CPE, download URL).
+
+PyPI and other indices MAY validate the contents of SBOM documents specified by
+this PEP, but MUST NOT validate or reject data for unknown
+SBOM standards, versions, or fields.
+
 Backwards Compatibility
 =======================
 
@@ -400,6 +420,13 @@ 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?
 
+Selecting a single SBOM standard
+--------------------------------
+
+Should this PEP select a single SBOM standard instead of supporting any
+SBOM standard? Selecting a single standard would potentially limit the
+evolution of SBOM standards which is an active area of development.
+
 References
 ==========