From 3b728db68844ec15932781068689d949c3966a80 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Wed, 29 Jul 2026 14:30:54 -0500 Subject: [PATCH 1/3] Clean check-in of AI/ML. Supersedes #948. Multiple things broken so more work to do. Signed-off-by: Steve Springett --- .gitignore | 8 + .../2.0/model/cyclonedx-ai-ml-2.0.schema.json | 1803 +++++++++++++++++ 2 files changed, 1811 insertions(+) create mode 100644 schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json diff --git a/.gitignore b/.gitignore index 2628a5390..f07927786 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,11 @@ +# Filesystem +**/.DS_Store + +# Tooling .idea/ .vscode/ tools/target/ +.bob + +# UML diagrams +**/.uml/ \ No newline at end of file diff --git a/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json b/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json new file mode 100644 index 000000000..edbb81e4f --- /dev/null +++ b/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json @@ -0,0 +1,1803 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://cyclonedx.org/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json", + "type": "null", + "title": "CycloneDX AI/ML schema", + "$comment": "OWASP CycloneDX is an Ecma International standard (ECMA-424) developed in collaboration between the OWASP Foundation and Ecma Technical Committee 54 (TC54). The standard is published under a royalty-free patent policy. This JSON schema is the reference implementation and is licensed under the Apache License 2.0.", + "$defs": { + "modelCard": { + "properties": { + "bom-ref": { + "title": "BOM Reference", + "description": "An identifier which can be used to reference the model card elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + }, + "tasks": { + "type": "array", + "title": "Tasks", + "description": "The machine learning tasks that the model is designed to perform. This directly influences the model's intended use, input and output characteristics, and evaluation metrics. Models may support multiple tasks (e.g., multimodal models).", + "minItems": 1, + "uniqueItems": true, + "items": { + "$ref": "#/$defs/modelTaskType" + }, + "examples": [ + [ + "text-generation" + ], + [ + "image-classification", + "object-detection" + ], + [ + "image-to-text", + "text-to-image" + ] + ] + }, + "architecture": { + "$ref": "#/defs/modelArchitecture" + }, + "designConsiderations": { + "$ref": "#/defs/designConsiderations" + }, + "trainingProfile": { + "$ref": "#/defs/trainingProfile" + }, + "modelParameters": { + "$ref": "#/$defs/modelParameters" + }, + "quantitativeAnalysis": { + "$ref": "#/$defs/quantitativeAnalysis" + }, + "externalReferences": { + "type": "array", + "description": "External references to information relevant to the model.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "description": "Properties of the model.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } + } + }, + "modelArchitecture": { + "type": "object", + "properties": { + "architectureName": { + "type": "string", + "title": "Architecture Name", + "description": "The specific identifying name of the model architecture. This typically refers to well-known model variants or versions.", + "examples": [ + "GPT-4", + "GPT-3.5-turbo", + "Llama-3.1-70B", + "Claude-3.5-Sonnet", + "Mistral-7B-v0.3", + "ResNet-50", + "YOLOv8", + "BERT-base-uncased", + "Stable-Diffusion-XL", + "Whisper-large-v3" + ] + }, + "description": { + "type": "string", + "title": "Description", + "description": "A detailed description of the model's architecture, including key characteristics, design decisions, and architectural innovations.", + "examples": [ + "Decoder-only transformer with grouped-query attention and rotary positional embeddings, using a mixture-of-experts feed-forward layer.", + "Convolutional backbone with residual connections and a transformer head for multi-scale feature aggregation." + ] + }, + "structural": { + "type": "object", + "description": "Describes the model's primary and secondary architectural structure and network topology.", + "required": [ + "primary" + ], + "properties": { + "primary": { + "$comment": "Values not listed can be proposed to the CycloneDX Property Taxonomy.", + "type": "string", + "description": "The core mathematical structural framework of the model backbone.", + "anyOf": [ + { + "enum": [ + "transformer", + "cnn", + "rnn", + "lstm", + "gru", + "gan", + "vae", + "mamba", + "ssm", + "gnn", + "mlp", + "rwkv", + "snn", + "kan", + "diffusion", + "flow-matching", + "rbm", + "capsnet", + "neuromorphic", + "hybrid" + ], + "meta:enum": { + "transformer": "Architecture based on self-attention mechanisms for processing sequential or spatial data.", + "cnn": "Convolutional Neural Network - architecture using convolutional layers for processing grid-like data.", + "rnn": "Recurrent Neural Network - architecture with recurrent connections for sequential data processing.", + "lstm": "Long Short-Term Memory - RNN variant with gating mechanisms for long-term dependencies.", + "gru": "Gated Recurrent Unit - RNN variant with simplified gating compared to LSTM.", + "gan": "Generative Adversarial Network - dual-network framework containing a generator and a discriminator.", + "vae": "Variational Autoencoder - probabilistic encoder-decoder architecture mapping to a latent space.", + "mamba": "State-space model architecture with selective mechanisms for efficient sequence modeling.", + "ssm": "State Space Model - core architecture based on continuous or discrete state-space representations.", + "gnn": "Graph Neural Network - architecture optimized for processing graph-structured data elements.", + "mlp": "Multi-Layer Perceptron - classic feedforward architecture composed entirely of fully connected layers.", + "rwkv": "Receptive Weighted Key Value - architecture combining parallelizable training with RNN-like inference.", + "snn": "Spiking Neural Network - neuromorphic architecture utilizing discrete, time-dependent spiking activations.", + "kan": "Kolmogorov-Arnold Network - architecture featuring learnable activation functions on edges rather than nodes.", + "diffusion": "Denoising diffusion probabilistic model - iteratively refines noise into data (e.g., DDPM, Stable Diffusion).", + "flow-matching": "Continuous normalizing flow trained via flow matching / rectified flow (e.g., Flux, SD3).", + "rbm": "Restricted Boltzmann Machine - energy-based generative model with stochastic hidden units.", + "capsnet": "Capsule Network - architecture using dynamic routing between capsule groups to preserve spatial hierarchies.", + "neuromorphic": "Architecture designed for deployment on neuromorphic hardware (e.g., Intel Loihi, IBM TrueNorth).", + "hybrid": "Explicit first-class combination of two or more distinct primary architectures (e.g., CNN+Transformer)." + } + }, + { + "pattern": "^cdx:ai-ml:model:architecture:primary:[a-z0-9:-]+$" + } + ], + "examples": [ + "transformer", + "cnn", + "mamba", + "gnn", + "cdx:ai-ml:model:architecture:primary:retnet" + ] + }, + "secondary": { + "type": "array", + "description": "A list of secondary macro-layouts or component sub-networks built into the primary structure.", + "uniqueItems": true, + "items": { + "type": "string", + "anyOf": [ + { + "enum": [ + "decoder-only", + "encoder-only", + "encoder-decoder", + "mixture-of-experts", + "vae-bottleneck", + "u-net", + "residual-connections", + "dual-encoders", + "cross-attention-gated", + "siamese-network", + "hybrid-backbone", + "state-space-model", + "flow-matching", + "vision-encoder", + "adapter-layers", + "projector-layers", + "gated-linear-units", + "speculative-decoding", + "rotary-position-embedding", + "grouped-query-attention", + "sliding-window-attention", + "retrieval-augmented", + "memory-augmented", + "multimodal-fusion", + "reranker", + "other" + ], + "meta:enum": { + "decoder-only": "Autoregressive macro-layout processing data left-to-right (e.g., GPT series).", + "encoder-only": "Bidirectional macro-layout processing complete sequences simultaneously (e.g., BERT).", + "encoder-decoder": "Sequence-to-sequence structure mapping an input representation to an output sequence (e.g., T5).", + "mixture-of-experts": "Sparse routing layer mechanism activating specific expert subnetworks per token.", + "vae-bottleneck": "Symmetric compression bottleneck utilizing mean and variance latent vectors.", + "u-net": "Symmetric contracting and expanding macro-layout featuring skip connections between corresponding scales.", + "residual-connections": "Explicit skip or identity shortcuts bypassing one or more structural layers.", + "dual-encoders": "Parallel feature extraction pipelines mapping different modalities into a shared space.", + "cross-attention-gated": "Explicit sub-component routing that conditions one feature stream using another via attention mechanisms.", + "siamese-network": "Twin identical subnetworks sharing identical weights to compute similarity metrics.", + "hybrid-backbone": "Direct cascading combination of distinct primary layers (e.g., a CNN feature extractor feeding a Transformer).", + "state-space-model": "State space model architectures using selective state spaces for sequence modeling (e.g., Mamba).", + "flow-matching": "Flow-based generative model backbone using continuous normalizing flows.", + "vision-encoder": "Vision encoding component for processing image inputs in multimodal architectures (e.g., CLIP, SigLIP).", + "adapter-layers": "Parameter-efficient fine-tuning layers inserted into frozen models (e.g., LoRA, adapters).", + "projector-layers": "Cross-modal projection components bridging different modalities (e.g., Q-Former, linear projectors).", + "gated-linear-units": "Gated activation mechanisms using element-wise multiplication (e.g., GLU, SwiGLU, GeGLU).", + "speculative-decoding": "Sub-network pairing a small draft model with a large verifier model to accelerate autoregressive generation.", + "rotary-position-embedding": "Rotary Position Embedding (RoPE) sub-component encoding positional information via rotation matrices.", + "grouped-query-attention": "Grouped-Query Attention (GQA) variant sharing key/value heads across groups of query heads to reduce KV-cache size.", + "sliding-window-attention": "Attention mechanism restricting receptive field to a local sliding window (e.g., Mistral).", + "retrieval-augmented": "Explicit retrieval sub-network prepended to or integrated into the model (e.g., RAG, RETRO).", + "memory-augmented": "External or persistent memory bank integrated into the forward pass (e.g., MemGPT, Memorizing Transformers).", + "multimodal-fusion": "Layer or block that fuses representations across more than one modality (e.g., cross-modal attention, FiLM conditioning).", + "reranker": "Separate scoring / reranking head applied after an initial retrieval or generation step.", + "other": "Other secondary architectural components not covered by the predefined categories." + } + }, + { + "pattern": "^cdx:ai-ml:model:architecture:secondary:[a-z0-9:-]+$" + } + ] + }, + "examples": [ + [ + "decoder-only", + "mixture-of-experts" + ], + [ + "vae-bottleneck", + "dual-encoders" + ], + [ + "cdx:ai-ml:model:architecture:secondary:cross-modal-fusion" + ] + ] + }, + "topologyType": { + "type": "string", + "description": "Specifies the runtime parameter activation and connection structure of the network layers.", + "anyOf": [ + { + "enum": [ + "dense", + "sparse", + "dynamic", + "liquid", + "mixture-of-depths", + "early-exit", + "recurrent-hybrid" + ], + "meta:enum": { + "dense": "All or most parameters are active during inference with full connectivity between layers.", + "sparse": "Only a subset of parameters are active during inference with selective connectivity.", + "dynamic": "Parameter activation and connectivity patterns change based on input or runtime conditions.", + "liquid": "Continuously adaptive network structure with time-varying connections and activations.", + "mixture-of-depths": "Tokens are routed to different computational depths rather than different expert modules.", + "early-exit": "Inference exits at the earliest layer that meets a confidence threshold, reducing compute for easy inputs.", + "recurrent-hybrid": "Static layer layout that alternates between global attention and recurrent / SSM layers (e.g., Jamba, Zamba)." + } + }, + { + "pattern": "^cdx:ai-ml:model:architecture:topology:[a-z0-9:-]+$" + } + ], + "examples": [ + "dense", + "sparse", + "cdx:ai-ml:model:architecture:topology:structured-pruned" + ] + } + } + }, + "behavioralParadigm": { + "type": "array", + "description": "The behavioral paradigm or modeling objective specifying how the system interacts with and learns data distributions.", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "string" + }, + "examples": [ + [ + "Autoregressive", + "Instruction-Tuned" + ], + [ + "Diffusion", + "Rectified-Flow" + ], + [ + "Contrastive" + ] + ] + }, + "specializedProcessing": { + "type": "array", + "description": "The custom processing mechanisms, attention kernels, and hardware-software optimization pipelines.", + "minItems": 1, + "uniqueItems": true, + "items": { + "type": "string" + }, + "examples": [ + [ + "RoPE", + "Grouped-Query-Attention", + "FlashAttention-2" + ], + [ + "Cross-Attention", + "MMDiT-Block" + ] + ] + }, + "externalReferences": { + "type": "array", + "description": "references to external resources that describe the model architecture.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + }, + "examples": [ + [ + { + "type": "source-distribution", + "url": "https://github.com/huggingface/transformers/blob/v4.45.0/src/transformers/models/llama/modeling_llama.py", + "comment": "Hugging Face Transformers v4.45.0 implementation" + }, + { + "type": "documentation", + "url": "https://arxiv.org/abs/2407.21783", + "comment": "Architecture paper" + } + ] + ] + }, + "properties": { + "description": "Properties of the model architecture.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } + } + }, + "designConsiderations": { + "type": "object", + "properties": { + "users": { + "$todos": [ + "Discuss moving actor from blueprints schema to common schema", + "Add externalReferences to actor as these may be defined by external orgs. and their docs." + ], + "type": "array", + "title": "Users", + "description": "Who are the intended users of the model?", + "uniqueItems": true, + "items": { + "$ref": "cyclonedx-blueprint-2.0.schema.json$defs/actor" + } + }, + "useCases": { + "$todos": [ + "Add externalReferences to usecase schema object." + ], + "title": "Use Cases", + "description": "What are the intended use cases for the model?", + "$ref": "cyclonedx-usecase-2.0.schema.json#/$defs/useCases" + }, + "technicalLimitations": { + "title": "Technical limitations", + "description": "List of mathematical and physical constraints that may affect a model's accuracy, reasoning, and scalability.", + "$ref": "#/$defs/considerations" + }, + "performanceTradeoffs": { + "title": "Performance Tradeoffs", + "description": "What are the known tradeoffs in accuracy/performance of the model?", + "$ref": "#/$defs/considerations" + }, + "ethicalConsiderations": { + "title": "Ethical Considerations", + "description": "What are the ethical risks involved in the application of this model?", + "$ref": "#/$defs/considerations" + }, + "environmentalConsiderations": { + "title": "Environmental Considerations", + "description": "What are the various environmental impacts the corresponding machine learning model has exhibited across its lifecycle?", + "$ref": "#/$defs/environmentalConsiderations" + }, + "fairnessAssessments": { + "title": "Fairness Assessments", + "description": "What are the fairness assessments and bias evaluations that have been performed on the model?", + "$ref": "#/$defs/considerations" + }, + "externalReferences": { + "type": "array", + "description": "External references provide a way to document systems, sites, and information that may be relevant but are not included with the BOM.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "type": "array", + "title": "Properties", + "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" + } + } + } + }, + "riskGroup": { + "type": "object", + "$todos": [ + "Verify riskDomain type enum. has all the values we need for EU AI Act.", + "We always want a group name, description to qualify the type (and we may have multiples of the same type), but riskDomain uses OneOf logic for custom domains.", + "Note: if we could extend domains using the AI/ML prop. tax., we perhaps could settle just for the type field" + ], + "description": "Provides a means of expressing a design, runtime or other consideration for a specific aspect of the model. The risk group can be referenced elsewhere in the BOM using its bom-ref.", + "additionalProperties": false, + "required": [ + "groupName" + ], + "allOf": [ + { + "$ref": "cyclonedx-risk-2.0.schema.json/$defs/riskDomain" + } + ], + "properties": { + "bom-ref": { + "title": "BOM Reference", + "description": "An identifier which can be used to reference the risk group elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + }, + "groupName": { + "type": "string", + "title": "Group Name", + "description": "The name of the group at risk.", + "examples": [ + "Elderly users", + "Non-native speakers", + "People with visual impairments", + "Low-income households" + ] + }, + "groupDescription": { + "type": "string", + "title": "Group Description", + "description": "A description of the group at risk.", + "examples": [ + "Users aged 65 and over who may have reduced digital literacy or accessibility needs.", + "Users whose primary language differs from the model's primary training language.", + "Individuals relying on assistive technologies such as screen readers." + ] + }, + "externalReferences": { + "type": "array", + "description": "References to external resources that describe the risk group.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "description": "Properties of the risk group.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } + }, + "examples": [ + { + "bom-ref": "risk-group-1", + "groupName": "Elderly users", + "groupDescription": "Users aged 65 and over who may have reduced digital literacy or accessibility needs." + }, + { + "bom-ref": "risk-group-2", + "groupName": "Non-native speakers", + "groupDescription": "Users whose primary language differs from the model's training language." + } + ] + }, + "riskGroupReference": { + "type": "object", + "title": "Risk Group Reference Choice", + "description": "A reference to either a risk group object or a risk group defined elsewhere in the BOM.", + "additionalProperties": false, + "properties": { + "riskGroupRef": { + "title": "Risk Group Reference", + "description": "References a risk group by its bom-ref attribute or provides a full risk group object.", + "oneOf": [ + { + "title": "Risk Group", + "$ref": "#/$defs/riskGroup" + }, + { + "title": "Risk Group Reference", + "description": "Reference to a risk group defined elsewhere in the BOM.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + } + ] + } + } + }, + "riskGroups": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/$defs/riskGroupReference" + } + }, + "consideration": { + "$todos": [ + "Determine if we want all fields from risk or a subset.", + "Determine if a consideration can be either a risk or an assessment from the risk schema (or can an assessment optionally reference a risk or vice-versa as is implied)." + ], + "type": "object", + "description": "Provides a means of expressing a design, runtime or other consideration for a specific aspect of the model relative to a percieved risk.", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the consideration.", + "examples": [ + "Hallucination in low-resource languages", + "Gender bias in occupational classification", + "Latency under high concurrency", + "Energy cost of fine-tuning" + ] + }, + "description": { + "type": "string", + "title": "Description", + "description": "The general description of the consideration.", + "examples": [ + "The model may produce factually incorrect outputs when prompted in languages underrepresented in the training corpus.", + "Classification accuracy for professional roles has been observed to vary by perceived gender of the subject." + ] + }, + "groupsAtRisk": { + "type": "array", + "title": "Groups At Risk", + "description": "The groups at risk of being systematically disadvantaged by the model.", + "$ref": "#/$defs/riskGroups" + }, + "benefits": { + "type": "string", + "title": "Benefits", + "description": "Expected benefits to the identified groups at risk.", + "examples": [ + "Improved accessibility through multilingual support reduces language barriers for non-native speakers.", + "Automated screening may reduce time-to-decision for applicants in under-served regions." + ] + }, + "harms": { + "type": "string", + "title": "Harms", + "description": "Expected harms to the identified groups at risk.", + "examples": [ + "Model outputs may reinforce occupational stereotypes, leading to discriminatory hiring outcomes for women in STEM.", + "Reduced accuracy for accented speech may cause misrecognition for non-native English speakers." + ] + }, + "risk": { + "$ref": "cyclonedx-risk-2.0.schema.json#/$defs/risk" + }, + "assessment": { + "$ref": "cyclonedx-risk-2.0.schema.json#/$defs/assessment" + }, + "externalReferences": { + "type": "array", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } + } + }, + "considerations": { + "type": "array", + "uniqueItems": true, + "items": { + "$ref": "#/$defs/consideration" + } + }, + "datasetReference": { + "type": "object", + "title": "Dataset Reference Choice", + "additionalProperties": false, + "properties": { + "dataRef": { + "title": "Dataset Reference", + "type": "string", + "description": "References a data component by the components bom-ref attribute", + "anyOf": [ + { + "title": "Data Component Reference", + "$ref": "#/$defs/cyclonedx-common-2.0/$defs/refLinkType" + }, + { + "title": "Data BOM, BOM-Link Reference", + "$ref": "#/$defs/cyclonedx-common-2.0/$defs/bomLinkElementType" + } + ], + "examples": [ + "training-dataset-1", + "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#openwebtext-subset" + ] + } + } + }, + "datasetProcessingSpec": { + "type": "object", + "description": "Dataset processing formula including collection parameters and methodological choices used to transform data components into the subject dataset for compliance transparency.", + "properties": { + "datasets": { + "type": "array", + "title": "Datasets", + "description": "An array of dataset references.", + "items": { + "$ref": "#/$defs/datasetReference" + } + }, + "datasetProcessingFormula": { + "title": "Dataset Processing Formula", + "description": "A reference to the dataset processing formula.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + }, + "externalReferences": { + "type": "array", + "description": "External references provide a way to document systems, sites, and information that may be relevant but are not included with the BOM.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "type": "array", + "title": "Properties", + "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" + } + } + } + }, + "trainingProfile": { + "type": "object", + "description": "Information about the data and datasets used for training or finetuning the associated model.", + "properties": { + "trainingFormula":{ + "type":"object", + "title":"Training Formula", + "description":"The training formula for the model, with sequenced phases (tasks) such as pre-training, supervised fine-tuning (SFT) and alignment tuning, using the declared training datasets.", + "properties": { + "formulaRef": { + "title": "BOM Reference", + "description": "A reference the formula defined elsewhere in the BOM.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + } + } + }, + "dataProcessingSpecs": { + "type": "array", + "title": "Data Processing Specifications", + "description": "An array of data processing specifications.", + "items": { + "$ref": "#/$defs/datasetProcessingSpec" + } + }, + "trainingDatasets": { + "type": "array", + "items": { + "$ref": "#/$defs/datasetReference" + } + } + } + }, + "environmentalConsiderations": { + "type": "object", + "title": "Environmental Considerations", + "description": "Describes various environmental impact metrics.", + "additionalProperties": false, + "properties": { + "energyConsumptions": { + "title": "Energy Consumptions", + "description": "Describes energy consumption information incurred for one or more component lifecycle activities.", + "type": "array", + "items": { + "$ref": "#/$defs/energyConsumption" + } + }, + "properties": { + "type": "array", + "title": "Properties", + "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" + } + } + } + }, + "energyConsumption": { + "title": "Energy consumption", + "description": "Describes energy consumption information incurred for the specified lifecycle activity.", + "type": "object", + "required": [ + "activity", + "energyProviders", + "activityEnergyCost" + ], + "additionalProperties": false, + "properties": { + "activity": { + "$comment": "TODO: allow for values from the CycloneDX Property Taxonomy in other domains.", + "title": "Activity", + "description": "The type of activity that is part of a machine learning model development or operational lifecycle.", + "type": "string", + "anyOf": [ + { + "enum": [ + "design", + "data-collection", + "data-preparation", + "training", + "fine-tuning", + "validation", + "deployment", + "inference" + ], + "meta:enum": { + "design": "A model design including problem framing, goal definition and algorithm selection.", + "data-collection": "Model data acquisition including search, selection and transfer.", + "data-preparation": "Model data preparation including data cleaning, labeling and conversion.", + "training": "Model building, training and generalized tuning.", + "fine-tuning": "Refining a trained model to produce desired outputs for a given problem space.", + "validation": "Model validation including model output evaluation and testing.", + "deployment": "Explicit model deployment to a target hosting infrastructure.", + "inference": "Generating an output response from a hosted model from a set of inputs." + } + }, + { + "pattern": "^cdx:[a-z0-9:-]+$" + } + ], + "examples": [ + "training", + "fine-tuning", + "inference" + ] + }, + "energyProviders": { + "title": "Energy Providers", + "description": "The provider(s) of the energy consumed by the associated model development lifecycle activity.", + "type": "array", + "items": { + "$ref": "#/$defs/energyProvider" + } + }, + "activityEnergyCost": { + "title": "Activity Energy Cost", + "description": "The total energy cost associated with the model lifecycle activity.", + "$ref": "#/$defs/energyMeasure" + }, + "co2CostEquivalent": { + "title": "CO2 Equivalent Cost", + "description": "The CO2 cost (debit) equivalent to the total energy cost.", + "$ref": "#/$defs/co2Measure" + }, + "co2CostOffset": { + "title": "CO2 Cost Offset", + "description": "The CO2 offset (credit) for the CO2 equivalent cost.", + "$ref": "#/$defs/co2Measure" + }, + "properties": { + "type": "array", + "title": "Properties", + "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" + } + } + } + }, + "timeUnits": { + "enum": ["ns", "μs", "ms", "s", "min", "h"], + "meta:enum": { + "ns": "Nanoseconds - commonly used for high-precision timing measurements.", + "μs": "Microseconds - commonly used for fine-grained latency measurements.", + "ms": "Milliseconds - commonly used for latency measurements.", + "s": "Seconds - commonly used for latency and duration measurements.", + "min": "Minutes - commonly used for duration measurements.", + "h": "Hours - commonly used for duration measurements." + } + }, + "throughputUnits": { + "enum": ["tokens/s", "requests/s", "ops/s"], + "meta:enum": { + "tokens/s": "Tokens per second - commonly used for LLM throughput measurements.", + "requests/s": "Requests per second - commonly used for API and service throughput measurements.", + "ops/s": "Operations per second - commonly used for general throughput measurements." + } + }, + "computeUnits": { + "enum": ["FLOPS", "GFLOPS", "TFLOPS", "PFLOPS"], + "meta:enum": { + "FLOPS": "Floating-point operations per second.", + "GFLOPS": "Billion (giga) floating-point operations per second.", + "TFLOPS": "Trillion (tera) floating-point operations per second.", + "PFLOPS": "Quadrillion (peta) floating-point operations per second." + } + }, + "memoryUnits": { + "enum": ["B", "KB", "MB", "GB", "TB", "PB", "KiB", "MiB", "GiB", "TiB", "PiB"], + "meta:enum": { + "B": "Bytes", + "KB": "Kilobytes", + "MB": "Megabytes", + "GB": "Gigabytes", + "TB": "Terabytes", + "PB": "Petabytes", + "KiB": "Kibibytes", + "MiB": "Mebibytes", + "GiB": "Gibibytes", + "TiB": "Tebibytes", + "PiB": "Pebibytes" + } + }, + "ratioUnits": { + "enum": ["%", "ppm"], + "meta:enum": { + "%": "Percentage value (0-100) - commonly used for accuracy, precision, recall, and other ratio-based metrics.", + "ppm": "Parts per million - a dimensionless unit expressing the ratio of one part per million parts." + } + }, + "energyUnits": { + "enum": ["kWh"], + "meta:enum": { + "kWh": "Kilowatt-hour (kWh) is the energy delivered by one kilowatt (kW) of power for one hour (h)." + } + }, + "co2Units": { + "enum": ["tCO2eq"], + "meta:enum": { + "tCO2eq": "Tonnes (t) of carbon dioxide (CO2) equivalent (eq)." + } + }, + "customUnitPattern": { + "pattern": "^cdx:[a-z0-9:-]+$" + }, + "measure": { + "type": "object", + "title": "Measure", + "description": "A generic measurement with a value and unit.", + "required": [ + "value", + "unit" + ], + "additionalProperties": false, + "properties": { + "value": { + "type": "number", + "title": "Value", + "description": "The numeric value of the measurement.", + "examples": [127, 0.87, 2500, 52.3, 1.4] + }, + "unit": { + "type": "string", + "title": "Unit", + "description": "The unit of measurement.", + "anyOf": [ + {"$ref": "#/$defs/timeUnits"}, + {"$ref": "#/$defs/throughputUnits"}, + {"$ref": "#/$defs/computeUnits"}, + {"$ref": "#/$defs/memoryUnits"}, + {"$ref": "#/$defs/ratioUnits"}, + {"$ref": "#/$defs/energyUnits"}, + {"$ref": "#/$defs/co2Units"}, + {"$ref": "#/$defs/customUnitPattern"} + ], + "examples": [ + "ms", + "%", + "tokens/s", + "GB", + "kWh", + "tCO2eq" + ] + } + } + }, + "energyMeasure": { + "type": "object", + "title": "Energy Measure", + "description": "A measure of energy.", + "$comment": "The unit property is intentionally constrained to 'kWh' only (not extensible) as energy measurements require standardized units for accurate comparison and reporting.", + "allOf": [ + { + "$ref": "#/$defs/measure" + }, + { + "properties": { + "unit": {"$ref": "#/$defs/energyUnits"} + } + } + ] + }, + "co2Measure": { + "type": "object", + "title": "CO2 Measure", + "description": "A measure of carbon dioxide (CO2).", + "$comment": "The unit property is intentionally constrained to 'tCO2eq' only (not extensible) as carbon emissions require standardized units for accurate environmental impact reporting.", + "allOf": [ + { + "$ref": "#/$defs/measure" + }, + { + "properties": { + "unit": {"$ref": "#/$defs/co2Units"} + } + } + ] + }, + "performanceMeasure": { + "type": "object", + "title": "Performance Measure", + "description": "A measure of performance with a value and unit.", + "$comment": "The unit property is extensible using the '^cdx:' pattern to accommodate diverse performance metrics across different AI/ML systems and use cases.", + "allOf": [ + { + "$ref": "#/$defs/measure" + }, + { + "properties": { + "unit": { + "anyOf": [ + {"$ref": "#/$defs/timeUnits"}, + {"$ref": "#/$defs/throughputUnits"}, + {"$ref": "#/$defs/computeUnits"}, + {"$ref": "#/$defs/memoryUnits"}, + {"$ref": "#/$defs/ratioUnits"}, + {"$ref": "#/$defs/customUnitPattern"} + ] + } + } + } + ] + }, + "energyProvider": { + "type": "object", + "title": "Energy Provider", + "description": "Describes the physical provider of energy used for model development or operations.", + "required": [ + "organization", + "energySource", + "energyProvided" + ], + "additionalProperties": false, + "properties": { + "bom-ref": { + "title": "BOM Reference", + "description": "An identifier which can be used to reference the energy provider elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the energy provider." + }, + "organization": { + "type": "object", + "title": "Organization", + "description": "The organization that provides energy.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/organizationalEntity" + }, + "energySource": { + "$comment": "TODO: allow for other values not listed to be proposed to the CycloneDX Property Taxonomy.", + "title": "Energy Source", + "description": "The energy source for the energy provider.", + "type": "string", + "anyOf": [ + { + "enum": [ + "coal", + "oil", + "natural-gas", + "nuclear", + "wind", + "solar", + "geothermal", + "hydropower", + "biofuel", + "biomass", + "hydrogen", + "tidal", + "unknown" + ], + "meta:enum": { + "coal": "Energy produced by types of coal.", + "oil": "Petroleum products (primarily crude oil and its derivative fuel oils).", + "natural-gas": "Hydrocarbon gas liquids (HGL) that occur as gases at atmospheric pressure and as liquids under higher pressures including Natural gas (C5H12 and heavier), Ethane (C2H6), Propane (C3H8), etc.", + "nuclear": "Energy produced from the cores of atoms (i.e., through nuclear fission or fusion).", + "wind": "Energy produced from moving air.", + "solar": "Energy produced from the sun (i.e., solar radiation).", + "geothermal": "Energy produced from heat within the earth.", + "hydropower": "Energy produced from flowing water.", + "biofuel": "Liquid fuels produced from biomass feedstocks (i.e., organic materials such as plants or animals).", + "biomass": "Energy produced from solid organic materials such as wood, agricultural crops, or organic waste.", + "hydrogen": "Energy produced from hydrogen fuel, which can be used in fuel cells or combustion.", + "tidal": "Energy produced from the rise and fall of ocean tides and tidal currents.", + "unknown": "The energy source is unknown." + } + }, + { + "pattern": "^cdx:[a-z0-9:-]+$" + } + ], + "examples": [ + "solar", + "wind", + "natural-gas", + "nuclear" + ] + }, + "energyProvided": { + "$ref": "#/$defs/energyMeasure", + "title": "Energy Provided", + "description": "The energy provided by the energy source for an associated activity." + }, + "externalReferences": { + "type": "array", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + }, + "title": "External References", + "description": "External references provide a way to document systems, sites, and information that may be relevant but are not included with the BOM. They may also establish specific relationships within or external to the BOM." + } + } + }, + "graphic": { + "$todos": [ + "Unsure if needed for 2.0. If so, is there a common object we can reuse?" + ], + "type": "object", + "title": "Graphic", + "additionalProperties": false, + "properties": { + "name": { + "title": "Name", + "description": "The name of the graphic.", + "type": "string" + }, + "image": { + "title": "Graphic Image", + "description": "The graphic (vector or raster). Base64 encoding must be specified for binary images.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/attachment" + } + } + }, + "performanceMetric": { + "type": "object", + "title": "Performance Metric", + "$comment": "Values not listed can be proposed to the CycloneDX Property Taxonomy.", + "$todos": [ + "Update AI/ML property taxonomy with performance metric type enum values." + ], + "additionalProperties": false, + "properties": { + "type": { + "title": "Type", + "description": "The type of performance metric used for AI model evaluation.", + "type": "string", + "anyOf": [ + { + "enum": [ + "mmlu-pro", + "gpqa", + "math-500", + "humaneval", + "swe-bench", + "terminal-bench", + "gdpval", + "browsecomp", + "bfcl", + "taubench", + "ifeval", + "livebench", + "webarena", + "lmsys-elo", + "strongreject", + "perplexity", + "bleu", + "rouge", + "latency", + "throughput", + "coco", + "vqa", + "imagenet" + ], + "meta:enum": { + "mmlu-pro": "Massive Multitask Language Understanding Pro - The current standard for broad, expert-level academic and professional reasoning across multiple disciplines.", + "gpqa": "Graduate-Level Google-Proof Q&A - A highly difficult dataset used to test advanced, PhD-level reasoning and scientific problem-solving capabilities.", + "math-500": "A subset of the MATH benchmark used to evaluate complex, multi-step mathematical reasoning and logic.", + "humaneval": "The industry standard benchmark for evaluating Python code generation and functional programming synthesis.", + "swe-bench": "Software Engineering Benchmark - Evaluates a model's agentic ability to resolve real-world software engineering issues and patches within complete, live code repositories.", + "terminal-bench": "Terminal-Bench - Evaluates an agent's ability to complete long-horizon, autonomous tasks inside a real shell environment, covering system administration, DevOps, and software engineering workflows.", + "gdpval": "GDPVal - A cross-domain general performance validation benchmark measuring an agent's instruction-following, tool-use, and reasoning fidelity across diverse real-world tasks.", + "browsecomp": "BrowseComp - OpenAI's benchmark for evaluating an agent's ability to answer hard, multi-hop research questions that require deep, autonomous web browsing to resolve.", + "bfcl": "Berkeley Function-Calling Leaderboard - Evaluates a model's ability to correctly call external tools and APIs by selecting the right function and generating accurate, schema-conformant arguments.", + "taubench": "τ-bench (TauBench) - An agentic benchmark assessing a model's ability to complete multi-step, tool-augmented tasks in simulated real-world domains such as retail and airline customer service.", + "ifeval": "Instruction Following Evaluation - Tests a model's ability to strictly adhere to verifiable formatting constraints (e.g., specific word counts, starting sentences with specific words).", + "livebench": "A frequently updated, contamination-free benchmark designed to test reasoning, math, and coding without the risk of models memorizing static test data.", + "webarena": "An agentic benchmark evaluating a model's ability to perform complex, multi-step tasks using a web browser, APIs, and OS environments.", + "lmsys-elo": "A crowd-sourced human preference rating derived from millions of blind A/B battle tests in the LMSYS Chatbot Arena.", + "strongreject": "A standardized metric for measuring safety and alignment by evaluating how reliably a model refuses harmful prompts while avoiding false positives.", + "perplexity": "A fundamental language model metric measuring how well a probability model predicts a sample. Lower perplexity indicates better prediction.", + "bleu": "Bilingual Evaluation Understudy - A metric for evaluating machine translation quality by comparing generated text to reference translations.", + "rouge": "Recall-Oriented Understudy for Gisting Evaluation - A set of metrics for evaluating automatic summarization and machine translation by comparing overlap with reference texts.", + "latency": "The time delay between input submission and output generation, typically measured in milliseconds or seconds. Critical for real-time applications.", + "throughput": "The rate at which a model processes requests or tokens, typically measured in tokens per second or requests per second.", + "coco": "Common Objects in Context - A large-scale object detection, segmentation, and captioning dataset used to evaluate computer vision models.", + "vqa": "Visual Question Answering - Evaluates a model's ability to answer questions about images, testing multimodal understanding.", + "imagenet": "A large visual database designed for visual object recognition research, commonly used to benchmark image classification models." + } + }, + { + "pattern": "^cdx:ai-ml:model:metric:performance:[a-z0-9:-]+$" + } + ], + "examples": [ + "mmlu-pro", + "humaneval", + "swe-bench" + ] + }, + "measure": { + "title": "Measure", + "description": "The measured value of the performance metric with its unit.", + "$ref": "#/$defs/performanceMeasure" + }, + "slice": { + "title": "Slice", + "description": "The name of the slice this metric was computed on. By default, assume this metric is not sliced.", + "type": "string", + "examples": [ + "overall", + "age:18-34", + "language:fr", + "gender:female", + "region:sub-saharan-africa" + ] + }, + "confidenceInterval": { + "title": "Confidence Interval", + "description": "The confidence interval of the metric.", + "type": "object", + "additionalProperties": false, + "properties": { + "lowerBound": { + "title": "Lower Bound", + "description": "The lower bound of the confidence interval.", + "type": "string" + }, + "upperBound": { + "title": "Upper Bound", + "description": "The upper bound of the confidence interval.", + "type": "string" + } + } + }, + "evaluationDatasets": { + "type": "array", + "title": "Evaluation Datasets", + "description": "References to the datasets or dataset subsets used to compute this performance metric.", + "items": { + "$ref": "#/$defs/datasetReference" + } + }, + "externalReferences": { + "type": "array", + "title": "External References", + "description": "External references to well-known AI model evaluations, benchmarks, leaderboards, or evaluation methodologies.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "type": "array", + "title": "Properties", + "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" + } + } + }, + "examples": [ + { + "type": "mmlu-pro", + "measure": { + "value": 58.2, + "unit": "%" + }, + "confidenceInterval": { + "lowerBound": "57.48", + "upperBound": "58.92" + } + }, + { + "type": "humaneval", + "measure": { + "value": 0.87, + "unit": "%" + } + }, + { + "type": "swe-bench", + "measure": { + "value": 45.3, + "unit": "%" + }, + "evaluationDatasets": [ + { + "dataRef": "data-ref:swe-bench-lite-dataset" + } + ], + "externalReferences": [ + { + "type": "distribution", + "url": "https://huggingface.co/datasets/princeton-nlp/SWE-bench_Lite" + } + ] + }, + { + "type": "latency", + "measure": { + "value": 127, + "unit": "ms" + }, + "properties": [ + { + "name": "percentile", + "value": "p95" + }, + { + "name": "hardware", + "value": "NVIDIA A100 GPU" + } + ] + }, + { + "type": "throughput", + "measure": { + "value": 2500, + "unit": "tokens/s" + }, + "properties": [ + { + "name": "batch-size", + "value": "32" + }, + { + "name": "hardware", + "value": "NVIDIA A100 GPU" + } + ] + }, + { + "type": "coco", + "measure": { + "value": 52.3, + "unit": "percentage" + }, + "properties": [ + { + "name": "metric", + "value": "mAP" + }, + { + "name": "iou-threshold", + "value": "0.5" + } + ], + "externalReferences": [ + { + "type": "distribution", + "url": "https://cocodataset.org/" + } + ] + }, + { + "type": "bleu", + "measure": { + "value": 34.5, + "unit": "percentage" + }, + "properties": [ + { + "name": "variant", + "value": "BLEU-4" + }, + { + "name": "per-class-precision-1", + "value": "0.78" + }, + { + "name": "per-class-precision-2", + "value": "0.52" + }, + { + "name": "per-class-precision-3", + "value": "0.38" + }, + { + "name": "per-class-precision-4", + "value": "0.29" + }, + { + "name": "brevity-penalty", + "value": "0.95" + } + ] + } + ] + }, + "quantitativeAnalysis": { + "type": "object", + "title": "Quantitative Analysis", + "description": "A quantitative analysis of the model", + "additionalProperties": false, + "properties": { + "performanceMetrics": { + "type": "array", + "title": "Performance Metrics", + "description": "The model performance metrics being reported. Examples may include accuracy, F1 score, precision, top-3 error rates, MSC, etc.", + "items": { "$ref": "#/definitions/performanceMetric" } + }, + "graphics": { "$ref": "#/definitions/graphicsCollection" } + } + }, + "modelParameters": { + "type": "object", + "title": "Model Parameters", + "description": "Describes the input and output parameters of an AI model, including support for various modalities and data formats.", + "additionalProperties": false, + "properties": { + "inputs": { + "type": "array", + "title": "Model Inputs", + "description": "The input parameters accepted by the model.", + "items": { + "$ref": "#/$defs/modelParameter" + }, + "uniqueItems": true + }, + "outputs": { + "type": "array", + "title": "Model Outputs", + "description": "The output parameters produced by the model.", + "items": { + "$ref": "#/$defs/modelParameter" + }, + "uniqueItems": true + }, + "properties": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } + } + }, + "modelParameter": { + "type": "object", + "title": "Model Parameter", + "description": "Describes a single input or output parameter of an AI model, supporting various modalities and encoding formats.", + "additionalProperties": false, + "required": [ + "name" + ], + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the parameter.", + "examples": [ + "prompt", + "image", + "audio", + "logits", + "embeddings" + ] + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the parameter and its purpose." + }, + "modality": { + "type": "string", + "title": "Modality", + "description": "The type of data modality for this parameter.", + "anyOf": [ + { + "enum": [ + "text", + "image", + "audio", + "video", + "multimodal", + "embedding", + "logits", + "other" + ], + "meta:enum": { + "text": "Natural language text input or output.", + "image": "Visual image data input or output.", + "audio": "Audio or speech data input or output.", + "video": "Video data input or output.", + "multimodal": "Combined multiple modalities (e.g., text and image).", + "embedding": "Dense vector representations in a continuous space.", + "logits": "Raw unnormalized model outputs before activation functions.", + "other": "Other modality types not explicitly listed." + } + }, + { + "pattern": "^cdx:ai-ml:model:task:[a-z0-9:-]+$" + } + ], + "examples": [ + "text", + "image", + "audio", + "logits" + ] + }, + "format": { + "type": "object", + "title": "Format", + "$comment": "TODO: There should be a common place in the CycloneDX Property Taxonomy to define encoding types", + "description": "Describes the format and encoding of the parameter data.", + "additionalProperties": false, + "properties": { + "dataType": { + "type": "string", + "title": "Data Type", + "description": "The data type of the parameter.", + "examples": [ + "string", + "float32", + "fp16", + "bf16", + "int64", + "uint8", + "q8_0" + ] + }, + "encoding": { + "type": "string", + "title": "Encoding", + "description": "The encoding format of the parameter data.", + "anyOf": [ + { + "enum": [ + "utf-8", + "ascii", + "base64", + "jpeg", + "png", + "wav", + "mp3", + "flac", + "raw", + "tokenized", + "other" + ], + "meta:enum": { + "utf-8": "UTF-8 text encoding.", + "ascii": "ASCII text encoding.", + "base64": "Base64 encoded binary data.", + "jpeg": "JPEG image format.", + "png": "PNG image format.", + "wav": "WAV audio format.", + "mp3": "MP3 audio format.", + "flac": "FLAC lossless audio format.", + "raw": "Raw binary data without specific encoding.", + "tokenized": "Pre-tokenized input (token IDs).", + "other": "Other encoding format not explicitly listed." + } + }, + { + "pattern": "^cdx:ai-ml:[a-z0-9:-]+$" + } + ], + "examples": [ + "utf-8", + "tokenized", + "jpeg", + "wav" + ] + }, + "mimeType": { + "type": "string", + "title": "MIME Type", + "description": "The MIME type of the parameter data.", + "examples": [ + "text/plain", + "image/jpeg", + "audio/wav", + "application/octet-stream" + ] + } + } + }, + "shape": { + "type": "array", + "title": "Shape", + "description": "The dimensional shape of the parameter (e.g., tensor dimensions). Use -1 or null for dynamic dimensions.", + "items": { + "oneOf": [ + { + "type": "integer", + "minimum": -1 + }, + { + "type": "null" + } + ] + }, + "examples": [ + [1, 512], + [null, 3, 224, 224], + [-1, 768] + ] + }, + "processingStage": { + "type": "string", + "title": "Processing Stage", + "description": "Indicates the processing stage of the parameter relative to tokenization or encoding.", + "enum": [ + "pre-tokenizer", + "post-tokenizer", + "pre-encoder", + "post-encoder", + "raw", + "processed" + ], + "meta:enum": { + "pre-tokenizer": "Data before tokenization (e.g., raw text string).", + "post-tokenizer": "Data after tokenization (e.g., token IDs).", + "pre-encoder": "Data before encoding transformation.", + "post-encoder": "Data after encoding transformation.", + "raw": "Raw unprocessed data.", + "processed": "Fully processed data ready for model consumption or output." + }, + "examples": [ + "pre-tokenizer", + "post-tokenizer", + "raw" + ] + }, + "required": { + "type": "boolean", + "title": "Required", + "description": "Indicates whether this parameter is required.", + "default": false + }, + "defaultValue": { + "type": "string", + "title": "Default Value", + "description": "The default value for the parameter if not provided." + }, + "constraints": { + "type": "object", + "title": "Constraints", + "description": "Constraints on the parameter values.", + "additionalProperties": false, + "properties": { + "minLength": { + "type": "integer", + "title": "Minimum Length", + "description": "Minimum length for text or sequence parameters.", + "minimum": 0 + }, + "maxLength": { + "type": "integer", + "title": "Maximum Length", + "description": "Maximum length for text or sequence parameters.", + "minimum": 0 + }, + "minValue": { + "type": "number", + "title": "Minimum Value", + "description": "Minimum numeric value." + }, + "maxValue": { + "type": "number", + "title": "Maximum Value", + "description": "Maximum numeric value." + }, + "allowedValues": { + "type": "array", + "title": "Allowed Values", + "description": "List of allowed values for the parameter.", + "items": { + "type": "string" + } + }, + "pattern": { + "type": "string", + "title": "Pattern", + "description": "Regular expression pattern for validating string parameters." + } + } + }, + "externalReferences": { + "type": "array", + "title": "External References", + "description": "External references to documentation or specifications for this parameter.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } + }, + "examples": [ + { + "name": "prompt", + "description": "Text prompt input to the model", + "modality": "text", + "format": { + "dataType": "string", + "encoding": "utf-8" + }, + "processingStage": "pre-tokenizer", + "required": true + }, + { + "name": "input_ids", + "description": "Tokenized input IDs", + "modality": "text", + "format": { + "dataType": "int64", + "encoding": "tokenized" + }, + "shape": [1, null], + "processingStage": "post-tokenizer", + "required": true + }, + { + "name": "image", + "description": "Input image", + "modality": "image", + "format": { + "dataType": "uint8", + "encoding": "jpeg", + "mimeType": "image/jpeg" + }, + "shape": [null, 3, 224, 224], + "required": true + }, + { + "name": "audio", + "description": "Audio waveform input", + "modality": "audio", + "format": { + "dataType": "float32", + "encoding": "wav", + "mimeType": "audio/wav" + }, + "shape": [1, null], + "required": true + }, + { + "name": "logits", + "description": "Raw model output logits", + "modality": "logits", + "format": { + "dataType": "fp16" + }, + "shape": [1, null, 50257], + "processingStage": "raw" + }, + { + "name": "generated_text", + "description": "Generated text output", + "modality": "text", + "format": { + "dataType": "string", + "encoding": "utf-8" + }, + "processingStage": "post-tokenizer" + } + ] + }, + "modelTaskType": { + "$comment": "Values not listed can be proposed to the CycloneDX Property Taxonomy.", + "$todos": [ + "Update AI/ML property taxonomy with task enum values." + ], + "type": "string", + "title": "Task Type", + "description": "A machine learning task that a model is designed to perform.", + "anyOf": [ + { + "enum": [ + "text-generation", + "text-classification", + "token-classification", + "question-answering", + "summarization", + "translation", + "text-to-text", + "fill-mask", + "sentence-similarity", + "text-to-image", + "text-to-video", + "text-to-audio", + "text-to-speech", + "image-classification", + "image-segmentation", + "object-detection", + "image-to-image", + "image-to-text", + "depth-estimation", + "video-classification", + "audio-classification", + "automatic-speech-recognition", + "audio-to-audio", + "voice-activity-detection", + "tabular-classification", + "tabular-regression", + "time-series-forecasting", + "reinforcement-learning", + "robotics", + "graph-ml", + "feature-extraction", + "embedding", + "zero-shot-classification", + "few-shot-learning", + "other" + ], + "meta:enum": { + "text-generation": "Generate coherent text continuations from prompts (e.g., GPT models).", + "text-classification": "Classify text into predefined categories (e.g., sentiment analysis, topic classification).", + "token-classification": "Classify individual tokens in text (e.g., named entity recognition, part-of-speech tagging).", + "question-answering": "Answer questions based on context or knowledge (e.g., extractive or generative QA).", + "summarization": "Generate concise summaries of longer text documents.", + "translation": "Translate text from one language to another.", + "text-to-text": "Transform text from one form to another (e.g., paraphrasing, style transfer).", + "fill-mask": "Predict masked tokens in text (e.g., BERT-style masked language modeling).", + "sentence-similarity": "Compute semantic similarity between text sequences.", + "text-to-image": "Generate images from text descriptions (e.g., DALL-E, Stable Diffusion).", + "text-to-video": "Generate video content from text descriptions.", + "text-to-audio": "Generate audio or music from text descriptions.", + "text-to-speech": "Convert text to spoken audio (speech synthesis).", + "image-classification": "Classify images into predefined categories (e.g., ResNet, ViT).", + "image-segmentation": "Segment images into regions or objects (semantic or instance segmentation).", + "object-detection": "Detect and localize objects in images (e.g., YOLO, R-CNN).", + "image-to-image": "Transform images (e.g., style transfer, super-resolution, inpainting).", + "image-to-text": "Generate text descriptions from images (e.g., image captioning).", + "depth-estimation": "Estimate depth information from images.", + "video-classification": "Classify video content into categories.", + "audio-classification": "Classify audio into categories (e.g., sound event detection).", + "automatic-speech-recognition": "Transcribe spoken audio to text (e.g., Whisper).", + "audio-to-audio": "Transform audio (e.g., noise reduction, voice conversion).", + "voice-activity-detection": "Detect presence of speech in audio streams.", + "tabular-classification": "Classify structured tabular data.", + "tabular-regression": "Predict continuous values from structured tabular data.", + "time-series-forecasting": "Predict future values in time series data.", + "reinforcement-learning": "Learn optimal actions through interaction with an environment.", + "robotics": "Control and decision-making for robotic systems.", + "graph-ml": "Machine learning tasks on graph-structured data.", + "feature-extraction": "Extract meaningful features or representations from data.", + "embedding": "Generate dense vector representations of data.", + "zero-shot-classification": "Classify data without task-specific training examples.", + "few-shot-learning": "Learn from very few examples per class.", + "other": "Other machine learning tasks not covered by predefined categories." + } + }, + { + "pattern": "^cdx:ai-ml:model:task:[a-z0-9:-]+$" + } + ], + "examples": [ + "text-generation", + "image-classification", + "object-detection", + "automatic-speech-recognition" + ] + } + } +} \ No newline at end of file From 58a7cc2d04105e7525b0ed369ccf0a4325dc34b2 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Wed, 29 Jul 2026 16:20:41 -0500 Subject: [PATCH 2/3] Removing modelcard schema Signed-off-by: Steve Springett --- .../cyclonedx-ai-modelcard-2.0.schema.json | 547 ------------------ 1 file changed, 547 deletions(-) delete mode 100644 schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json diff --git a/schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json b/schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json deleted file mode 100644 index 3fcf23c29..000000000 --- a/schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json +++ /dev/null @@ -1,547 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://cyclonedx.org/schema/2.0/model/cyclonedx-ai-modelcard-2.0.schema.json", - "type": "null", - "title": "CycloneDX AI Model Card", - "$comment" : "OWASP CycloneDX is an Ecma International standard (ECMA-424) developed in collaboration between the OWASP Foundation and Ecma Technical Committee 54 (TC54). The standard is published under a royalty-free patent policy. This JSON schema is the reference implementation and is licensed under the Apache License 2.0.", - "$defs": { - "modelCard": { - "$comment": "Model card support in CycloneDX is derived from TensorFlow Model Card Toolkit released under the Apache 2.0 license and available from 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.", - "type": "object", - "title": "Model Card", - "description": "A model card describes the intended uses of a machine learning model and potential limitations, including biases and ethical considerations. Model cards typically contain the training parameters, which datasets were used to train the model, performance metrics, and other relevant data useful for ML transparency. This object SHOULD be specified for any component of type `machine-learning-model` and must not be specified for other component types.", - "additionalProperties": false, - "properties": { - "bom-ref": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType", - "title": "BOM Reference", - "description": "An identifier which can be used to reference the model card elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links." - }, - "modelParameters": { - "type": "object", - "title": "Model Parameters", - "description": "Hyper-parameters for construction of the model.", - "additionalProperties": false, - "properties": { - "approach": { - "type": "object", - "title": "Approach", - "description": "The overall approach to learning used by the model for problem solving.", - "additionalProperties": false, - "properties": { - "type": { - "type": "string", - "title": "Learning Type", - "description": "Learning types describing the learning problem or hybrid learning problem.", - "enum": [ - "supervised", - "unsupervised", - "reinforcement-learning", - "semi-supervised", - "self-supervised" - ], - "meta:enum": { - "supervised": "Supervised machine learning involves training an algorithm on labeled data to predict or classify new data based on the patterns learned from the labeled examples.", - "unsupervised": "Unsupervised machine learning involves training algorithms on unlabeled data to discover patterns, structures, or relationships without explicit guidance, allowing the model to identify inherent structures or clusters within the data.", - "reinforcement-learning": "Reinforcement learning is a type of machine learning where an agent learns to make decisions by interacting with an environment to maximize cumulative rewards, through trial and error.", - "semi-supervised": "Semi-supervised machine learning utilizes a combination of labeled and unlabeled data during training to improve model performance, leveraging the benefits of both supervised and unsupervised learning techniques.", - "self-supervised": "Self-supervised machine learning involves training models to predict parts of the input data from other parts of the same data, without requiring external labels, enabling learning from large amounts of unlabeled data." - } - } - } - }, - "task": { - "type": "string", - "title": "Task", - "description": "Directly influences the input and/or output. Examples include classification, regression, clustering, etc." - }, - "architectureFamily": { - "type": "string", - "title": "Architecture Family", - "description": "The model architecture family such as transformer network, convolutional neural network, residual neural network, LSTM neural network, etc." - }, - "modelArchitecture": { - "type": "string", - "title": "Model Architecture", - "description": "The specific architecture of the model such as GPT-1, ResNet-50, YOLOv3, etc." - }, - "datasets": { - "type": "array", - "title": "Datasets", - "description": "The datasets used to train and evaluate the model.", - "items" : { - "oneOf" : [ - { - "title": "Inline Data Information", - "$ref": "cyclonedx-component-2.0.schema.json#/$defs/componentData" - }, - { - "type": "object", - "title": "Data Reference", - "additionalProperties": false, - "properties": { - "ref": { - "anyOf": [ - { - "title": "Ref", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType" - }, - { - "title": "BOM-Link Element", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/bomLinkElementType" - } - ], - "title": "Reference", - "type": "string", - "description": "References a data component by the components bom-ref attribute" - } - } - } - ] - } - }, - "inputs": { - "type": "array", - "title": "Inputs", - "description": "The input format(s) of the model", - "items": { "$ref": "#/$defs/inputOutputMLParameters" } - }, - "outputs": { - "type": "array", - "title": "Outputs", - "description": "The output format(s) from the model", - "items": { "$ref": "#/$defs/inputOutputMLParameters" } - } - } - }, - "quantitativeAnalysis": { - "type": "object", - "title": "Quantitative Analysis", - "description": "A quantitative analysis of the model", - "additionalProperties": false, - "properties": { - "performanceMetrics": { - "type": "array", - "title": "Performance Metrics", - "description": "The model performance metrics being reported. Examples may include accuracy, F1 score, precision, top-3 error rates, MSC, etc.", - "items": { "$ref": "#/$defs/performanceMetric" } - }, - "graphics": { "$ref": "#/$defs/graphicsCollection" } - } - }, - "considerations": { - "type": "object", - "title": "Considerations", - "description": "What considerations should be taken into account regarding the model's construction, training, and application?", - "additionalProperties": false, - "properties": { - "users": { - "type": "array", - "title": "Users", - "description": "Who are the intended users of the model?", - "items": { - "type": "string" - } - }, - "useCases": { - "type": "array", - "title": "Use Cases", - "description": "What are the intended use cases of the model?", - "items": { - "type": "string" - } - }, - "technicalLimitations": { - "type": "array", - "title": "Technical Limitations", - "description": "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?", - "items": { - "type": "string" - } - }, - "performanceTradeoffs": { - "type": "array", - "title": "Performance Tradeoffs", - "description": "What are the known tradeoffs in accuracy/performance of the model?", - "items": { - "type": "string" - } - }, - "ethicalConsiderations": { - "type": "array", - "title": "Ethical Considerations", - "description": "What are the ethical risks involved in the application of this model?", - "items": { "$ref": "#/$defs/risk" } - }, - "environmentalConsiderations":{ - "$ref": "#/$defs/environmentalConsiderations", - "title": "Environmental Considerations", - "description": "What are the various environmental impacts the corresponding machine learning model has exhibited across its lifecycle?" - }, - "fairnessAssessments": { - "type": "array", - "title": "Fairness Assessments", - "description": "How does the model affect groups at risk of being systematically disadvantaged? What are the harms and benefits to the various affected groups?", - "items": { - "$ref": "#/$defs/fairnessAssessment" - } - } - } - }, - "properties": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" - } - } - }, - "inputOutputMLParameters": { - "type": "object", - "title": "Input and Output Parameters", - "additionalProperties": false, - "properties": { - "format": { - "title": "Input/Output Format", - "description": "The data format for input/output to the model.", - "type": "string", - "examples": [ "string", "image", "time-series"] - } - } - }, - "environmentalConsiderations": { - "type": "object", - "title": "Environmental Considerations", - "description": "Describes various environmental impact metrics.", - "additionalProperties": false, - "properties": { - "energyConsumptions": { - "title": "Energy Consumptions", - "description": "Describes energy consumption information incurred for one or more component lifecycle activities.", - "type": "array", - "items": { - "$ref": "#/$defs/energyConsumption" - } - }, - "properties": { - "type": "array", - "title": "Properties", - "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" - } - } - } - }, - "energyConsumption": { - "title": "Energy consumption", - "description": "Describes energy consumption information incurred for the specified lifecycle activity.", - "type": "object", - "required": [ - "activity", - "energyProviders", - "activityEnergyCost" - ], - "additionalProperties": false, - "properties": { - "activity": { - "type": "string", - "title": "Activity", - "description": "The type of activity that is part of a machine learning model development or operational lifecycle.", - "enum": [ - "design", - "data-collection", - "data-preparation", - "training", - "fine-tuning", - "validation", - "deployment", - "inference", - "other" - ], - "meta:enum": { - "design": "A model design including problem framing, goal definition and algorithm selection.", - "data-collection": "Model data acquisition including search, selection and transfer.", - "data-preparation": "Model data preparation including data cleaning, labeling and conversion.", - "training": "Model building, training and generalized tuning.", - "fine-tuning": "Refining a trained model to produce desired outputs for a given problem space.", - "validation": "Model validation including model output evaluation and testing.", - "deployment": "Explicit model deployment to a target hosting infrastructure.", - "inference": "Generating an output response from a hosted model from a set of inputs.", - "other": "A lifecycle activity type whose description does not match currently defined values." - } - }, - "energyProviders": { - "title": "Energy Providers", - "description": "The provider(s) of the energy consumed by the associated model development lifecycle activity.", - "type": "array", - "items": { "$ref": "#/$defs/energyProvider" } - }, - "activityEnergyCost": { - "title": "Activity Energy Cost", - "description": "The total energy cost associated with the model lifecycle activity.", - "$ref": "#/$defs/energyMeasure" - }, - "co2CostEquivalent": { - "title": "CO2 Equivalent Cost", - "description": "The CO2 cost (debit) equivalent to the total energy cost.", - "$ref": "#/$defs/co2Measure" - }, - "co2CostOffset": { - "title": "CO2 Cost Offset", - "description": "The CO2 offset (credit) for the CO2 equivalent cost.", - "$ref": "#/$defs/co2Measure" - }, - "properties": { - "type": "array", - "title": "Properties", - "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" - } - } - } - }, - "energyMeasure": { - "type": "object", - "title": "Energy Measure", - "description": "A measure of energy.", - "required": [ - "value", - "unit" - ], - "additionalProperties": false, - "properties": { - "value": { - "type": "number", - "title": "Value", - "description": "Quantity of energy." - }, - "unit": { - "type": "string", - "enum": [ "kWh" ], - "title": "Unit", - "description": "Unit of energy.", - "meta:enum": { - "kWh": "Kilowatt-hour (kWh) is the energy delivered by one kilowatt (kW) of power for one hour (h)." - } - } - } - }, - "co2Measure": { - "type": "object", - "title": "CO2 Measure", - "description": "A measure of carbon dioxide (CO2).", - "required": [ - "value", - "unit" - ], - "additionalProperties": false, - "properties": { - "value": { - "type": "number", - "title": "Value", - "description": "Quantity of carbon dioxide (CO2)." - }, - "unit": { - "type": "string", - "enum": [ "tCO2eq" ], - "title": "Unit", - "description": "Unit of carbon dioxide (CO2).", - "meta:enum": { - "tCO2eq": "Tonnes (t) of carbon dioxide (CO2) equivalent (eq)." - } - } - } - }, - "energyProvider": { - "type": "object", - "title": "Energy Provider", - "description": "Describes the physical provider of energy used for model development or operations.", - "required": [ - "organization", - "energySource", - "energyProvided" - ], - "additionalProperties": false, - "properties": { - "bom-ref": { - "title": "BOM Reference", - "description": "An identifier which can be used to reference the energy provider elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" - }, - "description": { - "type": "string", - "title": "Description", - "description": "A description of the energy provider." - }, - "organization": { - "type": "object", - "title": "Organization", - "description": "The organization that provides energy.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/organizationalEntity" - }, - "energySource": { - "type": "string", - "enum": [ - "coal", - "oil", - "natural-gas", - "nuclear", - "wind", - "solar", - "geothermal", - "hydropower", - "biofuel", - "unknown", - "other" - ], - "meta:enum": { - "coal": "Energy produced by types of coal.", - "oil": "Petroleum products (primarily crude oil and its derivative fuel oils).", - "natural-gas": "Hydrocarbon gas liquids (HGL) that occur as gases at atmospheric pressure and as liquids under higher pressures including Natural gas (C5H12 and heavier), Ethane (C2H6), Propane (C3H8), etc.", - "nuclear": "Energy produced from the cores of atoms (i.e., through nuclear fission or fusion).", - "wind": "Energy produced from moving air.", - "solar": "Energy produced from the sun (i.e., solar radiation).", - "geothermal": "Energy produced from heat within the earth.", - "hydropower": "Energy produced from flowing water.", - "biofuel": "Liquid fuels produced from biomass feedstocks (i.e., organic materials such as plants or animals).", - "unknown": "The energy source is unknown.", - "other": "An energy source that is not listed." - }, - "title": "Energy Source", - "description": "The energy source for the energy provider." - }, - "energyProvided": { - "$ref": "#/$defs/energyMeasure", - "title": "Energy Provided", - "description": "The energy provided by the energy source for an associated activity." - }, - "externalReferences": { - "type": "array", - "items": {"$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference"}, - "title": "External References", - "description": "External references provide a way to document systems, sites, and information that may be relevant but are not included with the BOM. They may also establish specific relationships within or external to the BOM." - } - } - }, - "graphicsCollection": { - "type": "object", - "title": "Graphics Collection", - "description": "A collection of graphics that represent various measurements.", - "additionalProperties": false, - "properties": { - "description": { - "title": "Description", - "description": "A description of this collection of graphics.", - "type": "string" - }, - "collection": { - "title": "Collection", - "description": "A collection of graphics.", - "type": "array", - "items": { "$ref": "#/$defs/graphic" } - } - } - }, - "graphic": { - "type": "object", - "title": "Graphic", - "additionalProperties": false, - "properties": { - "name": { - "title": "Name", - "description": "The name of the graphic.", - "type": "string" - }, - "image": { - "title": "Graphic Image", - "description": "The graphic (vector or raster). Base64 encoding must be specified for binary images.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/attachment" - } - } - }, - "performanceMetric": { - "type": "object", - "title": "Performance Metric", - "additionalProperties": false, - "properties": { - "type": { - "title": "Type", - "description": "The type of performance metric.", - "type": "string" - }, - "value": { - "title": "Value", - "description": "The value of the performance metric.", - "type": "string" - }, - "slice": { - "title": "Slice", - "description": "The name of the slice this metric was computed on. By default, assume this metric is not sliced.", - "type": "string" - }, - "confidenceInterval": { - "title": "Confidence Interval", - "description": "The confidence interval of the metric.", - "type": "object", - "additionalProperties": false, - "properties": { - "lowerBound": { - "title": "Lower Bound", - "description": "The lower bound of the confidence interval.", - "type": "string" - }, - "upperBound": { - "title": "Upper Bound", - "description": "The upper bound of the confidence interval.", - "type": "string" - } - } - } - } - }, - "risk": { - "type": "object", - "title": "Risk", - "additionalProperties": false, - "properties": { - "name": { - "title": "Name", - "description": "The name of the risk.", - "type": "string" - }, - "mitigationStrategy": { - "title": "Mitigation Strategy", - "description": "Strategy used to address this risk.", - "type": "string" - } - } - }, - "fairnessAssessment": { - "type": "object", - "title": "Fairness Assessment", - "description": "Information about the benefits and harms of the model to an identified at risk group.", - "additionalProperties": false, - "properties": { - "groupAtRisk": { - "type": "string", - "title": "Group at Risk", - "description": "The groups or individuals at risk of being systematically disadvantaged by the model." - }, - "benefits": { - "type": "string", - "title": "Benefits", - "description": "Expected benefits to the identified groups." - }, - "harms": { - "type": "string", - "title": "Harms", - "description": "Expected harms to the identified groups." - }, - "mitigationStrategy": { - "type": "string", - "title": "Mitigation Strategy", - "description": "With respect to the benefits and harms outlined, please describe any mitigation strategy implemented." - } - } - } - } -} \ No newline at end of file From 49a945618811213e55686a23fa63b287940071c6 Mon Sep 17 00:00:00 2001 From: Steve Springett Date: Thu, 13 Aug 2026 18:01:10 -0500 Subject: [PATCH 3/3] Cleanup. Synced with superceeded PR, added test cases. Signed-off-by: Steve Springett --- .../2.0/model/cyclonedx-ai-ml-2.0.schema.json | 2539 +++++++---------- .../model/cyclonedx-common-2.0.schema.json | 162 ++ .../model/cyclonedx-component-2.0.schema.json | 9 +- .../2.0/invalid-ai-ml-energy-unit-2.0.json | 252 ++ .../invalid-ai-ml-legacy-modelcard-2.0.json | 49 + .../2.0/invalid-ai-ml-task-casing-2.0.json | 251 ++ .../resources/2.0/valid-ai-ml-model-2.0.json | 410 +++ .../2.0/valid-ai-ml-risk-integration-2.0.json | 524 ++++ 8 files changed, 2698 insertions(+), 1498 deletions(-) create mode 100644 tools/src/test/resources/2.0/invalid-ai-ml-energy-unit-2.0.json create mode 100644 tools/src/test/resources/2.0/invalid-ai-ml-legacy-modelcard-2.0.json create mode 100644 tools/src/test/resources/2.0/invalid-ai-ml-task-casing-2.0.json create mode 100644 tools/src/test/resources/2.0/valid-ai-ml-model-2.0.json create mode 100644 tools/src/test/resources/2.0/valid-ai-ml-risk-integration-2.0.json diff --git a/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json b/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json index edbb81e4f..8720c6197 100644 --- a/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json +++ b/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json @@ -2,1147 +2,1019 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://cyclonedx.org/schema/2.0/model/cyclonedx-ai-ml-2.0.schema.json", "type": "null", - "title": "CycloneDX AI/ML schema", + "title": "CycloneDX AI/ML Model", "$comment": "OWASP CycloneDX is an Ecma International standard (ECMA-424) developed in collaboration between the OWASP Foundation and Ecma Technical Committee 54 (TC54). The standard is published under a royalty-free patent policy. This JSON schema is the reference implementation and is licensed under the Apache License 2.0.", "$defs": { - "modelCard": { + "modelProperties": { + "type": "object", + "title": "AI/ML Model Properties", + "description": "Intrinsic technical characteristics of a machine learning model. This object SHOULD be specified for any component of type `machine-learning-model` and shall not be specified for other component types. Contextual and subjective aspects of a model, including ethical and fairness considerations, potential harms, groups at risk, and impact assessments, are expressed with the risk model and reference the model component. Views of this data tailored to a specific audience, such as a model card, are expressed with perspectives.", + "additionalProperties": false, "properties": { - "bom-ref": { - "title": "BOM Reference", - "description": "An identifier which can be used to reference the model card elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + "learningTypes": { + "type": "array", + "title": "Learning Types", + "description": "The learning paradigms applied when training the model. A model may combine several paradigms, for example self-supervised pre-training followed by supervised fine-tuning and reinforcement learning based alignment.", + "uniqueItems": true, + "items": { + "$ref": "#/$defs/learningType" + } }, "tasks": { "type": "array", "title": "Tasks", - "description": "The machine learning tasks that the model is designed to perform. This directly influences the model's intended use, input and output characteristics, and evaluation metrics. Models may support multiple tasks (e.g., multimodal models).", - "minItems": 1, + "description": "The machine learning tasks the model is designed to perform. Tasks directly influence the intended use, the input and output characteristics, and the applicable evaluation metrics of the model. A model may support multiple tasks.", "uniqueItems": true, "items": { - "$ref": "#/$defs/modelTaskType" - }, - "examples": [ - [ - "text-generation" - ], - [ - "image-classification", - "object-detection" - ], - [ - "image-to-text", - "text-to-image" - ] - ] + "$ref": "#/$defs/modelTask" + } }, "architecture": { - "$ref": "#/defs/modelArchitecture" - }, - "designConsiderations": { - "$ref": "#/defs/designConsiderations" + "title": "Architecture", + "description": "The architecture of the model.", + "$ref": "#/$defs/modelArchitecture" }, - "trainingProfile": { - "$ref": "#/defs/trainingProfile" + "parameterCount": { + "type": "integer", + "title": "Parameter Count", + "description": "The total number of trainable parameters of the model.", + "minimum": 0 }, - "modelParameters": { - "$ref": "#/$defs/modelParameters" + "quantization": { + "title": "Quantization", + "description": "The quantization applied to the model weights as distributed. Quantization of individual input and output tensors is expressed on the model parameters.", + "$ref": "#/$defs/quantization" }, - "quantitativeAnalysis": { - "$ref": "#/$defs/quantitativeAnalysis" - }, - "externalReferences": { + "inputs": { "type": "array", - "description": "External references to information relevant to the model.", + "title": "Model Inputs", + "description": "The input parameters accepted by the model.", "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + "$ref": "#/$defs/modelParameter" } }, - "properties": { - "description": "Properties of the model.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" - } - } - }, - "modelArchitecture": { - "type": "object", - "properties": { - "architectureName": { - "type": "string", - "title": "Architecture Name", - "description": "The specific identifying name of the model architecture. This typically refers to well-known model variants or versions.", - "examples": [ - "GPT-4", - "GPT-3.5-turbo", - "Llama-3.1-70B", - "Claude-3.5-Sonnet", - "Mistral-7B-v0.3", - "ResNet-50", - "YOLOv8", - "BERT-base-uncased", - "Stable-Diffusion-XL", - "Whisper-large-v3" - ] + "outputs": { + "type": "array", + "title": "Model Outputs", + "description": "The output parameters produced by the model.", + "items": { + "$ref": "#/$defs/modelParameter" + } }, - "description": { - "type": "string", - "title": "Description", - "description": "A detailed description of the model's architecture, including key characteristics, design decisions, and architectural innovations.", - "examples": [ - "Decoder-only transformer with grouped-query attention and rotary positional embeddings, using a mixture-of-experts feed-forward layer.", - "Convolutional backbone with residual connections and a transformer head for multi-scale feature aggregation." - ] + "training": { + "title": "Training", + "description": "Information about how the model was trained.", + "$ref": "#/$defs/training" }, - "structural": { - "type": "object", - "description": "Describes the model's primary and secondary architectural structure and network topology.", - "required": [ - "primary" - ], - "properties": { - "primary": { - "$comment": "Values not listed can be proposed to the CycloneDX Property Taxonomy.", - "type": "string", - "description": "The core mathematical structural framework of the model backbone.", - "anyOf": [ - { - "enum": [ - "transformer", - "cnn", - "rnn", - "lstm", - "gru", - "gan", - "vae", - "mamba", - "ssm", - "gnn", - "mlp", - "rwkv", - "snn", - "kan", - "diffusion", - "flow-matching", - "rbm", - "capsnet", - "neuromorphic", - "hybrid" - ], - "meta:enum": { - "transformer": "Architecture based on self-attention mechanisms for processing sequential or spatial data.", - "cnn": "Convolutional Neural Network - architecture using convolutional layers for processing grid-like data.", - "rnn": "Recurrent Neural Network - architecture with recurrent connections for sequential data processing.", - "lstm": "Long Short-Term Memory - RNN variant with gating mechanisms for long-term dependencies.", - "gru": "Gated Recurrent Unit - RNN variant with simplified gating compared to LSTM.", - "gan": "Generative Adversarial Network - dual-network framework containing a generator and a discriminator.", - "vae": "Variational Autoencoder - probabilistic encoder-decoder architecture mapping to a latent space.", - "mamba": "State-space model architecture with selective mechanisms for efficient sequence modeling.", - "ssm": "State Space Model - core architecture based on continuous or discrete state-space representations.", - "gnn": "Graph Neural Network - architecture optimized for processing graph-structured data elements.", - "mlp": "Multi-Layer Perceptron - classic feedforward architecture composed entirely of fully connected layers.", - "rwkv": "Receptive Weighted Key Value - architecture combining parallelizable training with RNN-like inference.", - "snn": "Spiking Neural Network - neuromorphic architecture utilizing discrete, time-dependent spiking activations.", - "kan": "Kolmogorov-Arnold Network - architecture featuring learnable activation functions on edges rather than nodes.", - "diffusion": "Denoising diffusion probabilistic model - iteratively refines noise into data (e.g., DDPM, Stable Diffusion).", - "flow-matching": "Continuous normalizing flow trained via flow matching / rectified flow (e.g., Flux, SD3).", - "rbm": "Restricted Boltzmann Machine - energy-based generative model with stochastic hidden units.", - "capsnet": "Capsule Network - architecture using dynamic routing between capsule groups to preserve spatial hierarchies.", - "neuromorphic": "Architecture designed for deployment on neuromorphic hardware (e.g., Intel Loihi, IBM TrueNorth).", - "hybrid": "Explicit first-class combination of two or more distinct primary architectures (e.g., CNN+Transformer)." - } - }, - { - "pattern": "^cdx:ai-ml:model:architecture:primary:[a-z0-9:-]+$" - } - ], - "examples": [ - "transformer", - "cnn", - "mamba", - "gnn", - "cdx:ai-ml:model:architecture:primary:retnet" - ] - }, - "secondary": { - "type": "array", - "description": "A list of secondary macro-layouts or component sub-networks built into the primary structure.", - "uniqueItems": true, - "items": { - "type": "string", - "anyOf": [ - { - "enum": [ - "decoder-only", - "encoder-only", - "encoder-decoder", - "mixture-of-experts", - "vae-bottleneck", - "u-net", - "residual-connections", - "dual-encoders", - "cross-attention-gated", - "siamese-network", - "hybrid-backbone", - "state-space-model", - "flow-matching", - "vision-encoder", - "adapter-layers", - "projector-layers", - "gated-linear-units", - "speculative-decoding", - "rotary-position-embedding", - "grouped-query-attention", - "sliding-window-attention", - "retrieval-augmented", - "memory-augmented", - "multimodal-fusion", - "reranker", - "other" - ], - "meta:enum": { - "decoder-only": "Autoregressive macro-layout processing data left-to-right (e.g., GPT series).", - "encoder-only": "Bidirectional macro-layout processing complete sequences simultaneously (e.g., BERT).", - "encoder-decoder": "Sequence-to-sequence structure mapping an input representation to an output sequence (e.g., T5).", - "mixture-of-experts": "Sparse routing layer mechanism activating specific expert subnetworks per token.", - "vae-bottleneck": "Symmetric compression bottleneck utilizing mean and variance latent vectors.", - "u-net": "Symmetric contracting and expanding macro-layout featuring skip connections between corresponding scales.", - "residual-connections": "Explicit skip or identity shortcuts bypassing one or more structural layers.", - "dual-encoders": "Parallel feature extraction pipelines mapping different modalities into a shared space.", - "cross-attention-gated": "Explicit sub-component routing that conditions one feature stream using another via attention mechanisms.", - "siamese-network": "Twin identical subnetworks sharing identical weights to compute similarity metrics.", - "hybrid-backbone": "Direct cascading combination of distinct primary layers (e.g., a CNN feature extractor feeding a Transformer).", - "state-space-model": "State space model architectures using selective state spaces for sequence modeling (e.g., Mamba).", - "flow-matching": "Flow-based generative model backbone using continuous normalizing flows.", - "vision-encoder": "Vision encoding component for processing image inputs in multimodal architectures (e.g., CLIP, SigLIP).", - "adapter-layers": "Parameter-efficient fine-tuning layers inserted into frozen models (e.g., LoRA, adapters).", - "projector-layers": "Cross-modal projection components bridging different modalities (e.g., Q-Former, linear projectors).", - "gated-linear-units": "Gated activation mechanisms using element-wise multiplication (e.g., GLU, SwiGLU, GeGLU).", - "speculative-decoding": "Sub-network pairing a small draft model with a large verifier model to accelerate autoregressive generation.", - "rotary-position-embedding": "Rotary Position Embedding (RoPE) sub-component encoding positional information via rotation matrices.", - "grouped-query-attention": "Grouped-Query Attention (GQA) variant sharing key/value heads across groups of query heads to reduce KV-cache size.", - "sliding-window-attention": "Attention mechanism restricting receptive field to a local sliding window (e.g., Mistral).", - "retrieval-augmented": "Explicit retrieval sub-network prepended to or integrated into the model (e.g., RAG, RETRO).", - "memory-augmented": "External or persistent memory bank integrated into the forward pass (e.g., MemGPT, Memorizing Transformers).", - "multimodal-fusion": "Layer or block that fuses representations across more than one modality (e.g., cross-modal attention, FiLM conditioning).", - "reranker": "Separate scoring / reranking head applied after an initial retrieval or generation step.", - "other": "Other secondary architectural components not covered by the predefined categories." - } - }, - { - "pattern": "^cdx:ai-ml:model:architecture:secondary:[a-z0-9:-]+$" - } - ] - }, - "examples": [ - [ - "decoder-only", - "mixture-of-experts" - ], - [ - "vae-bottleneck", - "dual-encoders" - ], - [ - "cdx:ai-ml:model:architecture:secondary:cross-modal-fusion" - ] - ] - }, - "topologyType": { - "type": "string", - "description": "Specifies the runtime parameter activation and connection structure of the network layers.", - "anyOf": [ - { - "enum": [ - "dense", - "sparse", - "dynamic", - "liquid", - "mixture-of-depths", - "early-exit", - "recurrent-hybrid" - ], - "meta:enum": { - "dense": "All or most parameters are active during inference with full connectivity between layers.", - "sparse": "Only a subset of parameters are active during inference with selective connectivity.", - "dynamic": "Parameter activation and connectivity patterns change based on input or runtime conditions.", - "liquid": "Continuously adaptive network structure with time-varying connections and activations.", - "mixture-of-depths": "Tokens are routed to different computational depths rather than different expert modules.", - "early-exit": "Inference exits at the earliest layer that meets a confidence threshold, reducing compute for easy inputs.", - "recurrent-hybrid": "Static layer layout that alternates between global attention and recurrent / SSM layers (e.g., Jamba, Zamba)." - } - }, - { - "pattern": "^cdx:ai-ml:model:architecture:topology:[a-z0-9:-]+$" - } - ], - "examples": [ - "dense", - "sparse", - "cdx:ai-ml:model:architecture:topology:structured-pruned" - ] - } - } + "evaluation": { + "title": "Evaluation", + "description": "A quantitative evaluation of the model.", + "$ref": "#/$defs/evaluation" }, - "behavioralParadigm": { + "limitations": { "type": "array", - "description": "The behavioral paradigm or modeling objective specifying how the system interacts with and learns data distributions.", - "minItems": 1, - "uniqueItems": true, + "title": "Limitations", + "description": "Known technical limitations of the model, including constraints on accuracy, reasoning, scalability, and appropriate use. Limitations that expose users or other parties to potential harm should also be documented with the risk model.", "items": { "type": "string" - }, - "examples": [ - [ - "Autoregressive", - "Instruction-Tuned" - ], - [ - "Diffusion", - "Rectified-Flow" - ], - [ - "Contrastive" - ] - ] + } }, - "specializedProcessing": { + "useCases": { "type": "array", - "description": "The custom processing mechanisms, attention kernels, and hardware-software optimization pipelines.", - "minItems": 1, + "title": "Use Cases", + "description": "References to use cases, defined elsewhere in the BOM, that describe the intended uses of the model.", "uniqueItems": true, "items": { - "type": "string" - }, - "examples": [ - [ - "RoPE", - "Grouped-Query-Attention", - "FlashAttention-2" - ], - [ - "Cross-Attention", - "MMDiT-Block" - ] - ] + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType" + } + }, + "environmental": { + "title": "Environmental Impact", + "description": "Measured environmental impacts of the model across its lifecycle activities.", + "$ref": "#/$defs/environmental" }, "externalReferences": { "type": "array", - "description": "references to external resources that describe the model architecture.", + "title": "External References", + "description": "External references to resources that are relevant to the model but are not included with the BOM.", "items": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" - }, - "examples": [ - [ - { - "type": "source-distribution", - "url": "https://github.com/huggingface/transformers/blob/v4.45.0/src/transformers/models/llama/modeling_llama.py", - "comment": "Hugging Face Transformers v4.45.0 implementation" - }, - { - "type": "documentation", - "url": "https://arxiv.org/abs/2407.21783", - "comment": "Architecture paper" - } - ] - ] + } }, "properties": { - "description": "Properties of the model architecture.", + "title": "Properties", + "description": "Provides the ability to document name-value pairs for the model. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" } } }, - "designConsiderations": { - "type": "object", - "properties": { - "users": { - "$todos": [ - "Discuss moving actor from blueprints schema to common schema", - "Add externalReferences to actor as these may be defined by external orgs. and their docs." + "learningType": { + "title": "Learning Type", + "description": "A learning paradigm applied when training a machine learning model. Use the custom option for paradigms not covered by the predefined values.", + "oneOf": [ + { + "title": "Predefined Learning Type", + "type": "string", + "enum": [ + "supervised", + "unsupervised", + "semi-supervised", + "self-supervised", + "reinforcement-learning" ], - "type": "array", - "title": "Users", - "description": "Who are the intended users of the model?", - "uniqueItems": true, - "items": { - "$ref": "cyclonedx-blueprint-2.0.schema.json$defs/actor" + "meta:enum": { + "supervised": "The model learns from labelled data to map inputs to known outputs.", + "unsupervised": "The model learns patterns and structure from unlabelled data.", + "semi-supervised": "The model learns from a combination of labelled and unlabelled data.", + "self-supervised": "The model learns from supervisory signals derived automatically from the data itself.", + "reinforcement-learning": "The model learns a policy by acting in an environment and receiving reward signals, including reward signals derived from human or automated feedback." } }, - "useCases": { - "$todos": [ - "Add externalReferences to usecase schema object." + { + "type": "object", + "title": "Custom Learning Type", + "required": [ + "name" ], - "title": "Use Cases", - "description": "What are the intended use cases for the model?", - "$ref": "cyclonedx-usecase-2.0.schema.json#/$defs/useCases" - }, - "technicalLimitations": { - "title": "Technical limitations", - "description": "List of mathematical and physical constraints that may affect a model's accuracy, reasoning, and scalability.", - "$ref": "#/$defs/considerations" - }, - "performanceTradeoffs": { - "title": "Performance Tradeoffs", - "description": "What are the known tradeoffs in accuracy/performance of the model?", - "$ref": "#/$defs/considerations" - }, - "ethicalConsiderations": { - "title": "Ethical Considerations", - "description": "What are the ethical risks involved in the application of this model?", - "$ref": "#/$defs/considerations" - }, - "environmentalConsiderations": { - "title": "Environmental Considerations", - "description": "What are the various environmental impacts the corresponding machine learning model has exhibited across its lifecycle?", - "$ref": "#/$defs/environmentalConsiderations" - }, - "fairnessAssessments": { - "title": "Fairness Assessments", - "description": "What are the fairness assessments and bias evaluations that have been performed on the model?", - "$ref": "#/$defs/considerations" - }, - "externalReferences": { - "type": "array", - "description": "External references provide a way to document systems, sites, and information that may be relevant but are not included with the BOM.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" - } - }, - "properties": { - "type": "array", - "title": "Properties", - "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom learning paradigm." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom learning paradigm." + } } } - } + ] }, - "riskGroup": { - "type": "object", - "$todos": [ - "Verify riskDomain type enum. has all the values we need for EU AI Act.", - "We always want a group name, description to qualify the type (and we may have multiples of the same type), but riskDomain uses OneOf logic for custom domains.", - "Note: if we could extend domains using the AI/ML prop. tax., we perhaps could settle just for the type field" - ], - "description": "Provides a means of expressing a design, runtime or other consideration for a specific aspect of the model. The risk group can be referenced elsewhere in the BOM using its bom-ref.", - "additionalProperties": false, - "required": [ - "groupName" - ], - "allOf": [ + "modelTask": { + "title": "Model Task", + "description": "A machine learning task that a model is designed to perform. Use the custom option for tasks not covered by the predefined values.", + "oneOf": [ { - "$ref": "cyclonedx-risk-2.0.schema.json/$defs/riskDomain" - } - ], - "properties": { - "bom-ref": { - "title": "BOM Reference", - "description": "An identifier which can be used to reference the risk group elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" - }, - "groupName": { - "type": "string", - "title": "Group Name", - "description": "The name of the group at risk.", - "examples": [ - "Elderly users", - "Non-native speakers", - "People with visual impairments", - "Low-income households" - ] - }, - "groupDescription": { + "title": "Predefined Task", "type": "string", - "title": "Group Description", - "description": "A description of the group at risk.", - "examples": [ - "Users aged 65 and over who may have reduced digital literacy or accessibility needs.", - "Users whose primary language differs from the model's primary training language.", - "Individuals relying on assistive technologies such as screen readers." - ] - }, - "externalReferences": { - "type": "array", - "description": "References to external resources that describe the risk group.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + "enum": [ + "text-generation", + "text-classification", + "token-classification", + "question-answering", + "summarization", + "translation", + "text-to-text", + "fill-mask", + "sentence-similarity", + "text-to-image", + "text-to-video", + "text-to-audio", + "text-to-speech", + "image-classification", + "image-segmentation", + "object-detection", + "image-to-image", + "image-to-text", + "depth-estimation", + "video-classification", + "audio-classification", + "automatic-speech-recognition", + "audio-to-audio", + "voice-activity-detection", + "tabular-classification", + "tabular-regression", + "time-series-forecasting", + "reinforcement-learning", + "robotics", + "graph-ml", + "feature-extraction", + "embedding", + "zero-shot-classification", + "few-shot-learning" + ], + "meta:enum": { + "text-generation": "Generate coherent text continuations from prompts.", + "text-classification": "Classify text into predefined categories, for example sentiment analysis or topic classification.", + "token-classification": "Classify individual tokens in text, for example named entity recognition or part-of-speech tagging.", + "question-answering": "Answer questions based on context or knowledge, using extractive or generative approaches.", + "summarization": "Generate concise summaries of longer text documents.", + "translation": "Translate text from one language to another.", + "text-to-text": "Transform text from one form to another, for example paraphrasing or style transfer.", + "fill-mask": "Predict masked tokens in text, as in masked language modelling.", + "sentence-similarity": "Compute semantic similarity between text sequences.", + "text-to-image": "Generate images from text descriptions.", + "text-to-video": "Generate video content from text descriptions.", + "text-to-audio": "Generate audio or music from text descriptions.", + "text-to-speech": "Convert text to spoken audio through speech synthesis.", + "image-classification": "Classify images into predefined categories.", + "image-segmentation": "Segment images into regions or objects using semantic or instance segmentation.", + "object-detection": "Detect and localize objects in images.", + "image-to-image": "Transform images, for example style transfer, super-resolution, or inpainting.", + "image-to-text": "Generate text descriptions from images, for example image captioning.", + "depth-estimation": "Estimate depth information from images.", + "video-classification": "Classify video content into categories.", + "audio-classification": "Classify audio into categories, for example sound event detection.", + "automatic-speech-recognition": "Transcribe spoken audio to text.", + "audio-to-audio": "Transform audio, for example noise reduction or voice conversion.", + "voice-activity-detection": "Detect the presence of speech in audio streams.", + "tabular-classification": "Classify structured tabular data.", + "tabular-regression": "Predict continuous values from structured tabular data.", + "time-series-forecasting": "Predict future values in time series data.", + "reinforcement-learning": "Learn optimal actions through interaction with an environment.", + "robotics": "Control and decision making for robotic systems.", + "graph-ml": "Machine learning tasks on graph structured data.", + "feature-extraction": "Extract meaningful features or representations from data.", + "embedding": "Generate dense vector representations of data.", + "zero-shot-classification": "Classify data without task specific training examples.", + "few-shot-learning": "Learn from very few examples per class." } }, - "properties": { - "description": "Properties of the risk group.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + { + "type": "object", + "title": "Custom Task", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom machine learning task." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom machine learning task." + } + } } - }, + ], "examples": [ + "text-generation", + "image-classification", + "object-detection", + "automatic-speech-recognition" + ] + }, + "architectureFamily": { + "title": "Architecture Family", + "description": "The core structural family of a model. Use the custom option for families not covered by the predefined values.", + "oneOf": [ { - "bom-ref": "risk-group-1", - "groupName": "Elderly users", - "groupDescription": "Users aged 65 and over who may have reduced digital literacy or accessibility needs." + "title": "Predefined Architecture Family", + "type": "string", + "enum": [ + "transformer", + "cnn", + "rnn", + "lstm", + "gru", + "gan", + "vae", + "mamba", + "ssm", + "gnn", + "mlp", + "rwkv", + "snn", + "kan", + "diffusion", + "flow-matching", + "rbm", + "capsnet", + "neuromorphic", + "hybrid" + ], + "meta:enum": { + "transformer": "Architecture based on self-attention mechanisms for processing sequential or spatial data.", + "cnn": "Convolutional neural network using convolutional layers for processing grid structured data.", + "rnn": "Recurrent neural network with recurrent connections for sequential data processing.", + "lstm": "Long short-term memory network, a recurrent variant with gating mechanisms for long-term dependencies.", + "gru": "Gated recurrent unit network, a recurrent variant with simplified gating.", + "gan": "Generative adversarial network, a dual network framework containing a generator and a discriminator.", + "vae": "Variational autoencoder, a probabilistic encoder and decoder architecture mapping to a latent space.", + "mamba": "State space model architecture with selective mechanisms for efficient sequence modelling.", + "ssm": "State space model based on continuous or discrete state space representations.", + "gnn": "Graph neural network optimized for processing graph structured data.", + "mlp": "Multilayer perceptron, a feedforward architecture composed entirely of fully connected layers.", + "rwkv": "Receptance weighted key value architecture combining parallelizable training with recurrent inference.", + "snn": "Spiking neural network, a neuromorphic architecture utilizing discrete, time dependent spiking activations.", + "kan": "Kolmogorov-Arnold network featuring learnable activation functions on edges rather than nodes.", + "diffusion": "Denoising diffusion model that iteratively refines noise into data.", + "flow-matching": "Continuous normalizing flow trained with flow matching or rectified flow objectives.", + "rbm": "Restricted Boltzmann machine, an energy based generative model with stochastic hidden units.", + "capsnet": "Capsule network using dynamic routing between capsule groups to preserve spatial hierarchies.", + "neuromorphic": "Architecture designed for deployment on neuromorphic hardware.", + "hybrid": "Explicit combination of two or more distinct architecture families." + } }, { - "bom-ref": "risk-group-2", - "groupName": "Non-native speakers", - "groupDescription": "Users whose primary language differs from the model's training language." + "type": "object", + "title": "Custom Architecture Family", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom architecture family." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom architecture family." + } + } } ] }, - "riskGroupReference": { - "type": "object", - "title": "Risk Group Reference Choice", - "description": "A reference to either a risk group object or a risk group defined elsewhere in the BOM.", - "additionalProperties": false, - "properties": { - "riskGroupRef": { - "title": "Risk Group Reference", - "description": "References a risk group by its bom-ref attribute or provides a full risk group object.", - "oneOf": [ - { - "title": "Risk Group", - "$ref": "#/$defs/riskGroup" + "architectureFeature": { + "title": "Architecture Feature", + "description": "A structural feature or mechanism present in a model, including macro level layouts, attention variants, and parameter efficient adaptation mechanisms. Use the custom option for features not covered by the predefined values.", + "oneOf": [ + { + "title": "Predefined Architecture Feature", + "type": "string", + "enum": [ + "decoder-only", + "encoder-only", + "encoder-decoder", + "mixture-of-experts", + "vae-bottleneck", + "u-net", + "residual-connections", + "dual-encoders", + "cross-attention", + "siamese-network", + "hybrid-backbone", + "vision-encoder", + "adapter-layers", + "projector-layers", + "gated-linear-units", + "speculative-decoding", + "rotary-position-embedding", + "grouped-query-attention", + "sliding-window-attention", + "retrieval-augmented", + "memory-augmented", + "multimodal-fusion", + "reranker" + ], + "meta:enum": { + "decoder-only": "Autoregressive layout that attends to prior positions only.", + "encoder-only": "Bidirectional layout that processes complete sequences simultaneously.", + "encoder-decoder": "Sequence to sequence structure mapping an input representation to an output sequence.", + "mixture-of-experts": "Sparse routing mechanism activating specific expert subnetworks per token.", + "vae-bottleneck": "Symmetric compression bottleneck utilizing mean and variance latent vectors.", + "u-net": "Symmetric contracting and expanding layout featuring skip connections between corresponding scales.", + "residual-connections": "Explicit skip or identity shortcuts bypassing one or more structural layers.", + "dual-encoders": "Parallel feature extraction pipelines mapping different inputs into a shared space.", + "cross-attention": "Mechanism that conditions one feature stream on another through attention.", + "siamese-network": "Twin subnetworks sharing identical weights to compute similarity metrics.", + "hybrid-backbone": "Direct cascading combination of distinct architecture families, for example a convolutional feature extractor feeding a transformer.", + "vision-encoder": "Vision encoding component for processing image inputs in multimodal architectures.", + "adapter-layers": "Parameter efficient fine-tuning layers inserted into otherwise frozen models.", + "projector-layers": "Projection components bridging different modalities.", + "gated-linear-units": "Gated activation mechanisms using element-wise multiplication.", + "speculative-decoding": "Pairing of a small draft model with a larger verifier model to accelerate autoregressive generation.", + "rotary-position-embedding": "Positional encoding applied through rotation matrices.", + "grouped-query-attention": "Attention variant sharing key and value heads across groups of query heads.", + "sliding-window-attention": "Attention mechanism restricting the receptive field to a local sliding window.", + "retrieval-augmented": "Retrieval component prepended to or integrated into the model.", + "memory-augmented": "External or persistent memory bank integrated into the forward pass.", + "multimodal-fusion": "Layer or block that fuses representations across more than one modality.", + "reranker": "Separate scoring or reranking head applied after an initial retrieval or generation step." + } + }, + { + "type": "object", + "title": "Custom Architecture Feature", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom architecture feature." }, - { - "title": "Risk Group Reference", - "description": "Reference to a risk group defined elsewhere in the BOM.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom architecture feature." } - ] + } } - } + ] }, - "riskGroups": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/$defs/riskGroupReference" - } + "architectureTopology": { + "title": "Architecture Topology", + "description": "The runtime parameter activation and connection structure of a model. Use the custom option for topologies not covered by the predefined values.", + "oneOf": [ + { + "title": "Predefined Architecture Topology", + "type": "string", + "enum": [ + "dense", + "sparse", + "dynamic", + "liquid", + "mixture-of-depths", + "early-exit", + "recurrent-hybrid" + ], + "meta:enum": { + "dense": "All or most parameters are active during inference with full connectivity between layers.", + "sparse": "Only a subset of parameters is active during inference with selective connectivity.", + "dynamic": "Parameter activation and connectivity patterns change based on input or runtime conditions.", + "liquid": "Continuously adaptive network structure with time varying connections and activations.", + "mixture-of-depths": "Tokens are routed to different computational depths rather than to different expert modules.", + "early-exit": "Inference exits at the earliest layer that meets a confidence threshold, reducing compute for easy inputs.", + "recurrent-hybrid": "Static layer layout that alternates between global attention and recurrent or state space layers." + } + }, + { + "type": "object", + "title": "Custom Architecture Topology", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom topology." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom topology." + } + } + } + ] }, - "consideration": { - "$todos": [ - "Determine if we want all fields from risk or a subset.", - "Determine if a consideration can be either a risk or an assessment from the risk schema (or can an assessment optionally reference a risk or vice-versa as is implied)." - ], + "modelArchitecture": { "type": "object", - "description": "Provides a means of expressing a design, runtime or other consideration for a specific aspect of the model relative to a percieved risk.", - "required": [ - "name" - ], + "title": "Model Architecture", + "description": "The architecture of a machine learning model, including its structural family, notable features, and topology.", "additionalProperties": false, "properties": { "name": { "type": "string", "title": "Name", - "description": "The name of the consideration.", + "description": "The identifying name of the model architecture, typically a well known architecture variant.", "examples": [ - "Hallucination in low-resource languages", - "Gender bias in occupational classification", - "Latency under high concurrency", - "Energy cost of fine-tuning" + "ResNet-50", + "BERT-base", + "U-Net", + "ViT-B/16" ] }, "description": { "type": "string", "title": "Description", - "description": "The general description of the consideration.", - "examples": [ - "The model may produce factually incorrect outputs when prompted in languages underrepresented in the training corpus.", - "Classification accuracy for professional roles has been observed to vary by perceived gender of the subject." - ] - }, - "groupsAtRisk": { - "type": "array", - "title": "Groups At Risk", - "description": "The groups at risk of being systematically disadvantaged by the model.", - "$ref": "#/$defs/riskGroups" - }, - "benefits": { - "type": "string", - "title": "Benefits", - "description": "Expected benefits to the identified groups at risk.", - "examples": [ - "Improved accessibility through multilingual support reduces language barriers for non-native speakers.", - "Automated screening may reduce time-to-decision for applicants in under-served regions." - ] + "description": "A description of the architecture, including key characteristics, design decisions, and architectural innovations." }, - "harms": { - "type": "string", - "title": "Harms", - "description": "Expected harms to the identified groups at risk.", - "examples": [ - "Model outputs may reinforce occupational stereotypes, leading to discriminatory hiring outcomes for women in STEM.", - "Reduced accuracy for accented speech may cause misrecognition for non-native English speakers." - ] + "family": { + "title": "Family", + "description": "The core structural family of the model.", + "$ref": "#/$defs/architectureFamily" }, - "risk": { - "$ref": "cyclonedx-risk-2.0.schema.json#/$defs/risk" + "features": { + "type": "array", + "title": "Features", + "description": "Structural features and mechanisms present in the model.", + "uniqueItems": true, + "items": { + "$ref": "#/$defs/architectureFeature" + } }, - "assessment": { - "$ref": "cyclonedx-risk-2.0.schema.json#/$defs/assessment" + "topology": { + "title": "Topology", + "description": "The runtime parameter activation and connection structure of the model.", + "$ref": "#/$defs/architectureTopology" }, "externalReferences": { "type": "array", + "title": "External References", + "description": "External references to resources that are relevant to the model architecture but are not included with the BOM.", "items": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" } }, "properties": { + "title": "Properties", + "description": "Provides the ability to document name-value pairs for the model architecture. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" } } }, - "considerations": { - "type": "array", - "uniqueItems": true, - "items": { - "$ref": "#/$defs/consideration" - } + "modality": { + "title": "Modality", + "description": "The type of data a model parameter carries. Use the custom option for modalities not covered by the predefined values.", + "oneOf": [ + { + "title": "Predefined Modality", + "type": "string", + "enum": [ + "text", + "image", + "audio", + "video", + "multimodal", + "embedding", + "logits" + ], + "meta:enum": { + "text": "Natural language text input or output.", + "image": "Visual image data input or output.", + "audio": "Audio or speech data input or output.", + "video": "Video data input or output.", + "multimodal": "Combined multiple modalities, for example text and image.", + "embedding": "Dense vector representations in a continuous space.", + "logits": "Raw unnormalized model outputs before activation functions." + } + }, + { + "type": "object", + "title": "Custom Modality", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom modality." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom modality." + } + } + } + ] }, - "datasetReference": { + "quantization": { "type": "object", - "title": "Dataset Reference Choice", + "title": "Quantization", + "description": "The quantization applied to a model parameter. The scheme parameters recorded here describe how quantized values relate to real values. The scale and zero point tensors themselves are model data and are distributed with the model artefact, not with the BOM. Additional scheme specific details may be recorded in the `properties` of the model parameter.", "additionalProperties": false, "properties": { - "dataRef": { - "title": "Dataset Reference", + "method": { "type": "string", - "description": "References a data component by the components bom-ref attribute", - "anyOf": [ + "title": "Method", + "description": "The quantization method or algorithm applied.", + "examples": [ + "gptq", + "awq", + "rtn", + "k-quant" + ] + }, + "bits": { + "type": "number", + "title": "Bits", + "description": "The nominal bit width per value. Fractional widths are permitted, for example 1.58 for ternary quantization.", + "exclusiveMinimum": 0, + "examples": [ + 8, + 4, + 1.58 + ] + }, + "scheme": { + "title": "Scheme", + "description": "The mapping between quantized values and real values.", + "oneOf": [ { - "title": "Data Component Reference", - "$ref": "#/$defs/cyclonedx-common-2.0/$defs/refLinkType" + "title": "Predefined Quantization Scheme", + "type": "string", + "enum": [ + "affine", + "symmetric" + ], + "meta:enum": { + "affine": "Asymmetric mapping using a scale and a zero point.", + "symmetric": "Symmetric mapping using a scale with the zero point fixed at zero." + } }, { - "title": "Data BOM, BOM-Link Reference", - "$ref": "#/$defs/cyclonedx-common-2.0/$defs/bomLinkElementType" + "type": "object", + "title": "Custom Quantization Scheme", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom quantization scheme." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom quantization scheme." + } + } } - ], + ] + }, + "granularity": { + "title": "Granularity", + "description": "The level at which scales and zero points are assigned.", + "oneOf": [ + { + "title": "Predefined Quantization Granularity", + "type": "string", + "enum": [ + "per-tensor", + "per-channel", + "per-group" + ], + "meta:enum": { + "per-tensor": "One scale and zero point applies to the entire tensor.", + "per-channel": "Scales and zero points are assigned along one tensor axis.", + "per-group": "Scales and zero points are assigned to fixed size groups of elements along one tensor axis." + } + }, + { + "type": "object", + "title": "Custom Quantization Granularity", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom quantization granularity." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom quantization granularity." + } + } + } + ] + }, + "groupSize": { + "type": "integer", + "title": "Group Size", + "description": "The number of elements sharing one scale and zero point when the granularity is `per-group`.", + "minimum": 1, "examples": [ - "training-dataset-1", - "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#openwebtext-subset" + 32, + 64, + 128 ] + }, + "axis": { + "type": "integer", + "title": "Axis", + "description": "The tensor axis along which scales and zero points are assigned when the granularity is `per-channel` or `per-group`.", + "minimum": 0 } } }, - "datasetProcessingSpec": { + "modelParameter": { "type": "object", - "description": "Dataset processing formula including collection parameters and methodological choices used to transform data components into the subject dataset for compliance transparency.", + "title": "Model Parameter", + "description": "A single input or output parameter of a machine learning model. Parameter specific details not covered by the predefined fields may be recorded in `properties`.", + "additionalProperties": false, + "required": [ + "name" + ], "properties": { - "datasets": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the parameter.", + "examples": [ + "prompt", + "image", + "audio", + "logits", + "embeddings" + ] + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the parameter and its purpose." + }, + "modality": { + "title": "Modality", + "description": "The type of data this parameter carries.", + "$ref": "#/$defs/modality" + }, + "dataType": { + "type": "string", + "title": "Data Type", + "description": "The numeric or symbolic data type of the parameter values.", + "examples": [ + "string", + "float32", + "float16", + "bfloat16", + "int64", + "uint8" + ] + }, + "mimeType": { + "title": "MIME Type", + "description": "The media type of the parameter data.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/mediaType" + }, + "quantization": { + "title": "Quantization", + "description": "The quantization applied to the parameter values.", + "$ref": "#/$defs/quantization" + }, + "shape": { "type": "array", - "title": "Datasets", - "description": "An array of dataset references.", + "title": "Shape", + "description": "The dimensional shape of the parameter, for example tensor dimensions. A dynamic dimension is expressed as null or -1.", "items": { - "$ref": "#/$defs/datasetReference" + "oneOf": [ + { + "type": "integer", + "minimum": -1 + }, + { + "type": "null" + } + ] + }, + "examples": [ + [ + 1, + 512 + ], + [ + null, + 3, + 224, + 224 + ], + [ + -1, + 768 + ] + ] + }, + "processingStage": { + "type": "string", + "title": "Processing Stage", + "description": "The processing stage of the parameter relative to tokenization or encoding.", + "enum": [ + "pre-tokenizer", + "post-tokenizer", + "pre-encoder", + "post-encoder", + "pre-processing", + "post-processing", + "raw" + ], + "meta:enum": { + "pre-tokenizer": "Data before tokenization, for example a raw text string.", + "post-tokenizer": "Data after tokenization, for example token identifiers.", + "pre-encoder": "Data before an encoding transformation.", + "post-encoder": "Data after an encoding transformation.", + "pre-processing": "Data before any processing pipeline has been applied.", + "post-processing": "Data after all processing steps have been applied.", + "raw": "Raw unprocessed data." } }, - "datasetProcessingFormula": { - "title": "Dataset Processing Formula", - "description": "A reference to the dataset processing formula.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + "required": { + "type": "boolean", + "title": "Required", + "description": "Indicates whether this parameter is required.", + "default": false + }, + "defaultValue": { + "type": "string", + "title": "Default Value", + "description": "The default value for the parameter when a value is not provided." + }, + "constraints": { + "title": "Constraints", + "description": "Constraints on the parameter values.", + "$ref": "#/$defs/parameterConstraints" }, "externalReferences": { "type": "array", - "description": "External references provide a way to document systems, sites, and information that may be relevant but are not included with the BOM.", + "title": "External References", + "description": "External references to resources that are relevant to the parameter but are not included with the BOM.", "items": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" } }, "properties": { - "type": "array", "title": "Properties", - "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" - } + "description": "Provides the ability to document name-value pairs for the parameter. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" } } }, - "trainingProfile": { + "parameterConstraints": { "type": "object", - "description": "Information about the data and datasets used for training or finetuning the associated model.", + "title": "Parameter Constraints", + "description": "Constraints on the values of a model parameter.", + "additionalProperties": false, "properties": { - "trainingFormula":{ - "type":"object", - "title":"Training Formula", - "description":"The training formula for the model, with sequenced phases (tasks) such as pre-training, supervised fine-tuning (SFT) and alignment tuning, using the declared training datasets.", - "properties": { - "formulaRef": { - "title": "BOM Reference", - "description": "A reference the formula defined elsewhere in the BOM.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" - } - } + "minLength": { + "type": "integer", + "title": "Minimum Length", + "description": "The minimum length for text or sequence parameters.", + "minimum": 0 + }, + "maxLength": { + "type": "integer", + "title": "Maximum Length", + "description": "The maximum length for text or sequence parameters.", + "minimum": 0 + }, + "minValue": { + "type": "number", + "title": "Minimum Value", + "description": "The minimum numeric value." }, - "dataProcessingSpecs": { - "type": "array", - "title": "Data Processing Specifications", - "description": "An array of data processing specifications.", - "items": { - "$ref": "#/$defs/datasetProcessingSpec" - } + "maxValue": { + "type": "number", + "title": "Maximum Value", + "description": "The maximum numeric value." }, - "trainingDatasets": { + "allowedValues": { "type": "array", + "title": "Allowed Values", + "description": "The list of permitted values for the parameter.", "items": { - "$ref": "#/$defs/datasetReference" + "type": "string" } + }, + "pattern": { + "type": "string", + "title": "Pattern", + "description": "A regular expression pattern that string values of the parameter match." } } }, - "environmentalConsiderations": { + "datasetChoice": { + "title": "Dataset Choice", + "description": "A reference to a dataset documented as a component of type `data`, either within this BOM by `bom-ref` or in another BOM by BOM-Link.", + "anyOf": [ + { + "title": "Dataset Reference", + "description": "A reference to a component of type `data` within this BOM.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType" + }, + { + "title": "Dataset BOM-Link Reference", + "description": "A BOM-Link reference to a component of type `data` in another BOM.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/bomLinkElementType" + } + ], + "examples": [ + "training-dataset-1", + "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#openwebtext-subset" + ] + }, + "training": { "type": "object", - "title": "Environmental Considerations", - "description": "Describes various environmental impact metrics.", + "title": "Training", + "description": "Information about how a model was trained, including references to the datasets used and to the formula that captures the training process. Detailed training and data preparation workflows, including their inputs, outputs, and processing steps, are expressed with formulation and referenced from here.", "additionalProperties": false, "properties": { - "energyConsumptions": { - "title": "Energy Consumptions", - "description": "Describes energy consumption information incurred for one or more component lifecycle activities.", + "formula": { + "title": "Formula Reference", + "description": "References a formula, defined in formulation, that describes how the model was trained, for example as sequenced phases of pre-training, supervised fine-tuning, and alignment tuning.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType" + }, + "datasets": { "type": "array", + "title": "Training Datasets", + "description": "References to the datasets used for training or fine-tuning the model.", + "uniqueItems": true, "items": { - "$ref": "#/$defs/energyConsumption" + "$ref": "#/$defs/datasetChoice" } }, "properties": { - "type": "array", "title": "Properties", - "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" - } + "description": "Provides the ability to document name-value pairs for the training process. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" } } }, - "energyConsumption": { - "title": "Energy consumption", - "description": "Describes energy consumption information incurred for the specified lifecycle activity.", + "evaluation": { "type": "object", - "required": [ - "activity", - "energyProviders", - "activityEnergyCost" - ], + "title": "Evaluation", + "description": "A quantitative evaluation of a model, including performance metrics and supporting graphics such as confusion matrices and calibration plots.", "additionalProperties": false, "properties": { - "activity": { - "$comment": "TODO: allow for values from the CycloneDX Property Taxonomy in other domains.", - "title": "Activity", - "description": "The type of activity that is part of a machine learning model development or operational lifecycle.", - "type": "string", - "anyOf": [ - { - "enum": [ - "design", - "data-collection", - "data-preparation", - "training", - "fine-tuning", - "validation", - "deployment", - "inference" - ], - "meta:enum": { - "design": "A model design including problem framing, goal definition and algorithm selection.", - "data-collection": "Model data acquisition including search, selection and transfer.", - "data-preparation": "Model data preparation including data cleaning, labeling and conversion.", - "training": "Model building, training and generalized tuning.", - "fine-tuning": "Refining a trained model to produce desired outputs for a given problem space.", - "validation": "Model validation including model output evaluation and testing.", - "deployment": "Explicit model deployment to a target hosting infrastructure.", - "inference": "Generating an output response from a hosted model from a set of inputs." - } - }, - { - "pattern": "^cdx:[a-z0-9:-]+$" - } - ], - "examples": [ - "training", - "fine-tuning", - "inference" - ] - }, - "energyProviders": { - "title": "Energy Providers", - "description": "The provider(s) of the energy consumed by the associated model development lifecycle activity.", + "metrics": { "type": "array", + "title": "Performance Metrics", + "description": "The performance metrics being reported, for example accuracy, F1 score, precision, or benchmark scores.", "items": { - "$ref": "#/$defs/energyProvider" + "$ref": "#/$defs/performanceMetric" } }, - "activityEnergyCost": { - "title": "Activity Energy Cost", - "description": "The total energy cost associated with the model lifecycle activity.", - "$ref": "#/$defs/energyMeasure" - }, - "co2CostEquivalent": { - "title": "CO2 Equivalent Cost", - "description": "The CO2 cost (debit) equivalent to the total energy cost.", - "$ref": "#/$defs/co2Measure" - }, - "co2CostOffset": { - "title": "CO2 Cost Offset", - "description": "The CO2 offset (credit) for the CO2 equivalent cost.", - "$ref": "#/$defs/co2Measure" + "graphics": { + "title": "Graphics", + "description": "A collection of graphics that represent various measurements.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/graphicsCollection" }, "properties": { - "type": "array", "title": "Properties", - "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" - } - } - } - }, - "timeUnits": { - "enum": ["ns", "μs", "ms", "s", "min", "h"], - "meta:enum": { - "ns": "Nanoseconds - commonly used for high-precision timing measurements.", - "μs": "Microseconds - commonly used for fine-grained latency measurements.", - "ms": "Milliseconds - commonly used for latency measurements.", - "s": "Seconds - commonly used for latency and duration measurements.", - "min": "Minutes - commonly used for duration measurements.", - "h": "Hours - commonly used for duration measurements." - } - }, - "throughputUnits": { - "enum": ["tokens/s", "requests/s", "ops/s"], - "meta:enum": { - "tokens/s": "Tokens per second - commonly used for LLM throughput measurements.", - "requests/s": "Requests per second - commonly used for API and service throughput measurements.", - "ops/s": "Operations per second - commonly used for general throughput measurements." - } - }, - "computeUnits": { - "enum": ["FLOPS", "GFLOPS", "TFLOPS", "PFLOPS"], - "meta:enum": { - "FLOPS": "Floating-point operations per second.", - "GFLOPS": "Billion (giga) floating-point operations per second.", - "TFLOPS": "Trillion (tera) floating-point operations per second.", - "PFLOPS": "Quadrillion (peta) floating-point operations per second." - } - }, - "memoryUnits": { - "enum": ["B", "KB", "MB", "GB", "TB", "PB", "KiB", "MiB", "GiB", "TiB", "PiB"], - "meta:enum": { - "B": "Bytes", - "KB": "Kilobytes", - "MB": "Megabytes", - "GB": "Gigabytes", - "TB": "Terabytes", - "PB": "Petabytes", - "KiB": "Kibibytes", - "MiB": "Mebibytes", - "GiB": "Gibibytes", - "TiB": "Tebibytes", - "PiB": "Pebibytes" - } - }, - "ratioUnits": { - "enum": ["%", "ppm"], - "meta:enum": { - "%": "Percentage value (0-100) - commonly used for accuracy, precision, recall, and other ratio-based metrics.", - "ppm": "Parts per million - a dimensionless unit expressing the ratio of one part per million parts." - } - }, - "energyUnits": { - "enum": ["kWh"], - "meta:enum": { - "kWh": "Kilowatt-hour (kWh) is the energy delivered by one kilowatt (kW) of power for one hour (h)." - } - }, - "co2Units": { - "enum": ["tCO2eq"], - "meta:enum": { - "tCO2eq": "Tonnes (t) of carbon dioxide (CO2) equivalent (eq)." - } - }, - "customUnitPattern": { - "pattern": "^cdx:[a-z0-9:-]+$" - }, - "measure": { - "type": "object", - "title": "Measure", - "description": "A generic measurement with a value and unit.", - "required": [ - "value", - "unit" - ], - "additionalProperties": false, - "properties": { - "value": { - "type": "number", - "title": "Value", - "description": "The numeric value of the measurement.", - "examples": [127, 0.87, 2500, 52.3, 1.4] - }, - "unit": { - "type": "string", - "title": "Unit", - "description": "The unit of measurement.", - "anyOf": [ - {"$ref": "#/$defs/timeUnits"}, - {"$ref": "#/$defs/throughputUnits"}, - {"$ref": "#/$defs/computeUnits"}, - {"$ref": "#/$defs/memoryUnits"}, - {"$ref": "#/$defs/ratioUnits"}, - {"$ref": "#/$defs/energyUnits"}, - {"$ref": "#/$defs/co2Units"}, - {"$ref": "#/$defs/customUnitPattern"} - ], - "examples": [ - "ms", - "%", - "tokens/s", - "GB", - "kWh", - "tCO2eq" - ] + "description": "Provides the ability to document name-value pairs for the evaluation. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" } } }, - "energyMeasure": { - "type": "object", - "title": "Energy Measure", - "description": "A measure of energy.", - "$comment": "The unit property is intentionally constrained to 'kWh' only (not extensible) as energy measurements require standardized units for accurate comparison and reporting.", - "allOf": [ - { - "$ref": "#/$defs/measure" - }, - { - "properties": { - "unit": {"$ref": "#/$defs/energyUnits"} - } - } - ] - }, - "co2Measure": { - "type": "object", - "title": "CO2 Measure", - "description": "A measure of carbon dioxide (CO2).", - "$comment": "The unit property is intentionally constrained to 'tCO2eq' only (not extensible) as carbon emissions require standardized units for accurate environmental impact reporting.", - "allOf": [ - { - "$ref": "#/$defs/measure" - }, - { - "properties": { - "unit": {"$ref": "#/$defs/co2Units"} - } - } - ] - }, "performanceMeasure": { - "type": "object", "title": "Performance Measure", - "description": "A measure of performance with a value and unit.", - "$comment": "The unit property is extensible using the '^cdx:' pattern to accommodate diverse performance metrics across different AI/ML systems and use cases.", + "description": "A measure of model performance with a value and a unit. The unit is constrained to the predefined unit sets for time, throughput, compute, memory, and ratio measurements.", "allOf": [ { - "$ref": "#/$defs/measure" + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/measure" }, { + "required": [ + "unit" + ], "properties": { "unit": { "anyOf": [ - {"$ref": "#/$defs/timeUnits"}, - {"$ref": "#/$defs/throughputUnits"}, - {"$ref": "#/$defs/computeUnits"}, - {"$ref": "#/$defs/memoryUnits"}, - {"$ref": "#/$defs/ratioUnits"}, - {"$ref": "#/$defs/customUnitPattern"} + { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/timeUnits" + }, + { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/throughputUnits" + }, + { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/computeUnits" + }, + { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/memoryUnits" + }, + { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/ratioUnits" + } ] } } } ] }, - "energyProvider": { + "performanceMetric": { "type": "object", - "title": "Energy Provider", - "description": "Describes the physical provider of energy used for model development or operations.", + "title": "Performance Metric", + "description": "A reported performance metric of a model. Benchmarks and evaluation methodologies evolve rapidly, so the metric type and benchmark name are open strings; external references and evaluation dataset references establish the identity, version, and provenance of the evaluation.", + "additionalProperties": false, "required": [ - "organization", - "energySource", - "energyProvided" + "type", + "measure" ], - "additionalProperties": false, "properties": { - "bom-ref": { - "title": "BOM Reference", - "description": "An identifier which can be used to reference the energy provider elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" - }, - "description": { - "type": "string", - "title": "Description", - "description": "A description of the energy provider." - }, - "organization": { - "type": "object", - "title": "Organization", - "description": "The organization that provides energy.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/organizationalEntity" - }, - "energySource": { - "$comment": "TODO: allow for other values not listed to be proposed to the CycloneDX Property Taxonomy.", - "title": "Energy Source", - "description": "The energy source for the energy provider.", + "type": { "type": "string", - "anyOf": [ - { - "enum": [ - "coal", - "oil", - "natural-gas", - "nuclear", - "wind", - "solar", - "geothermal", - "hydropower", - "biofuel", - "biomass", - "hydrogen", - "tidal", - "unknown" - ], - "meta:enum": { - "coal": "Energy produced by types of coal.", - "oil": "Petroleum products (primarily crude oil and its derivative fuel oils).", - "natural-gas": "Hydrocarbon gas liquids (HGL) that occur as gases at atmospheric pressure and as liquids under higher pressures including Natural gas (C5H12 and heavier), Ethane (C2H6), Propane (C3H8), etc.", - "nuclear": "Energy produced from the cores of atoms (i.e., through nuclear fission or fusion).", - "wind": "Energy produced from moving air.", - "solar": "Energy produced from the sun (i.e., solar radiation).", - "geothermal": "Energy produced from heat within the earth.", - "hydropower": "Energy produced from flowing water.", - "biofuel": "Liquid fuels produced from biomass feedstocks (i.e., organic materials such as plants or animals).", - "biomass": "Energy produced from solid organic materials such as wood, agricultural crops, or organic waste.", - "hydrogen": "Energy produced from hydrogen fuel, which can be used in fuel cells or combustion.", - "tidal": "Energy produced from the rise and fall of ocean tides and tidal currents.", - "unknown": "The energy source is unknown." - } - }, - { - "pattern": "^cdx:[a-z0-9:-]+$" - } - ], + "title": "Metric Type", + "description": "The type of performance metric being reported.", "examples": [ - "solar", - "wind", - "natural-gas", - "nuclear" + "accuracy", + "f1", + "pass@1", + "mean-average-precision", + "perplexity", + "latency", + "throughput", + "elo" ] }, - "energyProvided": { - "$ref": "#/$defs/energyMeasure", - "title": "Energy Provided", - "description": "The energy provided by the energy source for an associated activity." - }, - "externalReferences": { - "type": "array", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" - }, - "title": "External References", - "description": "External references provide a way to document systems, sites, and information that may be relevant but are not included with the BOM. They may also establish specific relationships within or external to the BOM." - } - } - }, - "graphic": { - "$todos": [ - "Unsure if needed for 2.0. If so, is there a common object we can reuse?" - ], - "type": "object", - "title": "Graphic", - "additionalProperties": false, - "properties": { - "name": { - "title": "Name", - "description": "The name of the graphic.", - "type": "string" - }, - "image": { - "title": "Graphic Image", - "description": "The graphic (vector or raster). Base64 encoding must be specified for binary images.", - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/attachment" - } - } - }, - "performanceMetric": { - "type": "object", - "title": "Performance Metric", - "$comment": "Values not listed can be proposed to the CycloneDX Property Taxonomy.", - "$todos": [ - "Update AI/ML property taxonomy with performance metric type enum values." - ], - "additionalProperties": false, - "properties": { - "type": { - "title": "Type", - "description": "The type of performance metric used for AI model evaluation.", + "benchmark": { "type": "string", - "anyOf": [ - { - "enum": [ - "mmlu-pro", - "gpqa", - "math-500", - "humaneval", - "swe-bench", - "terminal-bench", - "gdpval", - "browsecomp", - "bfcl", - "taubench", - "ifeval", - "livebench", - "webarena", - "lmsys-elo", - "strongreject", - "perplexity", - "bleu", - "rouge", - "latency", - "throughput", - "coco", - "vqa", - "imagenet" - ], - "meta:enum": { - "mmlu-pro": "Massive Multitask Language Understanding Pro - The current standard for broad, expert-level academic and professional reasoning across multiple disciplines.", - "gpqa": "Graduate-Level Google-Proof Q&A - A highly difficult dataset used to test advanced, PhD-level reasoning and scientific problem-solving capabilities.", - "math-500": "A subset of the MATH benchmark used to evaluate complex, multi-step mathematical reasoning and logic.", - "humaneval": "The industry standard benchmark for evaluating Python code generation and functional programming synthesis.", - "swe-bench": "Software Engineering Benchmark - Evaluates a model's agentic ability to resolve real-world software engineering issues and patches within complete, live code repositories.", - "terminal-bench": "Terminal-Bench - Evaluates an agent's ability to complete long-horizon, autonomous tasks inside a real shell environment, covering system administration, DevOps, and software engineering workflows.", - "gdpval": "GDPVal - A cross-domain general performance validation benchmark measuring an agent's instruction-following, tool-use, and reasoning fidelity across diverse real-world tasks.", - "browsecomp": "BrowseComp - OpenAI's benchmark for evaluating an agent's ability to answer hard, multi-hop research questions that require deep, autonomous web browsing to resolve.", - "bfcl": "Berkeley Function-Calling Leaderboard - Evaluates a model's ability to correctly call external tools and APIs by selecting the right function and generating accurate, schema-conformant arguments.", - "taubench": "τ-bench (TauBench) - An agentic benchmark assessing a model's ability to complete multi-step, tool-augmented tasks in simulated real-world domains such as retail and airline customer service.", - "ifeval": "Instruction Following Evaluation - Tests a model's ability to strictly adhere to verifiable formatting constraints (e.g., specific word counts, starting sentences with specific words).", - "livebench": "A frequently updated, contamination-free benchmark designed to test reasoning, math, and coding without the risk of models memorizing static test data.", - "webarena": "An agentic benchmark evaluating a model's ability to perform complex, multi-step tasks using a web browser, APIs, and OS environments.", - "lmsys-elo": "A crowd-sourced human preference rating derived from millions of blind A/B battle tests in the LMSYS Chatbot Arena.", - "strongreject": "A standardized metric for measuring safety and alignment by evaluating how reliably a model refuses harmful prompts while avoiding false positives.", - "perplexity": "A fundamental language model metric measuring how well a probability model predicts a sample. Lower perplexity indicates better prediction.", - "bleu": "Bilingual Evaluation Understudy - A metric for evaluating machine translation quality by comparing generated text to reference translations.", - "rouge": "Recall-Oriented Understudy for Gisting Evaluation - A set of metrics for evaluating automatic summarization and machine translation by comparing overlap with reference texts.", - "latency": "The time delay between input submission and output generation, typically measured in milliseconds or seconds. Critical for real-time applications.", - "throughput": "The rate at which a model processes requests or tokens, typically measured in tokens per second or requests per second.", - "coco": "Common Objects in Context - A large-scale object detection, segmentation, and captioning dataset used to evaluate computer vision models.", - "vqa": "Visual Question Answering - Evaluates a model's ability to answer questions about images, testing multimodal understanding.", - "imagenet": "A large visual database designed for visual object recognition research, commonly used to benchmark image classification models." - } - }, - { - "pattern": "^cdx:ai-ml:model:metric:performance:[a-z0-9:-]+$" - } - ], + "title": "Benchmark", + "description": "The name of the benchmark or evaluation suite that produced the metric, if any.", "examples": [ "mmlu-pro", "humaneval", - "swe-bench" + "imagenet-1k" ] }, "measure": { @@ -1151,32 +1023,31 @@ "$ref": "#/$defs/performanceMeasure" }, "slice": { - "title": "Slice", - "description": "The name of the slice this metric was computed on. By default, assume this metric is not sliced.", "type": "string", + "title": "Slice", + "description": "The name of the data slice on which the metric was computed, for example a demographic group, a language, or a domain. When absent, the metric applies to the entire evaluation population. Slice level metrics provide the quantitative evidence for fairness and bias risks documented with the risk model.", "examples": [ "overall", "age:18-34", "language:fr", - "gender:female", "region:sub-saharan-africa" ] }, "confidenceInterval": { + "type": "object", "title": "Confidence Interval", "description": "The confidence interval of the metric.", - "type": "object", "additionalProperties": false, "properties": { "lowerBound": { + "type": "number", "title": "Lower Bound", - "description": "The lower bound of the confidence interval.", - "type": "string" + "description": "The lower bound of the confidence interval." }, "upperBound": { + "type": "number", "title": "Upper Bound", - "description": "The upper bound of the confidence interval.", - "type": "string" + "description": "The upper bound of the confidence interval." } } }, @@ -1185,63 +1056,36 @@ "title": "Evaluation Datasets", "description": "References to the datasets or dataset subsets used to compute this performance metric.", "items": { - "$ref": "#/$defs/datasetReference" + "$ref": "#/$defs/datasetChoice" } }, "externalReferences": { "type": "array", "title": "External References", - "description": "External references to well-known AI model evaluations, benchmarks, leaderboards, or evaluation methodologies.", + "description": "External references to resources that are relevant to the metric, such as benchmark definitions, leaderboards, or evaluation methodologies but are not included with the BOM.", "items": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" } }, "properties": { - "type": "array", "title": "Properties", - "description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", - "items": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/property" - } + "description": "Provides the ability to document name-value pairs for the metric. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" } }, "examples": [ { - "type": "mmlu-pro", + "type": "accuracy", + "benchmark": "mmlu-pro", "measure": { "value": 58.2, "unit": "%" }, "confidenceInterval": { - "lowerBound": "57.48", - "upperBound": "58.92" - } - }, - { - "type": "humaneval", - "measure": { - "value": 0.87, - "unit": "%" + "lowerBound": 57.5, + "upperBound": 58.9 } }, - { - "type": "swe-bench", - "measure": { - "value": 45.3, - "unit": "%" - }, - "evaluationDatasets": [ - { - "dataRef": "data-ref:swe-bench-lite-dataset" - } - ], - "externalReferences": [ - { - "type": "distribution", - "url": "https://huggingface.co/datasets/princeton-nlp/SWE-bench_Lite" - } - ] - }, { "type": "latency", "measure": { @@ -1252,552 +1096,259 @@ { "name": "percentile", "value": "p95" - }, - { - "name": "hardware", - "value": "NVIDIA A100 GPU" - } - ] - }, - { - "type": "throughput", - "measure": { - "value": 2500, - "unit": "tokens/s" - }, - "properties": [ - { - "name": "batch-size", - "value": "32" - }, - { - "name": "hardware", - "value": "NVIDIA A100 GPU" - } - ] - }, - { - "type": "coco", - "measure": { - "value": 52.3, - "unit": "percentage" - }, - "properties": [ - { - "name": "metric", - "value": "mAP" - }, - { - "name": "iou-threshold", - "value": "0.5" - } - ], - "externalReferences": [ - { - "type": "distribution", - "url": "https://cocodataset.org/" } ] }, { - "type": "bleu", + "type": "accuracy", + "benchmark": "imagenet-1k", + "slice": "top-5", "measure": { - "value": 34.5, - "unit": "percentage" - }, - "properties": [ - { - "name": "variant", - "value": "BLEU-4" - }, - { - "name": "per-class-precision-1", - "value": "0.78" - }, - { - "name": "per-class-precision-2", - "value": "0.52" - }, - { - "name": "per-class-precision-3", - "value": "0.38" - }, - { - "name": "per-class-precision-4", - "value": "0.29" - }, - { - "name": "brevity-penalty", - "value": "0.95" - } - ] + "value": 94.7, + "unit": "%" + } } ] }, - "quantitativeAnalysis": { + "environmental": { "type": "object", - "title": "Quantitative Analysis", - "description": "A quantitative analysis of the model", + "title": "Environmental Impact", + "description": "Measured environmental impacts of a model across its lifecycle activities. This object captures factual measurements. Environmental risks informed by these measurements are expressed with the risk model and reference the model component.", "additionalProperties": false, "properties": { - "performanceMetrics": { + "energyConsumptions": { "type": "array", - "title": "Performance Metrics", - "description": "The model performance metrics being reported. Examples may include accuracy, F1 score, precision, top-3 error rates, MSC, etc.", - "items": { "$ref": "#/definitions/performanceMetric" } + "title": "Energy Consumptions", + "description": "The energy consumption incurred for one or more lifecycle activities of the model.", + "items": { + "$ref": "#/$defs/energyConsumption" + } }, - "graphics": { "$ref": "#/definitions/graphicsCollection" } + "properties": { + "title": "Properties", + "description": "Provides the ability to document name-value pairs for environmental impact. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } } }, - "modelParameters": { - "type": "object", - "title": "Model Parameters", - "description": "Describes the input and output parameters of an AI model, including support for various modalities and data formats.", - "additionalProperties": false, - "properties": { - "inputs": { - "type": "array", - "title": "Model Inputs", - "description": "The input parameters accepted by the model.", - "items": { - "$ref": "#/$defs/modelParameter" - }, - "uniqueItems": true - }, - "outputs": { - "type": "array", - "title": "Model Outputs", - "description": "The output parameters produced by the model.", - "items": { - "$ref": "#/$defs/modelParameter" - }, - "uniqueItems": true - }, - "properties": { - "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" - } - } - }, - "modelParameter": { - "type": "object", - "title": "Model Parameter", - "description": "Describes a single input or output parameter of an AI model, supporting various modalities and encoding formats.", - "additionalProperties": false, - "required": [ - "name" - ], - "properties": { - "name": { - "type": "string", - "title": "Name", - "description": "The name of the parameter.", - "examples": [ - "prompt", - "image", - "audio", - "logits", - "embeddings" - ] - }, - "description": { - "type": "string", - "title": "Description", - "description": "A description of the parameter and its purpose." - }, - "modality": { + "modelActivity": { + "title": "Model Activity", + "description": "An activity that is part of the development or operational lifecycle of a machine learning model. Use the custom option for activities not covered by the predefined values.", + "oneOf": [ + { + "title": "Predefined Activity", "type": "string", - "title": "Modality", - "description": "The type of data modality for this parameter.", - "anyOf": [ - { - "enum": [ - "text", - "image", - "audio", - "video", - "multimodal", - "embedding", - "logits", - "other" - ], - "meta:enum": { - "text": "Natural language text input or output.", - "image": "Visual image data input or output.", - "audio": "Audio or speech data input or output.", - "video": "Video data input or output.", - "multimodal": "Combined multiple modalities (e.g., text and image).", - "embedding": "Dense vector representations in a continuous space.", - "logits": "Raw unnormalized model outputs before activation functions.", - "other": "Other modality types not explicitly listed." - } - }, - { - "pattern": "^cdx:ai-ml:model:task:[a-z0-9:-]+$" - } + "enum": [ + "design", + "data-collection", + "data-preparation", + "training", + "fine-tuning", + "validation", + "deployment", + "inference" ], - "examples": [ - "text", - "image", - "audio", - "logits" - ] + "meta:enum": { + "design": "Model design, including problem framing, goal definition, and algorithm selection.", + "data-collection": "Model data acquisition, including search, selection, and transfer.", + "data-preparation": "Model data preparation, including data cleaning, labelling, and conversion.", + "training": "Model building, training, and generalized tuning.", + "fine-tuning": "Refining a trained model to produce desired outputs for a given problem space.", + "validation": "Model validation, including model output evaluation and testing.", + "deployment": "Model deployment to a target hosting infrastructure.", + "inference": "Generating an output response from a hosted model from a set of inputs." + } }, - "format": { + { "type": "object", - "title": "Format", - "$comment": "TODO: There should be a common place in the CycloneDX Property Taxonomy to define encoding types", - "description": "Describes the format and encoding of the parameter data.", + "title": "Custom Activity", + "required": [ + "name" + ], "additionalProperties": false, "properties": { - "dataType": { + "name": { "type": "string", - "title": "Data Type", - "description": "The data type of the parameter.", - "examples": [ - "string", - "float32", - "fp16", - "bf16", - "int64", - "uint8", - "q8_0" - ] - }, - "encoding": { - "type": "string", - "title": "Encoding", - "description": "The encoding format of the parameter data.", - "anyOf": [ - { - "enum": [ - "utf-8", - "ascii", - "base64", - "jpeg", - "png", - "wav", - "mp3", - "flac", - "raw", - "tokenized", - "other" - ], - "meta:enum": { - "utf-8": "UTF-8 text encoding.", - "ascii": "ASCII text encoding.", - "base64": "Base64 encoded binary data.", - "jpeg": "JPEG image format.", - "png": "PNG image format.", - "wav": "WAV audio format.", - "mp3": "MP3 audio format.", - "flac": "FLAC lossless audio format.", - "raw": "Raw binary data without specific encoding.", - "tokenized": "Pre-tokenized input (token IDs).", - "other": "Other encoding format not explicitly listed." - } - }, - { - "pattern": "^cdx:ai-ml:[a-z0-9:-]+$" - } - ], - "examples": [ - "utf-8", - "tokenized", - "jpeg", - "wav" - ] + "title": "Name", + "description": "The name of the custom activity." }, - "mimeType": { + "description": { "type": "string", - "title": "MIME Type", - "description": "The MIME type of the parameter data.", - "examples": [ - "text/plain", - "image/jpeg", - "audio/wav", - "application/octet-stream" - ] + "title": "Description", + "description": "A description of the custom activity." } } + } + ] + }, + "energyConsumption": { + "type": "object", + "title": "Energy Consumption", + "description": "The energy consumption incurred for a specific lifecycle activity of a model.", + "additionalProperties": false, + "required": [ + "activity", + "activityEnergyCost" + ], + "properties": { + "activity": { + "title": "Activity", + "description": "The lifecycle activity that incurred the energy consumption.", + "$ref": "#/$defs/modelActivity" }, - "shape": { + "formula": { + "title": "Formula Reference", + "description": "References a formula, defined in formulation, that captures the process which incurred this energy consumption, for example a training workflow.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refLinkType" + }, + "energyProviders": { "type": "array", - "title": "Shape", - "description": "The dimensional shape of the parameter (e.g., tensor dimensions). Use -1 or null for dynamic dimensions.", + "title": "Energy Providers", + "description": "The providers of the energy consumed by the activity.", "items": { - "oneOf": [ - { - "type": "integer", - "minimum": -1 - }, - { - "type": "null" - } - ] - }, - "examples": [ - [1, 512], - [null, 3, 224, 224], - [-1, 768] - ] - }, - "processingStage": { - "type": "string", - "title": "Processing Stage", - "description": "Indicates the processing stage of the parameter relative to tokenization or encoding.", - "enum": [ - "pre-tokenizer", - "post-tokenizer", - "pre-encoder", - "post-encoder", - "raw", - "processed" - ], - "meta:enum": { - "pre-tokenizer": "Data before tokenization (e.g., raw text string).", - "post-tokenizer": "Data after tokenization (e.g., token IDs).", - "pre-encoder": "Data before encoding transformation.", - "post-encoder": "Data after encoding transformation.", - "raw": "Raw unprocessed data.", - "processed": "Fully processed data ready for model consumption or output." - }, - "examples": [ - "pre-tokenizer", - "post-tokenizer", - "raw" - ] + "$ref": "#/$defs/energyProvider" + } }, - "required": { - "type": "boolean", - "title": "Required", - "description": "Indicates whether this parameter is required.", - "default": false + "activityEnergyCost": { + "title": "Activity Energy Cost", + "description": "The total energy cost associated with the activity.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/energyMeasure" }, - "defaultValue": { - "type": "string", - "title": "Default Value", - "description": "The default value for the parameter if not provided." + "co2CostEquivalent": { + "title": "CO2 Equivalent Cost", + "description": "The carbon dioxide equivalent cost of the total energy cost.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/co2Measure" }, - "constraints": { - "type": "object", - "title": "Constraints", - "description": "Constraints on the parameter values.", - "additionalProperties": false, - "properties": { - "minLength": { - "type": "integer", - "title": "Minimum Length", - "description": "Minimum length for text or sequence parameters.", - "minimum": 0 - }, - "maxLength": { - "type": "integer", - "title": "Maximum Length", - "description": "Maximum length for text or sequence parameters.", - "minimum": 0 - }, - "minValue": { - "type": "number", - "title": "Minimum Value", - "description": "Minimum numeric value." - }, - "maxValue": { - "type": "number", - "title": "Maximum Value", - "description": "Maximum numeric value." - }, - "allowedValues": { - "type": "array", - "title": "Allowed Values", - "description": "List of allowed values for the parameter.", - "items": { - "type": "string" - } - }, - "pattern": { - "type": "string", - "title": "Pattern", - "description": "Regular expression pattern for validating string parameters." - } - } + "co2CostOffset": { + "title": "CO2 Cost Offset", + "description": "The carbon dioxide offset credited against the carbon dioxide equivalent cost.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/co2Measure" }, "externalReferences": { "type": "array", "title": "External References", - "description": "External references to documentation or specifications for this parameter.", + "description": "External references to resources that are relevant to the energy consumption but are not included with the BOM.", "items": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" } }, "properties": { + "title": "Properties", + "description": "Provides the ability to document name-value pairs for the energy consumption. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" } - }, - "examples": [ - { - "name": "prompt", - "description": "Text prompt input to the model", - "modality": "text", - "format": { - "dataType": "string", - "encoding": "utf-8" - }, - "processingStage": "pre-tokenizer", - "required": true - }, - { - "name": "input_ids", - "description": "Tokenized input IDs", - "modality": "text", - "format": { - "dataType": "int64", - "encoding": "tokenized" - }, - "shape": [1, null], - "processingStage": "post-tokenizer", - "required": true - }, - { - "name": "image", - "description": "Input image", - "modality": "image", - "format": { - "dataType": "uint8", - "encoding": "jpeg", - "mimeType": "image/jpeg" - }, - "shape": [null, 3, 224, 224], - "required": true - }, - { - "name": "audio", - "description": "Audio waveform input", - "modality": "audio", - "format": { - "dataType": "float32", - "encoding": "wav", - "mimeType": "audio/wav" - }, - "shape": [1, null], - "required": true - }, - { - "name": "logits", - "description": "Raw model output logits", - "modality": "logits", - "format": { - "dataType": "fp16" - }, - "shape": [1, null, 50257], - "processingStage": "raw" - }, - { - "name": "generated_text", - "description": "Generated text output", - "modality": "text", - "format": { - "dataType": "string", - "encoding": "utf-8" - }, - "processingStage": "post-tokenizer" - } - ] + } }, - "modelTaskType": { - "$comment": "Values not listed can be proposed to the CycloneDX Property Taxonomy.", - "$todos": [ - "Update AI/ML property taxonomy with task enum values." - ], - "type": "string", - "title": "Task Type", - "description": "A machine learning task that a model is designed to perform.", - "anyOf": [ + "energySource": { + "title": "Energy Source", + "description": "The source of the energy provided by an energy provider. Use the custom option for sources not covered by the predefined values.", + "oneOf": [ { + "title": "Predefined Energy Source", + "type": "string", "enum": [ - "text-generation", - "text-classification", - "token-classification", - "question-answering", - "summarization", - "translation", - "text-to-text", - "fill-mask", - "sentence-similarity", - "text-to-image", - "text-to-video", - "text-to-audio", - "text-to-speech", - "image-classification", - "image-segmentation", - "object-detection", - "image-to-image", - "image-to-text", - "depth-estimation", - "video-classification", - "audio-classification", - "automatic-speech-recognition", - "audio-to-audio", - "voice-activity-detection", - "tabular-classification", - "tabular-regression", - "time-series-forecasting", - "reinforcement-learning", - "robotics", - "graph-ml", - "feature-extraction", - "embedding", - "zero-shot-classification", - "few-shot-learning", - "other" + "coal", + "oil", + "natural-gas", + "nuclear", + "wind", + "solar", + "geothermal", + "hydropower", + "biofuel", + "biomass", + "hydrogen", + "tidal", + "unknown" ], "meta:enum": { - "text-generation": "Generate coherent text continuations from prompts (e.g., GPT models).", - "text-classification": "Classify text into predefined categories (e.g., sentiment analysis, topic classification).", - "token-classification": "Classify individual tokens in text (e.g., named entity recognition, part-of-speech tagging).", - "question-answering": "Answer questions based on context or knowledge (e.g., extractive or generative QA).", - "summarization": "Generate concise summaries of longer text documents.", - "translation": "Translate text from one language to another.", - "text-to-text": "Transform text from one form to another (e.g., paraphrasing, style transfer).", - "fill-mask": "Predict masked tokens in text (e.g., BERT-style masked language modeling).", - "sentence-similarity": "Compute semantic similarity between text sequences.", - "text-to-image": "Generate images from text descriptions (e.g., DALL-E, Stable Diffusion).", - "text-to-video": "Generate video content from text descriptions.", - "text-to-audio": "Generate audio or music from text descriptions.", - "text-to-speech": "Convert text to spoken audio (speech synthesis).", - "image-classification": "Classify images into predefined categories (e.g., ResNet, ViT).", - "image-segmentation": "Segment images into regions or objects (semantic or instance segmentation).", - "object-detection": "Detect and localize objects in images (e.g., YOLO, R-CNN).", - "image-to-image": "Transform images (e.g., style transfer, super-resolution, inpainting).", - "image-to-text": "Generate text descriptions from images (e.g., image captioning).", - "depth-estimation": "Estimate depth information from images.", - "video-classification": "Classify video content into categories.", - "audio-classification": "Classify audio into categories (e.g., sound event detection).", - "automatic-speech-recognition": "Transcribe spoken audio to text (e.g., Whisper).", - "audio-to-audio": "Transform audio (e.g., noise reduction, voice conversion).", - "voice-activity-detection": "Detect presence of speech in audio streams.", - "tabular-classification": "Classify structured tabular data.", - "tabular-regression": "Predict continuous values from structured tabular data.", - "time-series-forecasting": "Predict future values in time series data.", - "reinforcement-learning": "Learn optimal actions through interaction with an environment.", - "robotics": "Control and decision-making for robotic systems.", - "graph-ml": "Machine learning tasks on graph-structured data.", - "feature-extraction": "Extract meaningful features or representations from data.", - "embedding": "Generate dense vector representations of data.", - "zero-shot-classification": "Classify data without task-specific training examples.", - "few-shot-learning": "Learn from very few examples per class.", - "other": "Other machine learning tasks not covered by predefined categories." + "coal": "Energy produced from coal.", + "oil": "Energy produced from petroleum products, primarily crude oil and its derivative fuel oils.", + "natural-gas": "Energy produced from hydrocarbon gases, including natural gas, ethane, and propane.", + "nuclear": "Energy produced from the cores of atoms through nuclear fission or fusion.", + "wind": "Energy produced from moving air.", + "solar": "Energy produced from solar radiation.", + "geothermal": "Energy produced from heat within the earth.", + "hydropower": "Energy produced from flowing water.", + "biofuel": "Energy produced from liquid fuels derived from biomass feedstocks.", + "biomass": "Energy produced from solid organic materials such as wood, agricultural crops, or organic waste.", + "hydrogen": "Energy produced from hydrogen fuel in fuel cells or combustion.", + "tidal": "Energy produced from the rise and fall of ocean tides and tidal currents.", + "unknown": "The energy source is unknown." } }, { - "pattern": "^cdx:ai-ml:model:task:[a-z0-9:-]+$" + "type": "object", + "title": "Custom Energy Source", + "required": [ + "name" + ], + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the custom energy source." + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the custom energy source." + } + } } - ], - "examples": [ - "text-generation", - "image-classification", - "object-detection", - "automatic-speech-recognition" ] + }, + "energyProvider": { + "type": "object", + "title": "Energy Provider", + "description": "The provider of energy consumed during model development or operations.", + "additionalProperties": false, + "required": [ + "provider", + "energySource", + "energyProvided" + ], + "properties": { + "bom-ref": { + "title": "BOM Reference", + "description": "An identifier which can be used to reference the energy provider elsewhere in the BOM. Every `bom-ref` must be unique within the BOM.\nValue SHOULD not start with the BOM-Link intro 'urn:cdx:' to avoid conflicts with BOM-Links.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/refType" + }, + "description": { + "type": "string", + "title": "Description", + "description": "A description of the energy provider." + }, + "provider": { + "title": "Provider", + "description": "The party that provides the consumed energy, typically an organization.", + "$ref": "cyclonedx-party-2.0.schema.json#/$defs/partyChoice" + }, + "energySource": { + "title": "Energy Source", + "description": "The source of the provided energy.", + "$ref": "#/$defs/energySource" + }, + "energyProvided": { + "title": "Energy Provided", + "description": "The energy provided by the energy source for the associated activity.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/energyMeasure" + }, + "externalReferences": { + "type": "array", + "title": "External References", + "description": "External references to resources that are relevant to the energy provider but are not included with the BOM.", + "items": { + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/externalReference" + } + }, + "properties": { + "title": "Properties", + "description": "Provides the ability to document name-value pairs for the energy provider. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.", + "$ref": "cyclonedx-common-2.0.schema.json#/$defs/properties" + } + } } } -} \ No newline at end of file +} diff --git a/schema/2.0/model/cyclonedx-common-2.0.schema.json b/schema/2.0/model/cyclonedx-common-2.0.schema.json index dd7ec3de6..4764dafaa 100644 --- a/schema/2.0/model/cyclonedx-common-2.0.schema.json +++ b/schema/2.0/model/cyclonedx-common-2.0.schema.json @@ -775,6 +775,168 @@ "$ref": "cyclonedx-jss_X590_2023_10-2.0.schema.json#/$defs/signatures", "title": "Signatures", "description": "Enveloped signatures in [JSON Signature Scheme (JSS/ITU-T X.590)](https://www.itu.int/epublications/publication/itu-t-x-590-2023-10-json-signature-scheme-jss)." + }, + "measure": { + "type": "object", + "title": "Measure", + "description": "A measurement expressed as a numeric value and a unit. Contexts that use this definition may constrain the permitted units. When the unit is omitted, the value represents a count.", + "additionalProperties": false, + "required": ["value"], + "properties": { + "value": { + "type": "number", + "title": "Value", + "description": "The numeric value of the measurement.", + "examples": [127, 0.87, 2500, 52.3] + }, + "unit": { + "type": "string", + "title": "Unit", + "description": "The unit of measure.", + "examples": ["ms", "%", "tokens/s", "GiB", "kWh", "tCO2eq"] + } + } + }, + "timeUnits": { + "title": "Time Units", + "description": "Units of time for duration and latency measurements.", + "enum": ["ns", "us", "ms", "s", "min", "h"], + "meta:enum": { + "ns": "Nanoseconds, commonly used for high precision timing measurements.", + "us": "Microseconds, commonly used for fine grained latency measurements.", + "ms": "Milliseconds, commonly used for latency measurements.", + "s": "Seconds, commonly used for latency and duration measurements.", + "min": "Minutes, commonly used for duration measurements.", + "h": "Hours, commonly used for duration measurements." + } + }, + "throughputUnits": { + "title": "Throughput Units", + "description": "Units of throughput for rate measurements.", + "enum": ["tokens/s", "requests/s", "ops/s"], + "meta:enum": { + "tokens/s": "Tokens per second, commonly used for language model throughput measurements.", + "requests/s": "Requests per second, commonly used for API and service throughput measurements.", + "ops/s": "Operations per second, commonly used for general throughput measurements." + } + }, + "computeUnits": { + "title": "Compute Units", + "description": "Units of computational work and computational rate.", + "enum": ["FLOP", "FLOPS", "GFLOPS", "TFLOPS", "PFLOPS"], + "meta:enum": { + "FLOP": "Total floating point operations, commonly used to express cumulative training compute.", + "FLOPS": "Floating point operations per second.", + "GFLOPS": "Billion floating point operations per second.", + "TFLOPS": "Trillion floating point operations per second.", + "PFLOPS": "Quadrillion floating point operations per second." + } + }, + "memoryUnits": { + "title": "Memory Units", + "description": "Units of digital information for memory and storage measurements.", + "enum": ["B", "KB", "MB", "GB", "TB", "PB", "KiB", "MiB", "GiB", "TiB", "PiB"], + "meta:enum": { + "B": "Bytes.", + "KB": "Kilobytes.", + "MB": "Megabytes.", + "GB": "Gigabytes.", + "TB": "Terabytes.", + "PB": "Petabytes.", + "KiB": "Kibibytes.", + "MiB": "Mebibytes.", + "GiB": "Gibibytes.", + "TiB": "Tebibytes.", + "PiB": "Pebibytes." + } + }, + "ratioUnits": { + "title": "Ratio Units", + "description": "Units for dimensionless ratio measurements.", + "enum": ["%", "ppm"], + "meta:enum": { + "%": "Percentage, commonly used for accuracy, precision, recall, and other ratio based metrics.", + "ppm": "Parts per million, a dimensionless unit expressing the ratio of one part per million parts." + } + }, + "energyUnits": { + "title": "Energy Units", + "description": "Units of energy.", + "enum": ["kWh"], + "meta:enum": { + "kWh": "Kilowatt hour, the energy delivered by one kilowatt of power for one hour." + } + }, + "co2Units": { + "title": "CO2 Units", + "description": "Units of carbon dioxide equivalent.", + "enum": ["tCO2eq"], + "meta:enum": { + "tCO2eq": "Tonnes of carbon dioxide equivalent." + } + }, + "energyMeasure": { + "title": "Energy Measure", + "description": "A measure of energy. The unit is constrained to a standardized energy unit for accurate comparison and reporting.", + "allOf": [ + {"$ref": "#/$defs/measure"}, + { + "required": ["unit"], + "properties": { + "unit": {"$ref": "#/$defs/energyUnits"} + } + } + ] + }, + "co2Measure": { + "title": "CO2 Measure", + "description": "A measure of carbon dioxide equivalent. The unit is constrained to a standardized unit for accurate environmental impact reporting.", + "allOf": [ + {"$ref": "#/$defs/measure"}, + { + "required": ["unit"], + "properties": { + "unit": {"$ref": "#/$defs/co2Units"} + } + } + ] + }, + "graphic": { + "type": "object", + "title": "Graphic", + "description": "A named graphic, such as a chart, plot, or diagram.", + "additionalProperties": false, + "properties": { + "name": { + "type": "string", + "title": "Name", + "description": "The name of the graphic." + }, + "image": { + "title": "Graphic Image", + "description": "The graphic, which may be a vector or raster image. Base64 encoding shall be specified for binary images.", + "$ref": "#/$defs/attachment" + } + } + }, + "graphicsCollection": { + "type": "object", + "title": "Graphics Collection", + "description": "A collection of graphics that represent various measurements.", + "additionalProperties": false, + "properties": { + "description": { + "type": "string", + "title": "Description", + "description": "A description of this collection of graphics." + }, + "collection": { + "type": "array", + "title": "Collection", + "description": "A collection of graphics.", + "items": {"$ref": "#/$defs/graphic"} + } + } } } } diff --git a/schema/2.0/model/cyclonedx-component-2.0.schema.json b/schema/2.0/model/cyclonedx-component-2.0.schema.json index 7b3dae3f6..c5d205b8b 100644 --- a/schema/2.0/model/cyclonedx-component-2.0.schema.json +++ b/schema/2.0/model/cyclonedx-component-2.0.schema.json @@ -200,9 +200,10 @@ "title": "Release notes", "description": "Specifies release notes." }, - "modelCard": { - "$ref": "cyclonedx-ai-modelcard-2.0.schema.json#/$defs/modelCard", - "title": "AI/ML Model Card" + "modelProperties": { + "$ref": "cyclonedx-ai-ml-2.0.schema.json#/$defs/modelProperties", + "title": "AI/ML Model Properties", + "description": "Intrinsic technical characteristics of a machine learning model. This object SHOULD be specified for any component of type `machine-learning-model` and shall not be specified for other component types." }, "data": { "type": "array", @@ -686,7 +687,7 @@ "type": "string" } }, - "graphics": { "$ref": "cyclonedx-ai-modelcard-2.0.schema.json#/$defs/graphicsCollection" }, + "graphics": { "$ref": "cyclonedx-common-2.0.schema.json#/$defs/graphicsCollection" }, "description": { "title": "Dataset Description", "description": "A description of the dataset. Can describe size of dataset, whether it's used for source code, training, testing, or validation, etc.", diff --git a/tools/src/test/resources/2.0/invalid-ai-ml-energy-unit-2.0.json b/tools/src/test/resources/2.0/invalid-ai-ml-energy-unit-2.0.json new file mode 100644 index 000000000..8420b130d --- /dev/null +++ b/tools/src/test/resources/2.0/invalid-ai-ml-energy-unit-2.0.json @@ -0,0 +1,252 @@ +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "serialNumber": "urn:uuid:8b41cf82-52e6-46d5-9f45-e6c2ab4bf003", + "version": 1, + "metadata": { + "timestamp": "2026-08-13T12:00:00Z" + }, + "components": [ + { + "type": "machine-learning-model", + "bom-ref": "model-1", + "name": "acme-summarizer", + "version": "2.1.0", + "description": "A transformer language model fine-tuned for clinical note summarization.", + "parties": [ + { + "bom-ref": "party-acme", + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Acme Health AI" + } + }, + { + "bom-ref": "party-clinicians", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "description": "Clinicians who review generated summaries before entering them into patient records." + } + } + ], + "modelProperties": { + "learningTypes": [ + "self-supervised", + "reinforcement-learning" + ], + "tasks": [ + "summarization", + "text-generation" + ], + "architecture": { + "name": "acme-lm-7b", + "description": "Decoder-only transformer with grouped-query attention and rotary positional embeddings.", + "family": "transformer", + "features": [ + "decoder-only", + "grouped-query-attention", + "rotary-position-embedding", + { + "name": "clinical-adapter", + "description": "Domain adapter layers trained on de-identified clinical text." + } + ], + "topology": "dense" + }, + "parameterCount": 7000000000, + "quantization": { + "method": "k-quant", + "bits": 4, + "scheme": "affine", + "granularity": "per-group", + "groupSize": 128, + "axis": 0 + }, + "inputs": [ + { + "name": "prompt", + "description": "The clinical note to summarize.", + "modality": "text", + "dataType": "string", + "processingStage": "pre-tokenizer", + "required": true, + "constraints": { + "maxLength": 32768 + } + }, + { + "name": "image", + "description": "An optional scanned document page.", + "modality": "image", + "dataType": "uint8", + "mimeType": "image/png", + "quantization": { + "scheme": "affine", + "granularity": "per-tensor", + "bits": 8 + }, + "shape": [ + null, + 3, + 224, + 224 + ] + } + ], + "outputs": [ + { + "name": "summary", + "modality": "text", + "dataType": "string", + "processingStage": "post-processing" + } + ], + "training": { + "formula": "formula-training-1", + "datasets": [ + "dataset-corpus-1", + "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#openwebtext-subset" + ] + }, + "evaluation": { + "metrics": [ + { + "type": "accuracy", + "benchmark": "mmlu-pro", + "measure": { + "value": 58.2, + "unit": "%" + }, + "confidenceInterval": { + "lowerBound": 57.5, + "upperBound": 58.9 + } + }, + { + "type": "rouge-l", + "slice": "language:es", + "measure": { + "value": 41.3, + "unit": "%" + }, + "evaluationDatasets": [ + "dataset-corpus-1" + ] + }, + { + "type": "latency", + "measure": { + "value": 127, + "unit": "ms" + }, + "properties": [ + { + "name": "percentile", + "value": "p95" + } + ] + } + ], + "graphics": { + "description": "Evaluation graphics.", + "collection": [ + { + "name": "Confusion Matrix", + "image": { + "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", + "mediaType": "image/png", + "encoding": "base64" + } + } + ] + } + }, + "limitations": [ + "Summarization accuracy degrades on notes longer than the maximum context length.", + "The model is not intended for autonomous clinical decision making." + ], + "environmental": { + "energyConsumptions": [ + { + "activity": "training", + "formula": "formula-training-1", + "energyProviders": [ + { + "bom-ref": "energy-provider-1", + "description": "Primary datacenter energy provider.", + "provider": { + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Example Energy Cooperative" + } + }, + "energySource": "wind", + "energyProvided": { + "value": 3200000, + "unit": "kWh" + } + } + ], + "activityEnergyCost": { + "value": 3200, + "unit": "MWh" + }, + "co2CostEquivalent": { + "value": 850, + "unit": "tCO2eq" + }, + "co2CostOffset": { + "value": 850, + "unit": "tCO2eq" + } + }, + { + "activity": { + "name": "retrieval-indexing", + "description": "Nightly re-indexing of the retrieval corpus." + }, + "activityEnergyCost": { + "value": 1200, + "unit": "kWh" + } + } + ] + }, + "properties": [ + { + "name": "cdx:ai-ml:model:contextWindow", + "value": "32768" + } + ] + } + }, + { + "type": "data", + "bom-ref": "dataset-corpus-1", + "name": "deidentified-clinical-notes", + "version": "2026-04", + "data": [ + { + "type": "dataset", + "bom-ref": "dataset-corpus-1-contents", + "name": "De-identified clinical notes", + "description": "Corpus of de-identified clinical notes used for fine-tuning.", + "classification": "restricted" + } + ] + } + ] +} diff --git a/tools/src/test/resources/2.0/invalid-ai-ml-legacy-modelcard-2.0.json b/tools/src/test/resources/2.0/invalid-ai-ml-legacy-modelcard-2.0.json new file mode 100644 index 000000000..e187b6778 --- /dev/null +++ b/tools/src/test/resources/2.0/invalid-ai-ml-legacy-modelcard-2.0.json @@ -0,0 +1,49 @@ +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "serialNumber": "urn:uuid:8b41cf82-52e6-46d5-9f45-e6c2ab4bf002", + "version": 1, + "metadata": { + "timestamp": "2026-08-13T12:00:00Z" + }, + "components": [ + { + "type": "machine-learning-model", + "bom-ref": "model-1", + "name": "acme-summarizer", + "version": "2.1.0", + "description": "A transformer language model fine-tuned for clinical note summarization.", + "parties": [ + { + "bom-ref": "party-acme", + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Acme Health AI" + } + }, + { + "bom-ref": "party-clinicians", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "description": "Clinicians who review generated summaries before entering them into patient records." + } + } + ], + "modelCard": { + "bom-ref": "modelcard-1", + "modelParameters": { + "task": "summarization" + } + } + } + ] +} diff --git a/tools/src/test/resources/2.0/invalid-ai-ml-task-casing-2.0.json b/tools/src/test/resources/2.0/invalid-ai-ml-task-casing-2.0.json new file mode 100644 index 000000000..76392cb0f --- /dev/null +++ b/tools/src/test/resources/2.0/invalid-ai-ml-task-casing-2.0.json @@ -0,0 +1,251 @@ +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "serialNumber": "urn:uuid:8b41cf82-52e6-46d5-9f45-e6c2ab4bf004", + "version": 1, + "metadata": { + "timestamp": "2026-08-13T12:00:00Z" + }, + "components": [ + { + "type": "machine-learning-model", + "bom-ref": "model-1", + "name": "acme-summarizer", + "version": "2.1.0", + "description": "A transformer language model fine-tuned for clinical note summarization.", + "parties": [ + { + "bom-ref": "party-acme", + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Acme Health AI" + } + }, + { + "bom-ref": "party-clinicians", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "description": "Clinicians who review generated summaries before entering them into patient records." + } + } + ], + "modelProperties": { + "learningTypes": [ + "self-supervised", + "reinforcement-learning" + ], + "tasks": [ + "Summarization" + ], + "architecture": { + "name": "acme-lm-7b", + "description": "Decoder-only transformer with grouped-query attention and rotary positional embeddings.", + "family": "transformer", + "features": [ + "decoder-only", + "grouped-query-attention", + "rotary-position-embedding", + { + "name": "clinical-adapter", + "description": "Domain adapter layers trained on de-identified clinical text." + } + ], + "topology": "dense" + }, + "parameterCount": 7000000000, + "quantization": { + "method": "k-quant", + "bits": 4, + "scheme": "affine", + "granularity": "per-group", + "groupSize": 128, + "axis": 0 + }, + "inputs": [ + { + "name": "prompt", + "description": "The clinical note to summarize.", + "modality": "text", + "dataType": "string", + "processingStage": "pre-tokenizer", + "required": true, + "constraints": { + "maxLength": 32768 + } + }, + { + "name": "image", + "description": "An optional scanned document page.", + "modality": "image", + "dataType": "uint8", + "mimeType": "image/png", + "quantization": { + "scheme": "affine", + "granularity": "per-tensor", + "bits": 8 + }, + "shape": [ + null, + 3, + 224, + 224 + ] + } + ], + "outputs": [ + { + "name": "summary", + "modality": "text", + "dataType": "string", + "processingStage": "post-processing" + } + ], + "training": { + "formula": "formula-training-1", + "datasets": [ + "dataset-corpus-1", + "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#openwebtext-subset" + ] + }, + "evaluation": { + "metrics": [ + { + "type": "accuracy", + "benchmark": "mmlu-pro", + "measure": { + "value": 58.2, + "unit": "%" + }, + "confidenceInterval": { + "lowerBound": 57.5, + "upperBound": 58.9 + } + }, + { + "type": "rouge-l", + "slice": "language:es", + "measure": { + "value": 41.3, + "unit": "%" + }, + "evaluationDatasets": [ + "dataset-corpus-1" + ] + }, + { + "type": "latency", + "measure": { + "value": 127, + "unit": "ms" + }, + "properties": [ + { + "name": "percentile", + "value": "p95" + } + ] + } + ], + "graphics": { + "description": "Evaluation graphics.", + "collection": [ + { + "name": "Confusion Matrix", + "image": { + "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", + "mediaType": "image/png", + "encoding": "base64" + } + } + ] + } + }, + "limitations": [ + "Summarization accuracy degrades on notes longer than the maximum context length.", + "The model is not intended for autonomous clinical decision making." + ], + "environmental": { + "energyConsumptions": [ + { + "activity": "training", + "formula": "formula-training-1", + "energyProviders": [ + { + "bom-ref": "energy-provider-1", + "description": "Primary datacenter energy provider.", + "provider": { + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Example Energy Cooperative" + } + }, + "energySource": "wind", + "energyProvided": { + "value": 3200000, + "unit": "kWh" + } + } + ], + "activityEnergyCost": { + "value": 3200000, + "unit": "kWh" + }, + "co2CostEquivalent": { + "value": 850, + "unit": "tCO2eq" + }, + "co2CostOffset": { + "value": 850, + "unit": "tCO2eq" + } + }, + { + "activity": { + "name": "retrieval-indexing", + "description": "Nightly re-indexing of the retrieval corpus." + }, + "activityEnergyCost": { + "value": 1200, + "unit": "kWh" + } + } + ] + }, + "properties": [ + { + "name": "cdx:ai-ml:model:contextWindow", + "value": "32768" + } + ] + } + }, + { + "type": "data", + "bom-ref": "dataset-corpus-1", + "name": "deidentified-clinical-notes", + "version": "2026-04", + "data": [ + { + "type": "dataset", + "bom-ref": "dataset-corpus-1-contents", + "name": "De-identified clinical notes", + "description": "Corpus of de-identified clinical notes used for fine-tuning.", + "classification": "restricted" + } + ] + } + ] +} diff --git a/tools/src/test/resources/2.0/valid-ai-ml-model-2.0.json b/tools/src/test/resources/2.0/valid-ai-ml-model-2.0.json new file mode 100644 index 000000000..b2cc65efe --- /dev/null +++ b/tools/src/test/resources/2.0/valid-ai-ml-model-2.0.json @@ -0,0 +1,410 @@ +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "serialNumber": "urn:uuid:8b41cf82-52e6-46d5-9f45-e6c2ab4bf001", + "version": 1, + "metadata": { + "timestamp": "2026-08-13T12:00:00Z" + }, + "components": [ + { + "type": "machine-learning-model", + "bom-ref": "model-1", + "name": "acme-summarizer", + "version": "2.1.0", + "description": "A transformer language model fine-tuned for clinical note summarization.", + "tags": [ + "nlp", + "summarization", + "clinical" + ], + "licenses": [ + { + "license": { + "id": "Apache-2.0" + } + } + ], + "hashes": [ + { + "alg": "SHA-256", + "content": "d2f61af223cf5d5db54a0e2ac4bbf29b06b5cf16983ae1e0e0e9c2536b1a5b19" + } + ], + "identifiers": [ + { + "party": "party-acme", + "identities": [ + { + "scheme": "purl", + "value": "pkg:generic/acme/acme-summarizer@2.1.0" + }, + { + "scheme": "model-number", + "value": "ACME-SUM-7B-INT4" + } + ] + } + ], + "parties": [ + { + "bom-ref": "party-acme", + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Acme Health AI" + } + }, + { + "bom-ref": "party-clinicians", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "description": "Clinicians who review generated summaries before entering them into patient records." + } + } + ], + "modelProperties": { + "learningTypes": [ + "self-supervised", + "reinforcement-learning" + ], + "tasks": [ + "summarization", + "text-generation" + ], + "architecture": { + "name": "acme-lm-7b", + "description": "Decoder-only transformer with grouped-query attention and rotary positional embeddings.", + "family": "transformer", + "features": [ + "decoder-only", + "grouped-query-attention", + "rotary-position-embedding", + { + "name": "clinical-adapter", + "description": "Domain adapter layers trained on de-identified clinical text." + } + ], + "topology": "dense" + }, + "parameterCount": 7000000000, + "quantization": { + "method": "k-quant", + "bits": 4, + "scheme": "affine", + "granularity": "per-group", + "groupSize": 128, + "axis": 0 + }, + "inputs": [ + { + "name": "prompt", + "description": "The clinical note to summarize.", + "modality": "text", + "dataType": "string", + "processingStage": "pre-tokenizer", + "required": true, + "constraints": { + "maxLength": 32768 + } + }, + { + "name": "image", + "description": "An optional scanned document page.", + "modality": "image", + "dataType": "uint8", + "mimeType": "image/png", + "quantization": { + "scheme": "affine", + "granularity": "per-tensor", + "bits": 8 + }, + "shape": [ + null, + 3, + 224, + 224 + ] + } + ], + "outputs": [ + { + "name": "summary", + "modality": "text", + "dataType": "string", + "processingStage": "post-processing" + } + ], + "training": { + "formula": "formula-training-1", + "datasets": [ + "dataset-corpus-1", + "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#openwebtext-subset" + ] + }, + "evaluation": { + "metrics": [ + { + "type": "accuracy", + "benchmark": "mmlu-pro", + "measure": { + "value": 58.2, + "unit": "%" + }, + "confidenceInterval": { + "lowerBound": 57.5, + "upperBound": 58.9 + } + }, + { + "type": "rouge-l", + "slice": "language:es", + "measure": { + "value": 41.3, + "unit": "%" + }, + "evaluationDatasets": [ + "dataset-corpus-1" + ] + }, + { + "type": "latency", + "measure": { + "value": 127, + "unit": "ms" + }, + "properties": [ + { + "name": "percentile", + "value": "p95" + } + ] + } + ], + "graphics": { + "description": "Evaluation graphics.", + "collection": [ + { + "name": "Confusion Matrix", + "image": { + "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", + "mediaType": "image/png", + "encoding": "base64" + } + } + ] + } + }, + "limitations": [ + "Summarization accuracy degrades on notes longer than the maximum context length.", + "The model is not intended for autonomous clinical decision making." + ], + "environmental": { + "energyConsumptions": [ + { + "activity": "training", + "formula": "formula-training-1", + "energyProviders": [ + { + "bom-ref": "energy-provider-1", + "description": "Primary datacenter energy provider.", + "provider": { + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Example Energy Cooperative" + } + }, + "energySource": "wind", + "energyProvided": { + "value": 3200000, + "unit": "kWh" + } + } + ], + "activityEnergyCost": { + "value": 3200000, + "unit": "kWh" + }, + "co2CostEquivalent": { + "value": 850, + "unit": "tCO2eq" + }, + "co2CostOffset": { + "value": 850, + "unit": "tCO2eq" + } + }, + { + "activity": { + "name": "retrieval-indexing", + "description": "Nightly re-indexing of the retrieval corpus." + }, + "activityEnergyCost": { + "value": 1200, + "unit": "kWh" + } + } + ] + }, + "properties": [ + { + "name": "cdx:ai-ml:model:contextWindow", + "value": "32768" + } + ] + } + }, + { + "type": "data", + "bom-ref": "dataset-corpus-1", + "name": "deidentified-clinical-notes", + "version": "2026-04", + "data": [ + { + "type": "dataset", + "bom-ref": "dataset-corpus-1-contents", + "name": "De-identified clinical notes", + "description": "Corpus of de-identified clinical notes used for fine-tuning.", + "classification": "restricted" + } + ] + } + ], + "formulation": [ + { + "bom-ref": "formula-training-1", + "workflows": [ + { + "bom-ref": "workflow-pretrain-1", + "uid": "workflow-pretrain-1", + "name": "Pre-training and fine-tuning", + "taskTypes": [ + "build" + ] + } + ] + } + ], + "perspectives": [ + { + "bom-ref": "perspective-model-card", + "name": "Model Card", + "description": "The model card view of this BOM. Mappings project the component identity, licensing, and party information together with the technical model properties, training, evaluation, limitations, and environmental measurements, using section names familiar to AI transparency audiences.", + "domains": [ + "machine-learning", + "transparency" + ], + "mappings": [ + { + "expression": "$.components[?(@.type=='machine-learning-model')]['name','version','description','tags']", + "nativeName": "Model Details", + "nativeDescription": "The identity of the model: its name, version, and a description of what it is and does.", + "relevance": "required", + "weight": 1.0 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].parties[?(@.roles[?(@.role=='supplier')])]", + "nativeName": "Developed By", + "nativeDescription": "The parties that develop and supply the model.", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].parties[?(@.roles[?(@.role=='end-user')])]", + "nativeName": "Intended Users", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].licenses", + "nativeName": "License", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].identifiers", + "nativeName": "Model Identifiers", + "nativeDescription": "Asserted identities of the model, such as package URLs and model numbers.", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].hashes", + "nativeName": "Artifact Integrity", + "nativeDescription": "Cryptographic hashes of the distributed model artifact.", + "relevance": "optional" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.tasks", + "nativeName": "Supported Tasks", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.learningTypes", + "nativeName": "Learning Paradigms", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.architecture", + "nativeName": "Architecture", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.parameterCount", + "nativeName": "Parameter Count", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.quantization", + "nativeName": "Quantization", + "relevance": "optional" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties['inputs','outputs']", + "nativeName": "Input and Output Specification", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.training", + "nativeName": "Training Data", + "relevance": "recommended", + "weight": 0.9 + }, + { + "expression": "$.formulation[?(@['bom-ref']=='formula-training-1')]", + "nativeName": "Training Procedure", + "relevance": "optional" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.evaluation", + "nativeName": "Evaluation Results", + "relevance": "recommended", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.limitations", + "nativeName": "Known Limitations", + "nativeDescription": "Documented constraints on accuracy, reasoning, scalability, and appropriate use.", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.environmental", + "nativeName": "Environmental Impact", + "relevance": "recommended" + } + ] + } + ] +} diff --git a/tools/src/test/resources/2.0/valid-ai-ml-risk-integration-2.0.json b/tools/src/test/resources/2.0/valid-ai-ml-risk-integration-2.0.json new file mode 100644 index 000000000..07e400fa0 --- /dev/null +++ b/tools/src/test/resources/2.0/valid-ai-ml-risk-integration-2.0.json @@ -0,0 +1,524 @@ +{ + "$schema": "https://cyclonedx.org/schema/2.0/cyclonedx-2.0.schema.json", + "specFormat": "CycloneDX", + "specVersion": "2.0", + "serialNumber": "urn:uuid:8b41cf82-52e6-46d5-9f45-e6c2ab4bf005", + "version": 1, + "metadata": { + "timestamp": "2026-08-13T12:00:00Z" + }, + "components": [ + { + "type": "machine-learning-model", + "bom-ref": "model-1", + "name": "acme-summarizer", + "version": "2.1.0", + "description": "A transformer language model fine-tuned for clinical note summarization.", + "tags": [ + "nlp", + "summarization", + "clinical" + ], + "licenses": [ + { + "license": { + "id": "Apache-2.0" + } + } + ], + "hashes": [ + { + "alg": "SHA-256", + "content": "d2f61af223cf5d5db54a0e2ac4bbf29b06b5cf16983ae1e0e0e9c2536b1a5b19" + } + ], + "identifiers": [ + { + "party": "party-acme", + "identities": [ + { + "scheme": "purl", + "value": "pkg:generic/acme/acme-summarizer@2.1.0" + }, + { + "scheme": "model-number", + "value": "ACME-SUM-7B-INT4" + } + ] + } + ], + "parties": [ + { + "bom-ref": "party-acme", + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Acme Health AI" + } + }, + { + "bom-ref": "party-clinicians", + "roles": [ + { + "role": "end-user" + } + ], + "persona": { + "description": "Clinicians who review generated summaries before entering them into patient records." + } + }, + { + "bom-ref": "party-elderly-users", + "roles": [ + { + "role": "data-subject" + } + ], + "persona": { + "description": "Patients aged 65 and over whose notes exhibit distinct terminology and comorbidity patterns." + } + } + ], + "modelProperties": { + "learningTypes": [ + "self-supervised", + "reinforcement-learning" + ], + "tasks": [ + "summarization", + "text-generation" + ], + "architecture": { + "name": "acme-lm-7b", + "description": "Decoder-only transformer with grouped-query attention and rotary positional embeddings.", + "family": "transformer", + "features": [ + "decoder-only", + "grouped-query-attention", + "rotary-position-embedding", + { + "name": "clinical-adapter", + "description": "Domain adapter layers trained on de-identified clinical text." + } + ], + "topology": "dense" + }, + "parameterCount": 7000000000, + "quantization": { + "method": "k-quant", + "bits": 4, + "scheme": "affine", + "granularity": "per-group", + "groupSize": 128, + "axis": 0 + }, + "inputs": [ + { + "name": "prompt", + "description": "The clinical note to summarize.", + "modality": "text", + "dataType": "string", + "processingStage": "pre-tokenizer", + "required": true, + "constraints": { + "maxLength": 32768 + } + }, + { + "name": "image", + "description": "An optional scanned document page.", + "modality": "image", + "dataType": "uint8", + "mimeType": "image/png", + "quantization": { + "scheme": "affine", + "granularity": "per-tensor", + "bits": 8 + }, + "shape": [ + null, + 3, + 224, + 224 + ] + } + ], + "outputs": [ + { + "name": "summary", + "modality": "text", + "dataType": "string", + "processingStage": "post-processing" + } + ], + "training": { + "formula": "formula-training-1", + "datasets": [ + "dataset-corpus-1", + "urn:cdx:f08a6ccd-4dce-4759-bd84-c626675d60a7/1#openwebtext-subset" + ] + }, + "evaluation": { + "metrics": [ + { + "type": "accuracy", + "benchmark": "mmlu-pro", + "measure": { + "value": 58.2, + "unit": "%" + }, + "confidenceInterval": { + "lowerBound": 57.5, + "upperBound": 58.9 + } + }, + { + "type": "rouge-l", + "slice": "language:es", + "measure": { + "value": 41.3, + "unit": "%" + }, + "evaluationDatasets": [ + "dataset-corpus-1" + ] + }, + { + "type": "latency", + "measure": { + "value": 127, + "unit": "ms" + }, + "properties": [ + { + "name": "percentile", + "value": "p95" + } + ] + } + ], + "graphics": { + "description": "Evaluation graphics.", + "collection": [ + { + "name": "Confusion Matrix", + "image": { + "content": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==", + "mediaType": "image/png", + "encoding": "base64" + } + } + ] + } + }, + "limitations": [ + "Summarization accuracy degrades on notes longer than the maximum context length.", + "The model is not intended for autonomous clinical decision making." + ], + "environmental": { + "energyConsumptions": [ + { + "activity": "training", + "formula": "formula-training-1", + "energyProviders": [ + { + "bom-ref": "energy-provider-1", + "description": "Primary datacenter energy provider.", + "provider": { + "roles": [ + { + "role": "supplier" + } + ], + "organization": { + "name": "Example Energy Cooperative" + } + }, + "energySource": "wind", + "energyProvided": { + "value": 3200000, + "unit": "kWh" + } + } + ], + "activityEnergyCost": { + "value": 3200000, + "unit": "kWh" + }, + "co2CostEquivalent": { + "value": 850, + "unit": "tCO2eq" + }, + "co2CostOffset": { + "value": 850, + "unit": "tCO2eq" + } + }, + { + "activity": { + "name": "retrieval-indexing", + "description": "Nightly re-indexing of the retrieval corpus." + }, + "activityEnergyCost": { + "value": 1200, + "unit": "kWh" + } + } + ] + }, + "properties": [ + { + "name": "cdx:ai-ml:model:contextWindow", + "value": "32768" + } + ], + "useCases": [ + "usecase-clinical-summarization" + ] + } + }, + { + "type": "data", + "bom-ref": "dataset-corpus-1", + "name": "deidentified-clinical-notes", + "version": "2026-04", + "data": [ + { + "type": "dataset", + "bom-ref": "dataset-corpus-1-contents", + "name": "De-identified clinical notes", + "description": "Corpus of de-identified clinical notes used for fine-tuning.", + "classification": "restricted" + } + ] + } + ], + "definitions": { + "useCases": [ + { + "bom-ref": "usecase-clinical-summarization", + "name": "Clinical note summarization", + "description": "Summarize clinical notes for clinician review prior to entry into the patient record.", + "actors": [ + "party-clinicians" + ] + } + ] + }, + "risks": { + "risks": [ + { + "bom-ref": "risk-demographic-disparity", + "name": "Demographic performance disparity", + "statement": "Summarization accuracy is lower for notes describing patients aged 65 and over, which may lead to incomplete summaries for that group.", + "domains": [ + { + "type": "ethical" + }, + { + "type": "safety" + } + ], + "affects": [ + "model-1", + "party-elderly-users" + ], + "inherentRisk": { + "likelihood": { + "level": "high" + }, + "impact": { + "level": "major", + "polarity": "harm", + "categories": [ + "bias", + "fairness", + "health" + ] + }, + "rationale": "Slice level evaluation shows a nine point accuracy gap for the affected group." + }, + "residualRisk": { + "likelihood": { + "level": "low" + }, + "impact": { + "level": "moderate", + "polarity": "harm", + "categories": [ + "bias", + "fairness" + ] + } + }, + "responses": [ + { + "bom-ref": "response-reweighting", + "strategy": "reduce", + "description": "Oversample under-represented age groups during fine-tuning and gate releases on slice level evaluation." + } + ] + } + ], + "assessments": [ + { + "bom-ref": "assessment-ai-impact-2026q3", + "type": [ + "ai-impact", + "model-risk" + ], + "cadence": "periodic", + "timestamp": "2026-08-01T00:00:00Z", + "assessors": [ + { + "roles": [ + { + "role": "verifier" + } + ], + "organization": { + "name": "Acme Responsible AI Board" + } + } + ], + "risks": [ + "risk-demographic-disparity" + ], + "summary": "Quarterly AI impact assessment of the clinical summarization model." + } + ] + }, + "perspectives": [ + { + "bom-ref": "perspective-model-card", + "name": "Model Card", + "description": "The model card view of this BOM. Mappings project the component identity, licensing, and party information together with the technical model properties, training, evaluation, limitations, environmental measurements, intended use cases, and the associated risks and impact assessments, using section names familiar to AI transparency audiences.", + "domains": [ + "machine-learning", + "transparency", + "ethics" + ], + "mappings": [ + { + "expression": "$.components[?(@.type=='machine-learning-model')]['name','version','description','tags']", + "nativeName": "Model Details", + "nativeDescription": "The identity of the model: its name, version, and a description of what it is and does.", + "relevance": "required", + "weight": 1.0 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].parties[?(@.roles[?(@.role=='supplier')])]", + "nativeName": "Developed By", + "nativeDescription": "The parties that develop and supply the model.", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].parties[?(@.roles[?(@.role=='end-user')])]", + "nativeName": "Intended Users", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].licenses", + "nativeName": "License", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].identifiers", + "nativeName": "Model Identifiers", + "nativeDescription": "Asserted identities of the model, such as package URLs and model numbers.", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].hashes", + "nativeName": "Artifact Integrity", + "nativeDescription": "Cryptographic hashes of the distributed model artifact.", + "relevance": "optional" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.tasks", + "nativeName": "Supported Tasks", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.learningTypes", + "nativeName": "Learning Paradigms", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.architecture", + "nativeName": "Architecture", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.parameterCount", + "nativeName": "Parameter Count", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.quantization", + "nativeName": "Quantization", + "relevance": "optional" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties['inputs','outputs']", + "nativeName": "Input and Output Specification", + "relevance": "recommended" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.training", + "nativeName": "Training Data", + "relevance": "recommended", + "weight": 0.9 + }, + { + "expression": "$.formulation[?(@['bom-ref']=='formula-training-1')]", + "nativeName": "Training Procedure", + "relevance": "optional" + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.evaluation", + "nativeName": "Evaluation Results", + "relevance": "recommended", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.limitations", + "nativeName": "Known Limitations", + "nativeDescription": "Documented constraints on accuracy, reasoning, scalability, and appropriate use.", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.components[?(@.type=='machine-learning-model')].modelProperties.environmental", + "nativeName": "Environmental Impact", + "relevance": "recommended" + }, + { + "expression": "$.definitions.useCases", + "nativeName": "Intended Use", + "nativeDescription": "The documented use cases the model is intended to serve.", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.risks.risks[?(@.domains[?(@.type=='ethical')])]", + "nativeName": "Ethical Considerations", + "nativeDescription": "Risks documenting potential harms, affected groups, and mitigations.", + "relevance": "required", + "weight": 0.9 + }, + { + "expression": "$.risks.assessments", + "nativeName": "Impact Assessments", + "relevance": "recommended" + } + ] + } + ] +}