Sync guide content from Google Docs and externalize image assets for GitHub-friendly maintenance by KoukiHama · Pull Request #18 · OpenChain-Project/SBOM-wg

KoukiHama · 2026-04-05T03:29:32Z

Summary

This PR refreshes the English SBOM Document Quality Guide using the latest Markdown exported from the Google Docs source document, and restructures the GitHub file layout to make the guide easier to review, maintain, and update.

Changes

Updated the Markdown body based on the latest Markdown downloaded from the Google Docs source document.
Separated embedded images from the Markdown and stored them as standalone asset files.
Replaced embedded image content with relative image references.
Split the main guide into chapter-level Markdown files under Cross-Industry-SBOM-Quality-Guide/en/chapters/.
Changed Cross-Industry-SBOM-Quality-Guide.md into an entry-point / table-of-contents file that links to the chapter files.
Updated the English README to describe the chapter-based structure.
Improved the repository layout for cleaner review and future maintenance.

Rationale

This makes the document easier to work with in GitHub:

Content changes are easier to review by chapter.
Image changes are isolated from text changes.
Contributors can edit focused sections without touching the entire guide.
Chapter-level files reduce the risk of large, hard-to-review Markdown diffs.
Future GitHub Actions for checking, transforming, or publishing the document will be easier to introduce.

Source

The original editable document is maintained here:

https://docs.google.com/document/d/1iuXX8j10N70dfce1-CZFWhW6S2jEqc--flcCgXMMdjg/edit?pli=1&tab=t.0

Public comments / Q&A

The public comments and Q&A tracking sheet is maintained here:

https://docs.google.com/spreadsheets/d/1tooDiuAixOn9enyA_zvzRrEgPi4Kyq-u/edit?usp=sharing&ouid=105671686755504216583&rtpof=true&sd=true

Signed-off-by: Kouki Hama <hamakouki0818@gmail.com>

…assets

Signed-off-by: Kouki Hama <hamakouki0818@gmail.com>

NorioKobota

Reviewed 02- and will continue to review.

NorioKobota · 2026-05-20T04:31:38Z

@@ -0,0 +1,11 @@
+# 0\. Preface {#0.-preface}


What is the purpose of the embedded '{#0.-preface}'? anchor?

This seems to be a Pandoc's Markdown extension.

We should be need to decide whether or not to use Markdown extensions.

NorioKobota · 2026-05-20T05:05:42Z

@@ -0,0 +1,16 @@
+# 1\. Scope and SBOM Document Quality {#1.-scope-and-sbom-document-quality}


Same as previous: e04598e#r3271227462

NorioKobota · 2026-05-20T05:08:28Z

+
+While the term **"SBOM"** generally refers to the information that constitutes a software's composition, this guide specifically focuses on the quality of the “**SBOM Document”**. In this guide, **”SBOM Document”** is a structured artifact – typically formatted in JSON and based on specifications such as SPDX or CycloneDX – that is exchanged between software distributors and recipients.
+
+![][image1]  


Memo: Transparent image is hard to see in dark mode. Will fix soon.

NorioKobota · 2026-05-20T05:11:14Z

+
+* Adequacy of Security Assurance  
+  Assesses whether sufficient baseline information is provided to support an investigation that validates the software's security posture, even if, at the time of delivery, the document does not comprehensively cover all risks, vulnerabilities, or mitigation strategies.  
+  * Effectiveness of License Compliance  


This bullet should be aligned.

NorioKobota · 2026-05-20T05:11:44Z

+  * Effectiveness of License Compliance  
+    Assesses whether the necessary licensing details and usage terms for each software component are properly captured to ensure compliance with relevant laws and regulations.
+
+  By adhering to this guide, stakeholders can ensure that the SBOM Documents exchanged within the software supply chain consistently meet high-quality standards.


Wrong indentation here.

NorioKobota · 2026-05-20T05:13:23Z

+
+  By adhering to this guide, stakeholders can ensure that the SBOM Documents exchanged within the software supply chain consistently meet high-quality standards.
+
+[image1]: <../assets/images/sbom-document-quality-guide/01-scope-and-sbom-document-quality-overview.png>


Images should probably go under the MD file's directory, but let's discuss.

NorioKobota · 2026-05-20T05:13:55Z

@@ -0,0 +1,19 @@
+# 2\. Terms and Definitions {#2.-terms-and-definitions}


Same as previous: e04598e#r3271227462

NorioKobota · 2026-05-20T05:27:35Z

