github.com/CycloneDX/sbom-utility@v0.16.0/schema/cyclonedx_modelcard.go (about) 1 // SPDX-License-Identifier: Apache-2.0 2 /* 3 * Licensed to the Apache Software Foundation (ASF) under one or more 4 * contributor license agreements. See the NOTICE file distributed with 5 * this work for additional information regarding copyright ownership. 6 * The ASF licenses this file to You under the Apache License, Version 2.0 7 * (the "License"); you may not use this file except in compliance with 8 * the License. You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 19 package schema 20 21 // Note: "Model card" support in CycloneDX is derived from TensorFlow Model Card Toolkit released 22 // under the Apache 2.0 license and available from: 23 // https://github.com/tensorflow/model-card-toolkit/blob/main/model_card_toolkit/schema/v0.0.2/model_card.schema.json. In addition, CycloneDX model card support includes portions of VerifyML, also released under the Apache 2.0 license and available from https://github.com/cylynx/verifyml/blob/main/verifyml/model_card_toolkit/schema/v0.0.4/model_card.schema.json.", 24 25 // v1.5: added 26 // NOTE: CDXRefType is a named `string` type as of v1.5 27 // TODO: v1.7: How to represent an AI App. (e.g., a Chatbot) using a model 28 // with components like embeddings (vector DB), re-rankers, etc. 29 // also consider distinguishing model capabilities: e.g., generative/classification; types (multi-model, LLM, LM, etc.) 30 type CDXModelCard struct { 31 BOMRef *CDXRefType `json:"bom-ref,omitempty" cdx:"+1.5"` // v1.5 32 ModelParameters *CDXModelParameters `json:"modelParameters,omitempty" cdx:"+1.5"` // v1.5 33 QuantitativeAnalysis *CDXQuantitativeAnalysis `json:"quantitativeAnalysis,omitempty" cdx:"+1.5"` // v1.5 34 Considerations *CDXConsiderations `json:"considerations,omitempty" cdx:"+1.5"` // v1.5 35 Properties *[]CDXProperty `json:"properties,omitempty" cdx:"+1.5"` // v1.5 36 } 37 38 // ======================================== 39 // Model Parameters 40 // ======================================== 41 42 // v1.5: added 43 type CDXModelParameters struct { 44 Approach *CDXApproach `json:"approach,omitempty" cdx:"+1.5"` // v1.5 45 Task string `json:"task,omitempty" cdx:"+1.5"` // v1.5 46 ArchitectureFamily string `json:"architectureFamily,omitempty" cdx:"+1.5"` // v1.5 47 ModelArchitecture string `json:"modelArchitecture,omitempty" cdx:"+1.5"` // v1.5 48 Datasets *[]CDXDataset `json:"datasets,omitempty" cdx:"+1.5"` // v1.5 49 Inputs *[]CDXInputOutputMLParameters `json:"inputs,omitempty" cdx:"+1.5"` // v1.5 50 Outputs *[]CDXInputOutputMLParameters `json:"outputs,omitempty" cdx:"+1.5"` // v1.5 51 } 52 53 // v1.5: added 54 // "Learning types describing the learning problem or hybrid learning problem." 55 // "enum": ["supervised","unsupervised","reinforcement-learning","semi-supervised","self-supervised"] 56 type CDXApproach struct { 57 Type string `json:"type,omitempty" cdx:"+1.5"` // v1.5 58 } 59 60 // v1.5: added. 61 // v1.5: Note: "ref" is a constrained "string" which can be "anyOf": ["#/definitions/refLinkType", "#/definitions/bomLinkElementType"] 62 // TODO: actually, "Ref" should be its own anonymous type with "anyOf": ["#/definitions/refLinkType", "#/definitions/bomLinkElementType"] 63 type CDXDataset struct { 64 CDXComponentData 65 Ref *CDXRefLinkType `json:"ref,omitempty" cdx:"+1.5"` // v1.5 66 } 67 68 // v1.5: added 69 // "The data format for input/output to the model. 70 // Example formats include string, image, time-series", 71 type CDXInputOutputMLParameters struct { 72 Format string `json:"format,omitempty" cdx:"+1.5"` // v1.5 73 } 74 75 // ======================================== 76 // Quantitative Analysis 77 // ======================================== 78 79 // v1.5: added (anonymous type) 80 type CDXQuantitativeAnalysis struct { 81 PerformanceMetrics *[]CDXPerformanceMetric `json:"performanceMetrics,omitempty" cdx:"+1.5"` // v1.5 82 Graphics *CDXGraphicsCollection `json:"graphics,omitempty" cdx:"+1.5"` // v1.5 83 } 84 85 // v1.5: added 86 type CDXPerformanceMetric struct { 87 Type string `json:"type,omitempty" cdx:"+1.5"` // v1.5 88 Value string `json:"value,omitempty" cdx:"+1.5"` // v1.5 89 Slice string `json:"slice,omitempty" cdx:"+1.5"` // v1.5 90 ConfidenceInterval *CDXConfidenceInterval `json:"confidenceInterval,omitempty" cdx:"+1.5"` // v1.5 91 } 92 93 // v1.5: added 94 type CDXConfidenceInterval struct { 95 LowerBound string `json:"lowerBound,omitempty" cdx:"+1.5"` // v1.5 96 UpperBound string `json:"upperBound,omitempty" cdx:"+1.5"` // v1.5 97 } 98 99 // v1.5: added 100 type CDXGraphicsCollection struct { 101 Description string `json:"description,omitempty" cdx:"+1.5"` // v1.5 102 Collection *[]CDXGraphic `json:"collection,omitempty" cdx:"+1.5"` // v1.5 103 } 104 105 // v1.5: added 106 type CDXGraphic struct { 107 Name string `json:"name,omitempty" cdx:"+1.5"` // v1.5 108 Image *CDXAttachment `json:"image,omitempty" cdx:"+1.5"` // v1.5 109 } 110 111 // ======================================== 112 // Considerations 113 // ======================================== 114 115 // v1.5: added (anonymous type) 116 // Considerations that should be taken into account regarding the model's construction, 117 // training, and application 118 type CDXConsiderations struct { 119 Users *[]string `json:"users,omitempty" cdx:"+1.5"` // v1.5 120 UseCases *[]string `json:"useCases,omitempty" cdx:"+1.5"` // v1.5 121 TechnicalLimitations *[]string `json:"technicalLimitations,omitempty" cdx:"+1.5"` // v1.5 122 PerformanceTradeoffs *[]string `json:"performanceTradeoffs,omitempty" cdx:"+1.5"` // v1.5 123 EthicalConsiderations *[]CDXRisk `json:"ethicalConsiderations,omitempty" cdx:"+1.5"` // v1.5 124 FairnessAssessments *[]CDXFairnessAssessment `json:"fairnessAssessments,omitempty" cdx:"+1.5"` // v1.5 125 EnvironmentalConsiderations *CDXEnvironmentalConsiderations `json:"environmentalConsiderations,omitempty" cdx:"+1.6"` // v1.6 126 } 127 128 // v1.5: added 129 type CDXRisk struct { 130 Name string `json:"name,omitempty" cdx:"+1.5"` // v1.5 131 MitigationStrategy string `json:"mitigationStrategy,omitempty" cdx:"+1.5"` // v1.5 132 } 133 134 // v1.5: added 135 // Information about the benefits and harms of the model to an identified at risk group. 136 type CDXFairnessAssessment struct { 137 GroupAtRisk string `json:"groupAtRisk,omitempty" cdx:"+1.5"` // v1.5 138 Benefits string `json:"benefits,omitempty" cdx:"+1.5"` // v1.5 139 Harms string `json:"harms,omitempty" cdx:"+1.5"` // v1.5 140 MitigationStrategy string `json:"mitigationStrategy,omitempty" cdx:"+1.5"` // v1.5 141 } 142 143 // v1.6: added 144 // Information about the benefits and harms of the model to an identified at risk group. 145 type CDXEnvironmentalConsiderations struct { 146 EnergyConsumptions *[]CDXEnergyConsumption `json:"energyConsumptions,omitempty" cdx:"+1.6"` // v1.6 147 Properties *[]CDXProperty `json:"properties,omitempty" cdx:"+1.6"` // v1.6 148 } 149 150 // v1.6: added 151 type CDXEnergyConsumption struct { 152 Activity string `json:"activity,omitempty" cdx:"+1.6"` // v1.6 153 EnergyProviders *[]CDXEnergyProvider `json:"energyProviders,omitempty" cdx:"+1.6"` // v1.6 154 ActivityEnergyCost *CDXEnergyMeasure `json:"activityEnergyCost,omitempty" cdx:"+1.6"` // v1.6 155 Co2CostEquivalent *CDXCo2Measure `json:"co2CostEquivalent,omitempty" cdx:"+1.6"` // v1.6 156 Co2CostOffset *CDXCo2Measure `json:"co2CostOffset,omitempty" cdx:"+1.6"` // v1.6 157 Properties *[]CDXProperty `json:"properties,omitempty" cdx:"+1.6"` // v1.6 158 } 159 160 // v1.6: added 161 type CDXEnergyMeasure struct { 162 Value float64 `json:"value,omitempty" cdx:"+1.6"` // v1.6 163 Unit string `json:"unit,omitempty" cdx:"+1.6"` // v1.6 164 } 165 166 // v1.6: added 167 type CDXCo2Measure struct { 168 Value float64 `json:"value,omitempty" cdx:"+1.6"` // v1.6 169 Unit string `json:"unit,omitempty" cdx:"+1.6"` // v1.6 170 } 171 172 // v1.6: added 173 type CDXEnergyProvider struct { 174 BOMRef *CDXRefType `json:"bom-ref,omitempty" cdx:"+1.6"` // v1.6 175 Description string `json:"description,omitempty" cdx:"+1.6"` // v1.6 176 Organization *CDXOrganizationalEntity `json:"organization,omitempty" cdx:"+1.6"` // v1.6 177 EnergySource string `json:"energySource,omitempty" cdx:"+1.6"` // v1.6 178 EnergyProvided *CDXEnergyMeasure `json:"energyProvided,omitempty" cdx:"+1.6"` // v1.6 179 ExternalReferences *[]CDXExternalReference `json:"externalReferences,omitempty" cdx:"+1.6"` // v1.6 180 } 181 182 // v1.6: added 183 type CDXPostalAddress struct { 184 BOMRef *CDXRefType `json:"bom-ref,omitempty" cdx:"+1.6"` // v1.6 185 Country string `json:"country,omitempty" cdx:"+1.6"` // v1.6 186 Region string `json:"region,omitempty" cdx:"+1.6"` // v1.6 187 Locality string `json:"locality,omitempty" cdx:"+1.6"` // v1.6 188 PostOfficeBoxNumber string `json:"postOfficeBoxNumber,omitempty" cdx:"+1.6"` // v1.6 189 PostalCode string `json:"postalCode,omitempty" cdx:"+1.6"` // v1.6 190 StreetAddress string `json:"streetAddress,omitempty" cdx:"+1.6"` // v1.6 191 }