feat: Add support for Component modelCard field

[wiebe-vandendriessche]

feat: Add support for Component modelCard field

Summary

• Adds modelCard support to components for CycloneDX 1.5+, including environmental considerations (1.6+).
• Temporarily gates modelParameters.datasets as unsupported pending [FEAT] Add support for Component data field #913.

Linked Issues

Closes: #912
Part of [TRACKING] Complete support for CycloneDX v1.5: #578
Follow-up: #913

Changes

• Model types: ModelCard, ModelParameters, QuantitativeAnalysis, PerformanceMetric, GraphicsCollection, ConfidenceInterval.
• Considerations: Considerations, EthicalConsideration, FairnessAssessment.
• Environmental (1.6+): EnvironmentalConsiderations, EnergyConsumption, EnergyProvider, EnergyMeasure, Co2Measure, enums EnergyActivity, EnergySource.
• Component integration: Component.model_card (1.5+).
• Datasets gating:
  • Raises NotImplementedError if modelParameters.datasets is populated.
  • Omitted from serialization until [FEAT] Add support for Component data field #913 implements shared component.data/componentData.

Schema Compatibility

• 1.5: modelCard with modelParameters, quantitativeAnalysis, considerations.
• 1.6–1.7: adds environmentalConsiderations and energy/CO2/provider types.

Tests

• New test_model_model_card.py:
  • Basic 1.5 JSON/XML serialization.
  • 1.6 environmental considerations JSON/XML.
  • Full 1.7 “rich” card including providers with bom-ref.
  • Ordering/equality for approaches, IO params, providers, consumptions.
• All tests pass locally.

Follow-ups

• Implement modelParameters.datasets once [FEAT] Add support for Component data field #913 lands:
  • Shared component.data model + union (inline componentData or {ref}).

Breaking Changes

• None in existing APIs. A NotImplementedError is raised only if modelParameters.datasets is supplied, intentionally preventing invalid output.

Validate modelCard locally

poetry run pytest -q tests/test_model_model_card.py

---

• fixes [FEAT] Add support for Component modelCard field #912

[jkowalleck]

Please also add a sufficient data model to https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/tests/_data/models.py

[Copilot]

Pull Request Overview

This PR adds comprehensive support for the modelCard field on CycloneDX components, enabling machine learning model documentation including parameters, performance metrics, ethical considerations, and environmental impact tracking.

Key changes:

• Introduces complete ModelCard type hierarchy including parameters, quantitative analysis, and considerations
• Adds environmental impact tracking with energy consumption and CO2 measurements (v1.6+)
• Temporarily gates modelParameters.datasets field with validation that raises NotImplementedError until shared component data support (#913) is implemented

Reviewed Changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 18 comments.

File	Description
cyclonedx/model/model_card.py	Defines comprehensive ModelCard type system including 20+ classes for ML model documentation, energy tracking, and ethical considerations with proper schema versioning (1.5-1.7)
cyclonedx/model/component.py	Integrates model_card property into Component class with proper serialization annotations and comparable tuple support
tests/test_model_model_card.py	Provides extensive test coverage including schema validation for v1.5-1.7, sorting behavior, equality checks, and version-specific feature gating

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wiebe-vandendriessche]

Please also add a sufficient data model to https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/tests/_data/models.py

Is there documentation on how this works?

[jkowalleck]

Please also add a sufficient data model to https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/tests/_data/models.py

Is there documentation on how this works?

not yet. We would be happy to see a dedicated pull-request that improves the documentation.

in your case, you would create a BOM with just one bare component and a complete modelCard with every property filled.

the system works like this:

• the models' functions MUST return instances of class Bom
• these functions should have names and docs that help understand their purpose.
• every function that starts with get_bom_ is picked up as a test case by all_get_bom_funct_valid -

  cyclonedx-python-lib/tests/_data/models.py

  Lines 1567 to 1570 in aff9636

  	all_get_bom_funct_valid = tuple(
  	(n, f) for n, f in getmembers(sys.modules[__name__], isfunction)
  	if n.startswith('get_bom_') and not n.endswith('_invalid')
  	)

• tests with incomplete dependency trees go here: all_get_bom_funct_with_incomplete_deps
• test cases(models) are picked up by the various runners - see https://github.com/search?q=repo%3ACycloneDX%2Fcyclonedx-python-lib+%22all_get_bom_funct_%22&type=code
• the test modesl are compared to previously created snapshots.
  Whenever models are modified, the snapshots need updates. these updates must be enforced as described here: https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/tests/_data/snapshots/README.md

[wiebe-vandendriessche]

Please also add a sufficient data model to https://github.com/CycloneDX/cyclonedx-python-lib/blob/main/tests/_data/models.py

Is there documentation on how this works?

not yet. We would be happy to see a dedicated pull-request that improves the documentation.
...

Ok, i'll take a look for this!

In the meantime i have encountered an issue regarding ModelCard.properties.

It seems like ModelCard.properties validates in JSON but is rejected by XML.

I tried to add top-level properties to ModelCard:

properties=[
    Property(name='release', value='2024-01-01'),
    Property(name='stability', value='experimental'),
]

JSON (1.7) validates successfully.
XML (1.7) fails schema validation with “Element … properties is not expected” under .

Can you confirm the XML spec indeed does not have ModelCard.properties?
And if so, is the JSON/XML asymmetry for modelCard.properties intentional in 1.5–1.7?

How should we handle this in the code? Because right now it's not possible to add custom properties in a ModelCard.

(however other classes inside the modelCard also have a "properties" field e.g. EnvironmentalConsiderations, and this does fully work)

[jkowalleck]

Can you confirm the XML spec indeed does not have ModelCard.properties?

can confirm.

JSON: https://cyclonedx.org/docs/1.7/json/#components_items_modelCard_properties
XML: https://cyclonedx.org/docs/1.7/xml/#type_modelCardType

And if so, is the JSON/XML asymmetry for modelCard.properties intentional in 1.5–1.7?

nope. it a bug. thanks for reporting - caused CycloneDX/specification#726

[wiebe-vandendriessche]

Can you confirm the XML spec indeed does not have ModelCard.properties?

can confirm.

JSON: https://cyclonedx.org/docs/1.7/json/#components_items_modelCard_properties XML: https://cyclonedx.org/docs/1.7/xml/#type_modelCardType

And if so, is the JSON/XML asymmetry for modelCard.properties intentional in 1.5–1.7?

nope. it a bug. thanks for reporting - caused CycloneDX/specification#726

Good to know! What should I do in the meantime? Should we merge this pull request with a temporary solution that just disables ModelCard.properties (both json and xml) untill that issue in the spec is resolved (because I guess this will take long)?

[jkowalleck]

How should we handle this in the code? Because right now it's not possible to add custom properties in a ModelCard.

(however other classes inside the modelCard also have a "properties" field e.g. EnvironmentalConsiderations, and this does fully work)

looking into this. give me some time.
I will find a way to omit the property for XML only.

[wiebe-vandendriessche]

looking into this. give me some time. I will find a way to omit the property for XML only.

Thanks, sounds good.