Introduce pre-defined perspectives - #1067
Conversation
…e form Adds an optional 'predefined' field to the perspective model, identifying a well-known perspective published in the CycloneDX perspectives catalog and incorporating the published definition by reference, so tooling can recognize the perspective without matching on free-text names. A perspective either declares a pre-defined identity or defines its own mappings inline; mixing the two is not permitted, keeping the published definition the single source of truth for what a pre-defined perspective contains. Initial enum values: model-card, pqc-readiness. Valid/invalid fixtures added covering the reference form, the inline form, enum rejection, and the forbidden mixed form. Bundled schemas are left to the post-merge bundle workflow. Signed-off-by: Pavel Shukhman <pavel@reliza.io>
Second entry in the perspectives catalog, following the delivery shape of the PQC readiness perspective: a complete, minimal, valid 2.0 document containing only the perspective. This is the definition incorporated by reference when a document declares the pre-defined perspective 'model-card'. The mappings express the industry-standard model card structure over the CycloneDX 2.0 decomposition of the former first-class modelCard entity: intrinsic technical characteristics in modelProperties (scoped to components of type machine-learning-model, the only type that may carry them), training datasets as components of type data, intended use cases as use case definitions, and ethical and fairness considerations as risk model entries. Assumes the AI/ML model properties proposed in CycloneDX#990. Signed-off-by: Pavel Shukhman <pavel@reliza.io>
The reference form previously excluded only inline mappings, leaving name, description, domains, externalReferences, and properties legal alongside a pre-defined identity. That allowed documents to locally shadow published fields (e.g. a different name or domains) with no defined precedence. The reference form now forbids all inline content except bom-ref, so the published definition is unambiguously the single source of truth. Invalid fixture added covering annotation of a pre-defined perspective. Signed-off-by: Pavel Shukhman <pavel@reliza.io>
…sion The expression selects all components of type data; JSONPath cannot follow references, so the selection is necessarily broader than the datasets referenced from the model's training information. Soften the description so prose and expression agree. Signed-off-by: Pavel Shukhman <pavel@reliza.io>
| ], | ||
| "meta:enum": { | ||
| "model-card": "A transparency view for machine learning models following the industry-standard model card structure, covering model details, intended use, training data and procedure, quantitative analysis, technical limitations, and ethical and environmental considerations.", | ||
| "pqc-readiness": "A view for assessing readiness for the post-quantum cryptography migration, covering cryptographic inventory, quantum resistance of the cryptography in use, and cryptographic agility." |
There was a problem hiding this comment.
Nice. Reserving "pqc-readiness", in advance, is good foresight.
| }, | ||
| "perspectives": [ | ||
| { | ||
| "bom-ref": "perspective-model-card", |
There was a problem hiding this comment.
I would suggest we utlilize the reserved "cdx:" namespace and establish a "cdx:perspectives" namespace path (or singular "perspective"). We could build upon and declare as part of the reserved cyclonedx-property-taxonomy.
| { | ||
| "bom-ref": "perspective-model-card", | ||
| "name": "Model Card", | ||
| "description": "Defines the data elements of a machine learning model card, following the industry-standard model card structure: model details, intended use, training data and procedure, quantitative analysis, technical limitations, and ethical, fairness, and environmental considerations. The mappings project that structure onto the CycloneDX 2.0 decomposition of the former first-class modelCard entity: intrinsic technical characteristics live in modelProperties, which may only appear on components of type machine-learning-model; training datasets are components of type data; intended use cases are use case definitions referenced from the model; and ethical and fairness considerations are entries in the document's risk model. This perspective assumes the AI/ML model properties proposed in CycloneDX/specification#990.", |
There was a problem hiding this comment.
Excellent. It captured all the key items from the guide.
| "mappings": [ | ||
| { | ||
| "expression": "$.components[?(@.type=='machine-learning-model')]['name','version','description']", | ||
| "nativeName": "Model Details", |
There was a problem hiding this comment.
Not quite sure what "native" means.
| ], | ||
| "mappings": [ | ||
| { | ||
| "expression": "$.components[?(@.type=='machine-learning-model')]['name','version','description']", |
There was a problem hiding this comment.
Should there be a version? Should we include any identifiers (like pURL for huggingface hub models)?
There was a problem hiding this comment.
or should all 2.0 identifiers have a mapping? 2.0 still confuses me as we seem to have diluted identifiers we endorse, like pURL, which are lock-step with Ecma/ISO goals, but treat it the same as a made up identity (domain) as well as legacy domains we attempted to solve with pURL.
| "rationale": "Training data provenance is central to assessing bias, capability boundaries, and data protection obligations." | ||
| }, | ||
| { | ||
| "expression": "$.components[?(@.type=='data')]", |
There was a problem hiding this comment.
Datasets are the key focus of EU AI Act and templates. This is one of the main concerns I have with perspectives as we need to likely capture all the things we need for the top-level component (e.g., identity, licenses, version, etc.) as well as information about its data provenance (e.g., crawled, synthetic, etc.) some of which are "properties". Plus we need to describe the "usage" of the data relative to training steps/stages (and perhaps declare data subsets and rationale).
| "rationale": "Limitations are the card's primary safeguard against use outside the model's competence." | ||
| }, | ||
| { | ||
| "expression": "$.risks.risks[?(@.domains[?(@.type=='ethical')])]", |
There was a problem hiding this comment.
I get the feeling Steve may be reworking "risk" as the object includes perhaps too much... The goal is to isolate risks, harms and benefits more effectively so perhaps they can be disassociated from most of the risk object (and optionally tied/bound to risks) and include them in "considerations" (for model design).
3 participants
Implements #1066.
What this adds
1. Schema: optional predefined field on perspective (cyclonedx-perspective-2.0.schema.json)
{ "perspectives": [ { "predefined": "model-card" } ] }Why a field rather than the choice pattern
We deliberately chose a field on the perspective object instead, since it keeps a pre-defined perspective addressable. A bare enum string cannot carry a bom-ref, so a string-item pre-defined perspective could never be the target of a BOM-Link or any other intra-document reference. With the field form, { "bom-ref": "…", "predefined": "model-card" } remains a first-class, referenceable node, and the oneOf on the object enforces the same pre-defined/custom exclusivity the choice pattern would have given us.
2. Catalog: perspectives/model-card-perspective.json
Second entry in the perspectives/ catalog introduced by #960, following its delivery shape (a complete, minimal, valid 2.0 document containing only the perspective). This is the definition incorporated when a document declares "predefined": "model-card".
The mappings express the industry-standard model card structure over the 2.0 decomposition of the former first-class modelCard entity:
3. Test fixtures (auto-discovered by the schema-v2 suite):
Not included
Dependencies