From 241e93f515cb0fcc138ea5a4d228c64d30f35342 Mon Sep 17 00:00:00 2001 From: Rul1an Date: Tue, 28 Apr 2026 15:46:32 +0200 Subject: [PATCH] docs: add ML-BOM model card example Signed-off-by: Rul1an --- MLBOM/Model-Card-With-Dataset/README.md | 16 +++ MLBOM/Model-Card-With-Dataset/bom.json | 152 ++++++++++++++++++++++++ MLBOM/README.md | 13 ++ README.md | 1 + 4 files changed, 182 insertions(+) create mode 100644 MLBOM/Model-Card-With-Dataset/README.md create mode 100644 MLBOM/Model-Card-With-Dataset/bom.json create mode 100644 MLBOM/README.md diff --git a/MLBOM/Model-Card-With-Dataset/README.md b/MLBOM/Model-Card-With-Dataset/README.md new file mode 100644 index 0000000..f42df95 --- /dev/null +++ b/MLBOM/Model-Card-With-Dataset/README.md @@ -0,0 +1,16 @@ +# Model Card With Dataset References + +This example shows a compact ML-BOM for an application that uses one fictional +machine-learning model and two fictional datasets. + +The BOM demonstrates: + +- a `machine-learning-model` component with an inline `modelCard` +- `modelCard.modelParameters.datasets[]` entries that reference dataset + components by `bom-ref` +- `data` components that include the recommended `data` property +- top-level dependency links from the model to the referenced datasets + +All names, URLs, and metric values are illustrative. They are not statements +about a real model, dataset, performance result, license, safety posture, or +deployment. diff --git a/MLBOM/Model-Card-With-Dataset/bom.json b/MLBOM/Model-Card-With-Dataset/bom.json new file mode 100644 index 0000000..780537c --- /dev/null +++ b/MLBOM/Model-Card-With-Dataset/bom.json @@ -0,0 +1,152 @@ +{ + "$schema": "http://cyclonedx.org/schema/bom-1.7.schema.json", + "bomFormat": "CycloneDX", + "specVersion": "1.7", + "serialNumber": "urn:uuid:df4f6ec7-6d36-47e6-a15b-640a0af54267", + "version": 1, + "metadata": { + "timestamp": "2026-04-28T12:00:00Z", + "component": { + "type": "application", + "bom-ref": "component-support-triage-service", + "name": "support-triage-service", + "version": "1.0.0", + "description": "Fictional application that uses a text classification model to route support tickets." + } + }, + "components": [ + { + "type": "machine-learning-model", + "bom-ref": "component-support-ticket-classifier", + "publisher": "Example ML Team", + "name": "support-ticket-classifier", + "version": "1.0.0", + "description": "Fictional supervised text classification model for support ticket routing.", + "modelCard": { + "bom-ref": "model-card-support-ticket-classifier", + "modelParameters": { + "approach": { + "type": "supervised" + }, + "task": "text-classification", + "architectureFamily": "transformer", + "modelArchitecture": "encoder-only transformer", + "datasets": [ + { + "ref": "component-support-ticket-training-data" + }, + { + "ref": "component-support-ticket-evaluation-data" + } + ], + "inputs": [ + { + "format": "text/plain" + } + ], + "outputs": [ + { + "format": "application/json" + } + ] + }, + "quantitativeAnalysis": { + "performanceMetrics": [ + { + "type": "macro-f1", + "value": "0.91", + "slice": "held-out-evaluation" + } + ] + }, + "considerations": { + "users": [ + "Support operations staff reviewing suggested ticket queues." + ], + "useCases": [ + "Suggest an initial support queue for a newly received support ticket." + ], + "technicalLimitations": [ + "The example model is illustrative and should not be used to infer production readiness." + ], + "performanceTradeoffs": [ + "The illustrative metric is included only to demonstrate the CycloneDX modelCard structure." + ], + "ethicalConsiderations": [ + { + "name": "automation bias", + "mitigationStrategy": "Human review remains responsible for final ticket routing." + } + ], + "fairnessAssessments": [ + { + "groupAtRisk": "Customers using underrepresented languages or dialects", + "benefits": "Faster initial triage when the model is reliable for the submitted language.", + "harms": "Misrouting can delay support if the model performs poorly for the submitted language.", + "mitigationStrategy": "Monitor routing quality across language slices and allow manual override." + } + ] + } + } + }, + { + "type": "data", + "bom-ref": "component-support-ticket-training-data", + "name": "support-ticket-training-data", + "version": "2026.04", + "description": "Fictional dataset component used to train the support ticket classifier.", + "data": [ + { + "bom-ref": "data-support-ticket-training-data", + "type": "dataset", + "name": "Support Ticket Training Data", + "contents": { + "url": "https://example.com/datasets/support-tickets/train.jsonl" + }, + "classification": "internal", + "description": "Illustrative training split for the fictional support ticket classifier." + } + ] + }, + { + "type": "data", + "bom-ref": "component-support-ticket-evaluation-data", + "name": "support-ticket-evaluation-data", + "version": "2026.04", + "description": "Fictional held-out dataset component used to evaluate the support ticket classifier.", + "data": [ + { + "bom-ref": "data-support-ticket-evaluation-data", + "type": "dataset", + "name": "Support Ticket Evaluation Data", + "contents": { + "url": "https://example.com/datasets/support-tickets/eval.jsonl" + }, + "classification": "internal", + "description": "Illustrative evaluation split for the fictional support ticket classifier." + } + ] + } + ], + "dependencies": [ + { + "ref": "component-support-triage-service", + "dependsOn": [ + "component-support-ticket-classifier" + ] + }, + { + "ref": "component-support-ticket-classifier", + "dependsOn": [ + "component-support-ticket-training-data", + "component-support-ticket-evaluation-data" + ] + }, + { + "ref": "component-support-ticket-training-data" + }, + { + "ref": "component-support-ticket-evaluation-data" + } + ] +} diff --git a/MLBOM/README.md b/MLBOM/README.md new file mode 100644 index 0000000..05d5b6f --- /dev/null +++ b/MLBOM/README.md @@ -0,0 +1,13 @@ +# Machine Learning Bill of Materials (ML-BOM) + +A Machine Learning Bill of Materials (ML-BOM) describes AI/ML inventory such as +models, datasets, and related artifacts. CycloneDX supports ML-BOM use cases with +component types such as `machine-learning-model` and `data`, plus `modelCard` +metadata for model transparency. + +This directory contains compact examples that are intended to be easy to inspect, +validate, and reuse as starting points. + +| Example | Description | +|---------|-------------| +| [Model Card With Dataset References](Model-Card-With-Dataset) | A schema-valid ML-BOM showing one application, one model component, two dataset components, an inline model card, dataset references, and dependency links. | diff --git a/README.md b/README.md index 759c207..7389f87 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ are categorized by different BOM types including: |--------------------|-----------------------------------------| | [CBOM](CBOM) | Cryptography Bill of Materials | | [HBOM](HBOM) | Hardware Bill of Materials | +| [MLBOM](MLBOM) | Machine Learning Bill of Materials | | [OBOM](OBOM) | Operations Bill of Materials | | [SaaSBOM](SaaSBOM) | Software-as-a-Service Bill of Materials | | [SBOM](SBOM) | Software Bill of Materials |