Skip to content

Introduce pre-defined perspectives - #1067

Draft
taleodor wants to merge 4 commits into
CycloneDX:2.0-devfrom
relizaio:2.0-predefined-perspectives
Draft

Introduce pre-defined perspectives#1067
taleodor wants to merge 4 commits into
CycloneDX:2.0-devfrom
relizaio:2.0-predefined-perspectives

Conversation

@taleodor

@taleodor taleodor commented Aug 29, 2026

Copy link
Copy Markdown

Implements #1066.

What this adds
1. Schema: optional predefined field on perspective (cyclonedx-perspective-2.0.schema.json)

{
  "perspectives": [
    { "predefined": "model-card" }
  ]
}
  • Identifies predefined (well-known) perspectives published in the CycloneDX perspectives catalog and incorporates the published definition by reference, giving tooling stable spec-backed identity instead of free-text name matching.
  • predefined and inline mappings are mutually exclusive (oneOf, enforced in both directions): a perspective either declares a pre-defined identity or defines its own mappings, never both. The part-of-spec published definition is the single source of truth for what a pre-defined perspective contains.
  • Initial enum values: model-card, pqc-readiness (the latter matching the catalog entry proposed in Add sample PQC readiness perspective for CBOM #960), with meta:enum descriptions.
  • Naming follows the schema's existing preDefinedPerspectiveDomain vocabulary.

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:

  • intrinsic technical characteristics via modelProperties, scoped to $.components[?(@.type=='machine-learning-model')] (the only component type that may carry them)
  • training datasets as components of type data
  • supplier / intended users via the party model roles
  • intended use cases as use case definitions
  • ethical and fairness considerations as risk model entries (ethical domain; fairness/bias impact categories)

3. Test fixtures (auto-discovered by the schema-v2 suite):

  • valid document covering the reference form and a plain inline perspective; invalid documents covering an unknown predefined value and the forbidden mixed form (predefined + mappings).

Not included

  • Bundled schemas — left to the post-merge bundle workflow, per repo convention.
  • Conformance validation — the schema validates identity and exclusivity; whether a document's data satisfies a perspective's mappings remains tooling territory, as for perspectives generally.

Dependencies

…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant