Skip to content

Comments

Create a guide for ML-BOM relative to CycloneDX v1.7 schema#40

Open
mrutkows wants to merge 110 commits intoCycloneDX:mainfrom
mrutkows:mlbom-1.7
Open

Create a guide for ML-BOM relative to CycloneDX v1.7 schema#40
mrutkows wants to merge 110 commits intoCycloneDX:mainfrom
mrutkows:mlbom-1.7

Conversation

@mrutkows
Copy link
Contributor

@mrutkows mrutkows commented Jan 9, 2026 •
edited by jkowalleck
Loading

Ready for review

Note

this PR references/depends-on CycloneDX/cyclonedx-property-taxonomy#153

@mrutkows
Create a guide for ML-BOM relative to CycloneDX v1.7 schema
e41eaa6 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows mrutkows self-assigned this Jan 9, 2026
@mrutkows mrutkows requested a review from a team as a code owner January 9, 2026 18:55
@mrutkows mrutkows changed the title Create a guide for ML-BOM relative to CycloneDX v1.7 schema WIP - Create a guide for ML-BOM relative to CycloneDX v1.7 schema Jan 9, 2026
@mrutkows mrutkows added documentation Improvements or additions to documentation t: ML-BOM labels Jan 9, 2026
@mrutkows mrutkows marked this pull request as draft January 9, 2026 18:56
mrutkows added 23 commits January 9, 2026 14:12
@mrutkows
Create a guide for ML-BOM relative to CycloneDX v1.7 schema
ddc2f3b 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Create a guide for ML-BOM relative to CycloneDX v1.7 schema
48816b3 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Create a guide for ML-BOM relative to CycloneDX v1.7 schema
995666f 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
40817c0 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
71cc342 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
e37961b 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
e1baa55 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
388a017 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
036c797 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
4d1d23c 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
c1d79ac 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
3e8347f 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
27f6ed0 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
e83101e 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
846c47e 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
ac607a5 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
57b5f39 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
a9665d7 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
609fd7a 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
6d28bda 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
beb3480 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
a634c85 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Provide object design informaton for the ML-BOM
fc3b50e 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
mrutkows added 11 commits February 5, 2026 11:24
@mrutkows
Final edits, cleanup, link validation, etc.
c47bf63 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
c889e50 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
64f49a5 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
035e7d2 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
79fc617 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
01f5649 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
55eccfd 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
011e4e8 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
cd8dee2 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
9c87e05 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
8a7892a 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows mrutkows changed the title WIP - Create a guide for ML-BOM relative to CycloneDX v1.7 schema Create a guide for ML-BOM relative to CycloneDX v1.7 schema Feb 5, 2026
@mrutkows mrutkows marked this pull request as ready for review February 5, 2026 18:33
@mrutkows
Copy link
Contributor Author

mrutkows commented Feb 5, 2026

@stevespringett @jkowalleck @HesAnEasyCoder Ready for your review.

@mrutkows
Final edits, cleanup, link validation, etc.
43ec09f 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final edits, cleanup, link validation, etc.
7f2ccf6 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows mrutkows mentioned this pull request Feb 5, 2026
Open
@mrutkows
Copy link
Contributor Author

mrutkows commented Feb 5, 2026

Note: There is a dependence on Property Taxonomy PR: CycloneDX/cyclonedx-property-taxonomy#153

jkowalleck
jkowalleck reviewed Feb 9, 2026
View reviewed changes
Copy link
Member

@jkowalleck jkowalleck left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

some semantical questions and remarks

ML-BOM/en/0x22-Design-Model-Card-Parameters.md Outdated

Describes the input and output data types (formats) of the model.

>[!Note] The current object used to describe model inputs and outputs is limited to describing the data types strictly used for training and inference. Future revisions of CycloneDX plan to expand these objects to provide more detailed information especially in regard to names, formats and defaults for model configuration parameters and hyperparameters.
Copy link
Member

@jkowalleck jkowalleck Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this > [!NOTE] syntax is github only. probably no other tool will know what to do with it when redering this markdown...

And this is not how a note works. missing the line break, and more.

this is how it is supposed to be: https://github.com/orgs/community/discussions/16925

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

Copy link
Contributor Author

@mrutkows mrutkows Feb 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did assume GH markdown and forgot that you have to start the text on the next line (as my renderer did not seem to care. Can fix the multi-line aspect; is there a better way to include a "callout"? What tool should I verify with (the one Steve uses for conversion?)?

Copy link
Member

@stevespringett stevespringett Feb 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI the generated guide was posted to https://cyclonedx.slack.com/archives/C0A75L3E8V9/p1770336350500359?thread_ts=1770316529.613359&cid=C0A75L3E8V9 last week.

Copy link
Member

@stevespringett stevespringett Feb 10, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The tool is our GitHub Action that runs. But since this is a PR, I'm running it locally

ML-BOM/en/0x22-Design-Model-Card-Parameters.md
}
```

---
Copy link
Member

@jkowalleck jkowalleck Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why add a horizontal rule here?

Copy link
Contributor Author

@mrutkows mrutkows Feb 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Will look at... tried to add horz. rull between major topic (headers) consistently to breakup largish markdown files for readability.

@mrutkows
Improve parameter and hyperparameter exmaples using proposed ai-ml ta…
9758eb6 
…x. values

Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Improve parameter and hyperparameter exmaples using proposed ai-ml ta…
bf9bc0d 
…x. values

Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Improve parameter and hyperparameter exmaples using proposed ai-ml ta…
bfd72f7 
…x. values

Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Adjust all header levels to generate better guide index
3d70233 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Attempt to fix text scaling in svg
b3afcd1 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Fix all invalid markdown callout blocks
9259e09 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Fix empty link for glossary - prompt engineering
0f65684 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Final review: fix typos, etc.
c51142f 
Signed-off-by: Matt Rutkowski <mrutkows@us.ibm.com>
@mrutkows
Copy link
Contributor Author

mrutkows commented Feb 20, 2026 •
edited
Loading

@jkowalleck @stevespringett Happy with the draft generated from my last commit by Steve late yesterday (please note for the final build that I asked Steve if he could change the CSS style for code block and callout backgrounds to light gray as red/pink really seems an odd choice and not familiar to developers accustomed to markdown and endorsed). In addition, I will note most UI designers avoid "reds" as it is universally associated with errors, danger, or stop signals, which can cause user anxiety and visual fatigue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@jkowalleck jkowalleck jkowalleck left review comments

@stevespringett stevespringett Awaiting requested review from stevespringett

+1 more reviewer

@HesAnEasyCoder HesAnEasyCoder HesAnEasyCoder left review comments

Reviewers whose approvals may not affect merge requirements

Assignees

@mrutkows mrutkows

Labels

documentation Improvements or additions to documentation t: ML-BOM

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@mrutkows @jkowalleck @stevespringett @HesAnEasyCoder