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 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