Merge pull request #209 from CycloneDX/v1.5-dev-machine-learning

Added support for ML

Author: stevespringett

schema/bom-1.5.proto

@@ -59,6 +59,12 @@ enum Classification {
   CLASSIFICATION_FIRMWARE = 8;
   // A special type of software that operates or controls a particular type of device. Refer to https://en.wikipedia.org/wiki/Device_driver
   CLASSIFICATION_DEVICE_DRIVER = 9;
+  // A runtime environment which interprets or executes software. This may include runtimes such as those that execute bytecode or low-code/no-code application platforms.
+  CLASSIFICATION_PLATFORM = 10;
+  // A model based on training data that can make predictions or decisions without being explicitly programmed to do so.
+  CLASSIFICATION_MACHINE_LEARNING_MODEL = 11;
+  // A collection of discrete values that convey information.
+  CLASSIFICATION_DATA = 12;
 }
 
 message Commit {
@@ -121,6 +127,10 @@ message Component {
   repeated Evidence evidence = 23;
   // Specifies optional release notes.
   optional ReleaseNotes releaseNotes = 24;
+  // A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets used to train the model, performance metrics, and other relevant data useful for ML transparency.
+  optional ModelCard modelCard = 25;
+  // This object SHOULD be specified for any component of type `data` and MUST NOT be specified for other component types.
+  optional ComponentData data = 26;
 }
 
 // Specifies the data flow.
@@ -233,6 +243,8 @@ enum ExternalReferenceType {
   EXTERNAL_REFERENCE_TYPE_QUALITY_METRICS = 28;
   // Code or configuration that defines and provisions virtualized infrastructure, commonly referred to as Infrastructure as Code (IaC)
   EXTERNAL_REFERENCE_TYPE_CODIFIED_INFRASTRUCTURE = 29;
+  // A model card describes the intended uses of a machine learning model, potential limitations, biases, ethical considerations, training parameters, datasets used to train the model, performance metrics, and other relevant data useful for ML transparency.
+  EXTERNAL_REFERENCE_TYPE_MODEL_CARD = 30;
 }
 
 enum HashAlg {
@@ -916,4 +928,181 @@ message Annotation {
   google.protobuf.Timestamp timestamp = 4;
   // The textual content of the annotation.
   string text = 5;
+}
+
+message ModelCard {
+  // An optional identifier which can be used to reference the model card elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.
+  optional string bom_ref = 1;
+  // Hyper-parameters for construction of the model.
+  optional ModelParameters modelParameters = 2;
+  // A quantitative analysis of the model
+  optional QuantitativeAnalysis quantitativeAnalysis = 3;
+  // What considerations should be taken into account regarding the model's construction, training, and application?
+  optional ModelCardConsiderations considerations = 4;
+
+  message ModelParameters {
+    // The overall approach to learning used by the model for problem solving.
+    optional Approach approach = 1;
+    // Directly influences the input and/or output. Examples include classification, regression, clustering, etc.
+    optional string task = 2;
+    // The model architecture family such as transformer network, convolutional neural network, residual neural network, LSTM neural network, etc.
+    optional string architectureFamily = 3;
+    //The specific architecture of the model such as GPT-1, ResNet-50, YOLOv3, etc.
+    optional string modelArchitecture = 4;
+    // The datasets used to train and evaluate the model.
+    repeated Datasets datasets = 5;
+    // The input format(s) of the model
+    repeated MachineLearningInputOutputParameters inputs = 6;
+    // The output format(s) from the model
+    repeated MachineLearningInputOutputParameters outputs = 7;
+
+    message Approach {
+      optional ModelParameterApproachType type = 1;
+    }
+    message Datasets {
+      oneof choice {
+        ComponentData dataset = 1;
+        // References a data component by the components bom-ref attribute
+        string ref = 2;
+      }
+    }
+    message MachineLearningInputOutputParameters {
+      // The data format for input/output to the model. Example formats include string, image, time-series
+      optional string format = 1;
+    }
+  }
+  message QuantitativeAnalysis {
+    // The model performance metrics being reported. Examples may include accuracy, F1 score, precision, top-3 error rates, MSC, etc.
+    repeated PerformanceMetrics performanceMetrics = 1;
+    optional GraphicsCollection graphics = 2;
+
+    message PerformanceMetrics {
+      // The type of performance metric.
+      optional string type = 1;
+      // The value of the performance metric.
+      optional string value = 2;
+      // The name of the slice this metric was computed on. By default, assume this metric is not sliced.
+      optional string slice = 3;
+      // The confidence interval of the metric.
+      optional ConfidenceInterval confidenceInterval = 4;
+
+      message ConfidenceInterval {
+        // The lower bound of the confidence interval.
+        optional string lowerBound = 1;
+        // The upper bound of the confidence interval.
+        optional string upperBound = 2;
+      }
+    }
+  }
+  message ModelCardConsiderations {
+    // Who are the intended users of the model?
+    repeated string users = 1;
+    // What are the intended use cases of the model?
+    repeated string useCases = 2;
+    // What are the known technical limitations of the model? E.g. What kind(s) of data should the model be expected not to perform well on? What are the factors that might degrade model performance?
+    repeated string technicalLimitations = 3;
+    // What are the known tradeoffs in accuracy/performance of the model?
+    repeated string performanceTradeoffs = 4;
+    // What are the ethical (or environmental) risks involved in the application of this model?
+    repeated EthicalConsiderations ethicalConsiderations = 5;
+    // How does the model affect groups at risk of being systematically disadvantaged? What are the harms and benefits to the various affected groups?
+    repeated FairnessAssessments fairnessAssessments = 6;
+
+    message EthicalConsiderations {
+      // The name of the risk.
+      optional string name = 1;
+      // Strategy used to address this risk.
+      optional string mitigationStrategy = 2;
+    }
+    message FairnessAssessments {
+      // The groups or individuals at risk of being systematically disadvantaged by the model.
+      optional string groupAtRisk = 1;
+      // Expected benefits to the identified groups.
+      optional string benefits = 2;
+      // Expected harms to the identified groups.
+      optional string harms = 3;
+      // With respect to the benefits and harms outlined, please describe any mitigation strategy implemented.
+      optional string mitigationStrategy = 4;
+    }
+  }
+}
+
+enum ModelParameterApproachType {
+  MODEL_PARAMETER_APPROACH_TYPE_SUPERVISED = 0;
+  MODEL_PARAMETER_APPROACH_TYPE_UNSUPERVISED = 1;
+  MODEL_PARAMETER_APPROACH_TYPE_REINFORCED_LEARNING = 2;
+  MODEL_PARAMETER_APPROACH_TYPE_SEMI_SUPERVISED = 3;
+  MODEL_PARAMETER_APPROACH_TYPE_SELF_SUPERVISED = 4;
+}
+
+message ComponentData {
+  // An optional identifier which can be used to reference the dataset elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.
+  optional string bom_ref = 1;
+  // The general theme or subject matter of the data being specified.
+  ComponentDataType type = 2;
+  // The name of the dataset.
+  optional string name = 3;
+  // The contents or references to the contents of the data being described.
+  optional ComponentDataContents contents = 4;
+  // Data classification tags data according to its type, sensitivity, and value if altered, stolen, or destroyed.
+  optional string classification = 5;
+  // A description of any sensitive data in a dataset.
+  repeated string sensitiveData = 6;
+  // A collection of graphics that represent various measurements.
+  optional GraphicsCollection graphics = 7;
+  // A description of the dataset. Can describe size of dataset, whether it's used for source code, training, testing, or validation, etc.
+  optional string description = 8;
+  // Data Governance
+  optional DataGovernance governance = 9;
+
+  message ComponentDataContents {
+    // An optional way to include textual or encoded data.
+    optional AttachedText attachment = 1;
+    // The URL to where the data can be retrieved.
+    optional string url = 2;
+    // Provides the ability to document name-value parameters used for configuration.
+    repeated Property properties = 3;
+  }
+
+  message DataGovernance {
+    // Data custodians are responsible for the safe custody, transport, and storage of data.
+    repeated DataGovernanceResponsibleParty custodians = 1;
+    // Data stewards are responsible for data content, context, and associated business rules.
+    repeated DataGovernanceResponsibleParty stewards = 2;
+    // Data owners are concerned with risk and appropriate access to data.
+    repeated DataGovernanceResponsibleParty owners = 3;
+
+    message DataGovernanceResponsibleParty {
+      oneof choice {
+        OrganizationalEntity organization = 1;
+        OrganizationalContact contact = 2;
+      }
+    }
+  }
+}
+
+enum ComponentDataType {
+  // Any type of code, code snippet, or data-as-code
+  COMPONENT_DATA_TYPE_SOURCE_CODE = 0;
+  // Parameters or settings that may be used by other components.
+  COMPONENT_DATA_TYPE_CONFIGURATION = 1;
+  // A collection of data.
+  COMPONENT_DATA_TYPE_DATASET = 2;
+  // Any other type of data that does not fit into existing definitions.
+  COMPONENT_DATA_TYPE_OTHER = 3;
+}
+
+message GraphicsCollection {
+  // A description of this collection of graphics.
+  optional string description = 1;
+  // A collection of graphics.
+  repeated Graphic graphic = 2;
+
+  message Graphic {
+    // The name of the graphic.
+    optional string name = 1;
+    // The graphic (vector or raster). Base64 encoding MUST be specified for binary images.
+    optional AttachedText image = 2;
+  }
+
 }