+| SPDX | SPDX (System Package Data Exchange) is the ISO standard ([ISO/IEC 5962:2021](https://www.iso.org/standard/81870.html)) for exchanging SBOM for a given software package, including associated license and copyright information. The standard was created by the Linux Foundation's [SPDX project](https://spdx.dev/). |
+| CycloneDX | CycloneDX is the ECMA standard ([ECMA-424](https://ecma-international.org/publications-and-standards/standards/ecma-424/)) for a full-stack Bill of Materials (BOM) standard that provides advanced supply chain capabilities for cyber risk reduction.The standard was created by the OWASP Foundation, which is a nonprofit foundation for improving software security. |
+| OpenChain Specification ISO/IEC 5230:2020 | [ISO/IEC 5230:2020](https://www.iso.org/standard/81039.html) is an international standard that specifies the key requirements of a quality open source license compliance program in order to provide a benchmark that builds trust between organizations exchanging software solutions that incorporate open source software. The OpenChain standard is produced by [the OpenChain project](https://www.openchainproject.org/) of the Linux Foundation. |
+| OpenChain Specification ISO/IEC 18974:2023 | [ISO/IEC MO 18974:2023](https://www.iso.org/standard/86450.html) is an international standard from the OpenChain Project that provides requirements for open source software security assurance. It aims to improve software supply chain confidence by managing publicly known security vulnerabilities. Organizations can demonstrate compliance through self-certification or audits. |


[ISO/IEC MO 18974:2023]
Remove "MO".

xoxyuxu · 2026-05-20T14:31:56Z

+* OpenChain Telco SBOM Guide Version 1.1  
+  [https://github.com/OpenChain-Project/Telco-WG/blob/main/OpenChain-Telco-SBOM-Guide\_EN.md](https://github.com/OpenChain-Project/Telco-WG/blob/main/OpenChain-Telco-SBOM-Guide_EN.md)
+
+## 


Empty header should be removed.

xoxyuxu · 2026-05-20T14:44:38Z

+##  {#heading}
+
+## 
+


Empty headers should be removed.

// Does original document has empty header ?

xoxyuxu · 2026-05-20T14:48:39Z

+
+## 
+
+## 6.2 Cross-Regulation Comparison Table {#heading}


If we use Pandoc's Markdown extension:
{#heading} should be {#6\.2-cross-regulation-comparison-table}

If we don't use it, remove {#heading}.

xoxyuxu · 2026-05-20T15:03:48Z

+### 
+


Empty header should be removed.

xoxyuxu · 2026-05-20T15:04:19Z

+## 
+


Empty header should be removed.

xoxyuxu · 2026-05-20T15:36:35Z

The files in assets/images/sbom-document-quality-guide/ are saved as a PNG. The text is illegible due to its size, so it should be an SVG or resized more larger, aren't them ?

xoxyuxu · 2026-05-20T15:49:11Z

+1. Keywords for describing the current state of a component  
+   1. “contains” / ”composition-assemblies”  
+      Indicates that a component includes or is composed of another.    
+   2. “dependsOn” / “composition-dependencies”  
+      Indicates that a component depends on or requires another.  
+2. Keywords for describing the origin of a component    
+   1. “generatedFrom” / “components-pedigree”  
+      Indicates that a component was generated (replicated, modified, or built) from another.  


The second row of the list syntax contains numbers. But the original document uses letters.

case 1: use html tag <ol type="a"><li>...
case 2: write directly a., b....
case 3: ignore about this difference.

xoxyuxu · 2026-05-20T15:58:03Z

+| SBOM Document for ‘application A’ from **Vendor1** | file-level | All dependency shall be recorded and provided at the file-level. | **Maker1** needs to convert file-level information to package-level for application A. |
+| SBOM Document for ‘application A’ from **Vendor1** | package-level | **Maker1** needs to decompose package-level information and convert them to  file-level. | All dependency shall be recorded and provided at the package-level. |


All dependency -> All dependencies

This fix is figured out by comment in the original document.
Commented by Saquib Saifee.

If this pull request is for translation only and not included above comment's fixes, ignore this.

no-ta · 2026-05-21T08:45:38Z

3.1.2 Rationale {#3.1.2-rationale}

"improved the document quality." -> "improves the document quality."

KoukiHama requested a review from NorioKobota April 5, 2026 03:29

Update SBOM Document Quality Guide and externalize image assets

3881235

Signed-off-by: Kouki Hama <hamakouki0818@gmail.com>

KoukiHama force-pushed the update-sbom-quality-guide-assets branch from e30ccf8 to 3881235 Compare May 19, 2026 21:33

KoukiHama added 2 commits May 20, 2026 09:33

Merge branch 'OpenChain-Project:main' into update-sbom-quality-guide-…

5af3516

…assets

Split SBOM Quality Guide into chapter files

e04598e

Signed-off-by: Kouki Hama <hamakouki0818@gmail.com>

KoukiHama marked this pull request as ready for review May 20, 2026 00:50

NorioKobota requested changes May 20, 2026

View reviewed changes

xoxyuxu reviewed May 20, 2026

View reviewed changes

no-ta reviewed May 21, 2026

View reviewed changes

		@@ -0,0 +1,16 @@
		# 1\. Scope and SBOM Document Quality {#1.-scope-and-sbom-document-quality}


		While the term "SBOM" generally refers to the information that constitutes a software's composition, this guide specifically focuses on the quality of the “SBOM Document”. In this guide, ”SBOM Document” is a structured artifact – typically formatted in JSON and based on specifications such as SPDX or CycloneDX – that is exchanged between software distributors and recipients.

		![][image1]


		By adhering to this guide, stakeholders can ensure that the SBOM Documents exchanged within the software supply chain consistently meet high-quality standards.

		[image1]: <../assets/images/sbom-document-quality-guide/01-scope-and-sbom-document-quality-overview.png>

		@@ -0,0 +1,19 @@
		# 2\. Terms and Definitions {#2.-terms-and-definitions}

		\| SBOM Document for ‘application A’ from Vendor1 \| file-level \| All dependency shall be recorded and provided at the file-level. \| Maker1 needs to convert file-level information to package-level for application A. \|
		\| SBOM Document for ‘application A’ from Vendor1 \| package-level \| Maker1 needs to decompose package-level information and convert them to file-level. \| All dependency shall be recorded and provided at the package-level. \|

		###

Conversation

KoukiHama commented Apr 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Rationale

Source

Public comments / Q&A

Uh oh!

NorioKobota left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

xoxyuxu commented May 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

3.1.2 Rationale {#3.1.2-rationale}

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

KoukiHama commented Apr 5, 2026 •

edited

Loading