Introduce pre-defined perspectives

[taleodor]

• Implements [2.0]: Proposal - Pre-defined perspectives: stable spec-provided identity with incorporation by reference #1066.

What this adds

1. Schema: three forms of a perspective, and scopes (cyclonedx-perspective-2.0.schema.json)

A perspective is one of three mutually exclusive forms (oneOf, enforced in all directions):

{ "bom-ref": "card-vision", "predefined": "cdx:perspectives:model-card", "predefinedVersion": 1, "scopes": [ … ] }
{ "bom-ref": "crypto-per-model", "ref": "def-crypto-in-use", "scopes": [ … ] }
{ "bom-ref": "custom", "name": "…", "mappings": [ … ], "scopes": [ … ] }

• Pre-defined form (predefined + predefinedVersion): incorporates a published perspective from the CycloneDX perspectives catalog by identity, giving tooling stable spec-backed identity instead of free-text name matching. Identities live under the reserved cdx: namespace with a cdx:perspectives: path (per @mrutkows), so they cannot collide with author-chosen names and can be declared in the reserved cyclonedx-property-taxonomy. predefinedVersion pins the published revision: it is the version of the catalog document defining the perspective (integer, incremented by 1 per revision, like other CycloneDX version fields). Initial identities: cdx:perspectives:model-card and cdx:perspectives:pqc-readiness (the latter reserved for the entry proposed in Add sample PQC readiness perspective for CBOM #960).
• Definition reference form (ref): applies a reusable inline perspective declared under definitions.perspectives (see 1b), by bom-ref or BOM-Link element.
• Inline form (name + mappings): fully defined in the document.

In the two reference forms only bom-ref and scopes may accompany the reference, so the referenced definition stays the single source of truth while the document decides where it applies.

Why a field rather than the choice pattern. A field on the perspective object keeps a pre-defined perspective addressable. A bare enum string cannot carry a bom-ref, so it could never be the target of a BOM-Link or any intra-document reference. With the field form, { "bom-ref": "…", "predefined": "cdx:perspectives:model-card", "predefinedVersion": 1 } remains a first-class, referenceable node, and the oneOf enforces the same exclusivity the choice pattern would have.

scopes: applying a perspective to parts of the document. Without scopes a perspective applies to the whole document. With scopes, each entry is an independent application: one view, one completeness evaluation.

"scopes": [
  { "bom-ref": "scope-vision", "name": "Vision model", "targets": ["model-vision"] },
  { "bom-ref": "scope-text",   "name": "Text models",
    "expressions": ["$.definitions.components[?(@.type=='machine-learning-model' && @.group=='text')]"] }
]

• expressions[]: JSONPath (RFC 9535) from the document root; targets[]: bom-ref or BOM-Link (elementLink, the type compositions use). At least one of the two; within a scope they union.
• Resolution (normative text on scopes, written as a numbered algorithm so implementations converge): (1) evaluate expressions from the root; (2) resolve targets by bom-ref; (3) one-hop closure: every same-document reference entry (an object with a ref property, as the inventory refactor introduces) inside the selected subtrees also selects the referenced node; (4) the scope is the union of the selected subtrees. Containment is by JSONPath Normalized Path prefix (RFC 9535 §2.7). BOM-Links to other documents are not followed.
• Mapping expressions stay root-absolute: a mapping selects the intersection of its expression with the scope. Nothing is relative, so catalog entries stay generic and the document decides where they apply. Published pre-defined perspectives and definitions declare no scopes of their own.
• Closure is tooling behaviour; the schema validates structure only.

via on a mapping: following references. JSONPath cannot join, so data related to a scoped subject (the datasets a model trained on, the risks that affect it, the algorithms a library provides) needed a way to be reached. via is an ordered list of traversal steps applied before the expression; each step is exactly one of:

• { "refs": "<root-absolute JSONPath>" }: restricted to the current node set, collect reference values and resolve them to objects in this document. Forward references, e.g. a model's training.datasets.
• { "referrers": "<root-absolute JSONPath>" }: the inverse. The path selects reference values anywhere in the document; the step produces the objects that hold a value identifying a node in the current set (the object owning the property, or, when the value sits in an array, the object holding the array). For relationships that point towards the scoped nodes, e.g. a risk's affects. The step replaces the current set with the matching referring objects; when the current set is the whole document it produces the whole document, so an unscoped perspective is not narrowed.
• { "dependencies": "depends-on" | "provides" | "dependents" | "provided-by", "transitive": bool }: walk the dependency graph from the referenceable nodes within the current set.

The first step starts from the scope (or the whole document when unscoped); the expression is then intersected with the subtrees of what the last step produced. Steps chain:

{ "expression": "$.definitions.components[?(@.type=='cryptographic-asset')]",
  "via": [ { "dependencies": "depends-on", "transitive": true }, { "dependencies": "provides" } ] }

Worked example for referrers (from @JunHwan-Kwon's review): two models, risk-a with "affects": ["model-a"], risk-b with "affects": ["model-b"]. A model card scoped to model-a evaluates a risk mapping as: current set {model-a} → referrers: $.risks.risks[*].affects[*] yields {risk-a} → expression intersected with that subtree → risk-a. Unscoped, both risks are selected. Selection is automatic; authors do not add risks to the scope.

1a. Registry: schema/perspectives-defs.schema.json + schema/perspectives-defs.json

The identity enum does not live in the versioned perspective schema. It lives in a standalone registry at the schema root, which the perspective schema $refs (../../perspectives-defs.schema.json#/definitions/preDefinedPerspectivesEnum), following the cryptography-defs pattern, so perspectives can be added or revised without a specification release.

• perspectives-defs.schema.json is hand-maintained: the identity enum (with meta:enum descriptions) plus the governing schema for the registry data. No mapping is declared; by naming convention the catalog document defining cdx:perspectives:<name> is perspectives/<name>-perspective.json.
• perspectives-defs.json is generated. Per identity it records every published version with the sha256 of the catalog document's canonical JSON and the commit that introduced it. Once registered, a version's content is immutable; changing a catalog document requires bumping its version by 1. Identities without a catalog document yet (pqc-readiness) are reserved and absent until their document lands.
• CI: the schema-v2 suite checks every identity on each PR (reserved, new, unchanged, or bumped by exactly one pass; a content change without a bump, a regressed or skipped version, or a removed registered document fail). A workflow runs the generator after merge and opens a PR registering any new version, mirroring generate_algorithm_families.yml.

1b. Reusable definitions: definitions.perspectives (cyclonedx-definition-2.0.schema.json)

Reusable inline perspectives, each with a required bom-ref, typed as perspectiveDefinition, a mixin over the perspective schema that forbids predefined, predefinedVersion, ref and scopes. The same definition can be applied at several places with different scopes without repeating its mappings. Follows the definitions-registry direction of #1075.

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": "cdx:perspectives:model-card". 23 mappings, eight reached through via:

• Model identity: details (name, version, description), identifiers (identity claims grouped by asserting party, e.g. a Package-URL for a model hub entry), supplier via party roles, licence.
• Intrinsic characteristics via modelProperties: tasks, learning types, architecture, inputs/outputs, size and quantization, evaluation, limitations, environmental considerations. Models are located by descendant search ($..[?(@.type=='machine-learning-model')]) so the entry applies whether models are declared at the document root, in inventories, or in definitions.
• Training: the training object; the training procedure reached through via.refs over modelProperties.training.formula into $.formulation[*] (workflows and tasks as the training stages and the data each consumed).
• Datasets, reached through via.refs over modelProperties.training.datasets, in four mappings so completeness can report which aspect is missing: identity and licensing (required), description and contents, classification and sensitive data, governance (parties accountable as owner, steward, custodian).
• Intended use: the model's use-case references, and the use-case definitions reached through via.refs; intended users via party roles.
• Ethical and fairness considerations as risk model entries (ethical domain; fairness/bias impact categories), reached through via.referrers over $.risks.risks[*].affects[*]: for a scoped model, exactly the risks that name it in affects; unscoped, every matching risk.

Not mappable today: provenance labels such as crawled or synthetic, and data subsets with rationale; the 2.0 data model has no fields for them.

3. Tests

• Fixtures (auto-discovered by the schema-v2 suite). Valid: the pre-defined reference form alongside a plain inline perspective; a scoped document exercising targets, expressions, a definitions.perspectives entry applied at two scopes by ref, a chained dependency traversal and a refs step; the two-models/two-risks document with a model card scoped to model-a and an inline perspective using referrers. Invalid: unknown identity (correct namespace, not in the enum); reference missing predefinedVersion; identity plus inline mappings; identity plus name and domains; scope with neither expressions nor targets; traversal step mixing refs and dependencies; traversal step mixing referrers and refs; unknown dependency direction; ref plus inline mappings; ref plus predefined; a definition declaring scopes; a definition without bom-ref.
• Registry test (test:v2.0:t4-perspectives-registry, runs in the JavaScript CI workflow on every PR): validates perspectives-defs.json against its governing schema, checks registered identities are in the enum with contiguous versions from 1 and conventional file paths, and assesses each identity's catalog document against the registry.
• Harness wiring: perspectives-defs.schema.json registered as an external schema in both JS ajv harnesses, the Java 2.x harness's classpath mapping, and the bundler's ref-exception list, mirroring cryptography-defs.schema.json.

Not included

• Bundled schemas — left to the post-merge bundle workflow, per repo convention.
• Conformance validation — the schema validates identity, exclusivity and structure; evaluating scopes, closure, traversal steps (refs, referrers, dependencies) and mapping expressions against a document's data remains tooling territory, as for perspectives generally. The fixtures pin the intended node selections in prose; a semantic evaluator would be a separate contribution.

Dependencies

• Premised on Clean check-in of AI/ML. Supersedes #948.  #990: the catalog entry's mappings target modelProperties, training.datasets, training.formula and useCases. The schema change and fixtures stand alone; only the catalog entry's JSONPath expressions assume Clean check-in of AI/ML. Supersedes #948.  #990's shape. Happy to adjust if that lands differently.
• Written with Inventory refactor and definitions registry #1075 in mind: schema examples use the inventory layout, definitions.perspectives follows its definitions registry, and the catalog's descendant search covers both the current and the inventory layout. Fixtures keep the root components layout until Inventory refactor and definitions registry #1075 lands.
• Complements Add sample PQC readiness perspective for CBOM #960: adopts its perspectives/ folder and delivery shape, and reserves cdx:perspectives:pqc-readiness for its entry; to be registered automatically, that document needs to live at perspectives/pqc-readiness-perspective.json at version 1.

[JunHwan-Kwon]

Thanks for incorporating the wording in 7a7d2dd.

One separate, non-blocking question about completeness tooling. My executable probe reproduces the replacement of {model-a} by {risk-a} for the existing two-model/two-risk fixture, without retaining model A in that mapping's evaluation set. This F1 node-selection trace is unchanged from fdc2bd6.

The PR already includes a multi-subject scope: valid-perspective-scopes-2.0.json groups two text models into one expression scope and describes them as "evaluated as one card."

For the required License mapping, $..[?(@.type=='machine-learning-model')].licenses, two fixtures that validate against the pinned #1067 modular schema give the following candidate-policy outcomes:

Case	Any match within scope	Per-initial-subject presence	Per-initial-subject non-empty
Two models in one scope; only model A has licenses	pass	fail	fail
One model with licenses: []	pass	pass	fail

These results compare possible policies; they are not conformance verdicts. Both cases evaluate the initial model subjects directly and do not test attribution after via.

For a required mapping, is the intended rule (a) at least one matching node within the scope, (b) presence for every initial model selected by the scope, or (c) a consumer-policy choice? Separately, should selecting an empty collection such as [] count as present?

If both points are intentionally left to consumer policy, that would also resolve the question. I am not requesting a scoring implementation in this PR; a short clarification or linked follow-up would be sufficient.

Reproduction evidence: pinned inputs, F1 before/after trace, candidate-policy matrix, and schema validation.

[taleodor]

@JunHwan-Kwon

Thank you,

On the F1 trace. That transition is specified behaviour rather than a regression. via.referrers states it directly: "the step replaces the current set with the matching referring objects; objects are not retained merely because they were already in the current set." A risk mapping scoped to model A therefore evaluates {risk-a}, not {model-a, risk-a}. That is intentional: the mapping selects the risks that affect the model, and the model itself is already selected by the scope.

On required. The intended reading is (a), with granularity chosen by scoping rather than by the relevance value. The scope is already the unit of evaluation — "tooling generates one view and one completeness evaluation per scope" — so a required mapping is satisfied when it selects at least one node within the scope, and a verdict per model is obtained by declaring one scope per model, as scope-vision does. scope-text groups both text models deliberately; "Both text models, evaluated as one card" is a request for a single verdict over the pair.

(b) is not well-defined in this model once traversal is in play. After a via step the initial subjects are no longer in the evaluation set, by the rule quoted above, so there is nothing to attribute per-subject presence to without back-pointers the specification does not carry. Your matrix notes the same boundary — the fixtures "do not test attribution after via". Defining (b) would make required mean one thing for direct mappings and something else for traversed ones.

On empty collections. Presence is node selection: licenses: [] is selected, so it is present. Whether an empty collection is sufficient is consumer policy. relevance and weight are importance annotations — "Indicates the importance of a data type to a perspective", and a "relative ranking of mappings" — and this specification deliberately defines no scoring algorithm. An empty-collection rule would be the only conformance rule in a document that otherwise carries none.

I will make this explicit in the text rather than leave it implied, along these lines:

Relevance and weight rank importance to the audience; they do not define a conformance rule. Within a completeness evaluation, a mapping is satisfied when it selects at least one node within the scope; declare one scope per subject for a verdict per subject. Whether a selected but empty collection is sufficient is left to the consumer's policy.

[JunHwan-Kwon]

@taleodor Thank you. This resolves my completeness question.

I reran the bounded License probes at d3fca0c and recorded the clarified interpretation as any-match per scope, with one scope per subject when a per-subject verdict is needed. Selecting licenses: [] establishes node presence, while whether that value is sufficient remains consumer policy.

I will retain F2 and F5 as non-normative policy comparisons, with the intended interpretation now recorded, and consider this question resolved.

Updated evidence: pinned inputs and required-policy replay.

[mrutkows]

Looks good and thanks for your work; it is very, very important.

Could you help me see the previous "ask" where I wanted a means to request that any appearance of "bom-ref" (by default or within specified objects) would cause those referenced objects to be pulled into the perspective output document.

[mrutkows]

Assume we can have a "Published At" as a means to express the model repo. (e.g., Hugging Face, Ollama, LM Studio, etc.)

[taleodor]

We can add a separate mapping, or modify this one, lmk how you want it + can discuss more on call.

[mrutkows]

We can use CycloneDX semantics for "native" names. Although I was not a fan of "formula" I would like CDX perspective to name things according to our 2.0 element/object names (e.g., "Training formula", "Fine-tuning formula", etc.)

[taleodor]

Again, can be renamed or split to different mappings. We can discuss.

[taleodor]

@mrutkows

Could you help me see the previous "ask" where I wanted a means to request that any appearance of "bom-ref" (by default or within specified objects) would cause those referenced objects to be pulled into the perspective output document.

1. Scope: referenced objects are pulled in automatically

A scope selects the part of the document the perspective applies to, and it can be declared by reference or by path:

"scopes": [
  {                                   // by ref — bom-ref / bom-link
    "bom-ref": "scope-vision",
    "name": "Vision model",
    "targets": [ "model-vision" ]
  },
  {                                   // by path — RFC 9535 JSONPath from the document root
    "bom-ref": "scope-text",
    "name": "Text models",
    "description": "Both text models, evaluated as one card.",
    "expressions": [
      "$.components[?(@.type=='machine-learning-model' && @.group=='text')]"
    ]
  }
]

2. Mappings: via steps, when you want to state the traversal explicitly

Where the data is related to the scope rather than contained in it, a mapping declares traversal steps. Three kinds, applied in order, each to the result of the previous:

// refs — resolve reference values found at a path
{
  "expression": "$..[?(@.type=='data')]['name','version','identifiers','licenses']",
  "via": [ { "refs": "$..[?(@.type=='machine-learning-model')].modelProperties.training.datasets[*]" } ],
  "nativeName": "Dataset Identity and Licensing"
}

// referrers — the inverse: objects that hold a reference to the current nodes
{
  "expression": "$.risks.risks[?(@.domains[?(@.type=='ethical')])]",
  "via": [ { "referrers": "$.risks.risks[*].affects[*]" } ],
  "nativeName": "Ethical Considerations"
}

// dependencies — walk the dependency graph, optionally transitively
{
  "expression": "$.components[?(@.type=='cryptographic-asset')]",
  "via": [ { "dependencies": "depends-on", "transitive": true },
           { "dependencies": "provides" } ],
  "nativeName": "Algorithms in Use"
}

3. Possible gaps

1. The reference-following matches only one of the two shapes CycloneDX uses.
A reference is followed when it appears as an object carrying a ref property. Most relationships in 2.0 are encoded as bare reference strings instead. training.datasets[] resolves to refLinkType, and dependsOn, provides and affects are arrays of plain values. Those are skipped. (Can still be expressed by other means).

2. Only outbound references are followed.
References contained in the scoped subtree are followed. Objects that point at the scoped node from elsewhere are not reached, because they sit outside that subtree. This matters most for dependencies, which is a document-root array: an entry such as {"ref": "model-vision", "dependsOn": ["lib-openssl"]} is a sibling of components, not part of the model's subtree, so scoping a model never pulls in its dependency graph at any depth. The same applies to risks[].affects[]. Reaching either requires a mapping with via.referrers or via.dependencies.

3. Following stops after one hop.
A reference is resolved and its target selected, but that target's own references are not followed in turn. If A references B and B references C, the scope contains B and never C; C has to be enumerated in the scope or reached with a via step.

4. There is no control over which references are followed.
Following is unconditional: every qualifying reference inside the scope is followed, always. There is no way to express "follow the training-dataset references but not the rest".

5. A via step replaces the working set rather than adding to it.
Each step produces the nodes it reaches, and nodes are not retained merely because they were already in the set. A single mapping therefore cannot express "the scoped nodes and what they reference". It is one or the other.

[taleodor]

Note: squashed to fix DCO issue.

[JunHwan-Kwon]

Following the current #990 structure, I have reduced this integration check to three directly applicable suggestions covering four mappings at 565b1d1.

Reproduction, exact patch, and results are pinned to #1067 565b1d1 and #990 f3d8521. Both official #990 fixtures and the original/proposed #1067 catalogs pass their respective complete modular schemas. On the risk-integration fixture, the proposed selections are 3 performance records, 1 intended-use reference collection, 1 referenced use-case definition, and 2 energy records; the current catalog selects none of these. The plain model fixture correctly continues to select no use case because it declares none.

The measurement suggestions follow #990's inline examples. The use-case suggestion is one explicit implements-only catalog policy, offered for acceptance or rejection; it is not claimed to be an already agreed rule. Fourteen additional checks cover all ten assertion types, model-specific reference selection, and an empty reference collection. The empty collection remains a selected node, so this does not add a new non-empty completeness rule.

These suggestions are limited to the four mappings. The previously closed Required/Fairness questions remain closed, and no scope, closure, or completeness-processing change is proposed. The tests are bounded selection checks, not a full perspective-conformance result.

[taleodor]

Latest 2.0-dev was merged / conflicts resolved.

[stevespringett]

@taleodor Congrats. This has passed community review. However, please address the implementation issues that Jan raised so that we can merge this in this week.

[taleodor]

@taleodor Congrats. This has passed community review. However, please address the implementation issues that Jan raised so that we can merge this in this week.

Thank you, I believe issues are addressed now. @jkowalleck please lmk if you still have concerns.