CBOMProfiles /Methodology ← Working group site
OPERATIONS

Handling older CBOM files

"An older CBOM" can mean three different things, because three items each carry their own version and change independently: the document format (for example CycloneDX 1.7), the PKIC CBOM profile, and the CBOM's content. A conformance claim must state all three versions, or nobody can repeat the check and get the same result.

Three version axes

AxisExampleChanges when
Carrier formatCycloneDX specVersion 1.7 → 2.0the SBOM/CBOM standard is revised
Profileinterface-disclosure v0.8 → v0.9the requirements change
Content revisiona product's CBOM version over timethe product or a re-scan changes

The carrier format is the document format in which a CBOM is written. The three axes vary independently. For example, a newly generated CBOM (a new content revision) may still be serialized in CycloneDX 1.7 (an older carrier) and evaluated against the baseline v0.9 (newer rules). A common error is to treat the three axes as one.

When a profile needs a new version. A profile gets a new version when its requirements change. It also gets one when it changes the format versions it accepts, or changes its mapping, because either change can move a document from one band to another. Checking a profile against a new release of the format, with no other change, does not need a new version. The changelog records that check as editorial. A claim stays reproducible because it cites both the profile version and the format version.

The values for two of these axes are now recorded as data in the bill of materials, rather than left to local convention. The 2026 minimum elements guidance adds the elements SBOM Data Format Name and SBOM Data Format Version, which record the carrier version. It also adds SBOM Version, which records the content revision. Its Frequency element expects a new bill of materials for each build or release. Content revisions are therefore produced as a matter of course rather than on request. A producer that meets the minimum elements guidance supplies the two values a validator needs to place a document on both axes. See References.

Carrier version bands

Each PKIC CBOM profile declares the range of carrier versions it accepts, so that the validator handles older CBOMs by a stated rule. Every profile in the family specifies "appliesTo": { "cyclonedx": { "min": "1.6", "tested": "2.0" } }. The validator then places each CBOM in one of four bands (ranges of carrier versions), and each band receives its own treatment:

< 1.6 1.6, 1.7 2.0 > 2.0 refuse upgrade first legacy — accept, warn same verdicts target — accept pinned 2.0-dev @ 76f185c newer — accept, review the examples examples/legacy/ min = 1.6 tested = 2.0
A declared range does two things. It provides a migration window, so that the 1.x CBOMs today's tools emit are still evaluated while the target is 2.0. It also sets a defined lower bound. Below that bound, evaluation could produce an incorrect verdict (pass or fail result).

The validator reports the band in which the CBOM falls. Each band needs its own input. examples/cbom-keycloak-product.cdx.json is at 2.0, the tested version. examples/legacy/cbom-keycloak-product-1.7.cdx.json falls in the legacy window. A copy of the 2.0 record marked 2.1 is newer than tested. A copy of the legacy record marked 1.5 is below the minimum and is refused. Files gives the commands.

How a CycloneDX 1.7 document is read

The validator reads both carrier generations and produces the same abstract record from each. For a 1.7 document it takes the subject from metadata.component, services from services[], package URLs from purl, and the algorithms in use from cryptoRefArray and algorithmRef. For a 2.0 document it takes the same facts from inventories[0].subject, from components of type service, from identifiers[] and from relatedCryptographicAssets. The rules are written once and see only the abstract record.

The legacy band changes the report, not the verdict. The Keycloak product record is published twice, with the same facts. The 2.0 record is the target. The 1.7 record, examples/legacy/cbom-keycloak-product-1.7.cdx.json, conforms to the same five profiles: interface-enumeration v0.3, the baseline v0.9, pqc-migration v0.8, pqc-migration-extended v0.1 and procurement v0.1. Its report opens with FORMAT [warn] CycloneDX 1.7 accepted, profile tested against 2.0 (legacy -- warn), and a conformance claim records the band as legacy.

Some 1.x documents fail for their content, not their version. examples/legacy/cbom-keycloak-scanner-output.cdx.json is untargeted scanner output in CycloneDX 1.7. The validator reads it, places it in the legacy band and finds that it fails even the entry profile, on P1, P3, P4, P5 and P6.

CycloneDX 2.0 as the target

CycloneDX 2.0 is the target carrier (decision 0025). It is not yet released, so the PKIC CBOM profiles are pinned to the development branch 2.0-dev of CycloneDX/specification, commit 76f185c (23 October 2026). The repository holds that schema in tests/schemas/cyclonedx-2.0/. Ecma is expected to ratify the release in December 2026.

A CycloneDX 1.7 document is not valid 2.0. The changes are structural, and the profile attributes do not change. These are the changes the examples rely on:

CycloneDX 1.7CycloneDX 2.0
bomFormatspecFormat
metadata.componentinventories[0].subject
components[], services[]inventories[0].components[], a service having type: "service"
purl on a componentidentifiers[], each asserted by a declared party
supplier, manufacturer on a componentparties[], each with a role
cryptoRefArray, algorithmRef and the certificate referencesrelatedCryptographicAssets[]
curve (deprecated in 1.7)ellipticCurve, enumerated
certificationLevel; module validation as a propertycertifications[]
compositions[].assembliescompositions[].targets, kind components
property pkic:profile:subjectIdentifieran identifier with the custom scheme tag-uri

cdx17_to_20.py applies these changes to a 1.6 or 1.7 CBOM. It re-encodes existing facts and adds none. The repository's example generator builds each Keycloak document in 1.7 form and converts it, so the converter runs on every example.

CycloneDX 2.0 has the following consequences for the profiles:

Re-pinning to the released 2.0

When Ecma ratifies CycloneDX 2.0, the working group moves from the pinned commit to the release. The steps are these:

  1. Replace the files in tests/schemas/cyclonedx-2.0/ with the released schema, and record the release in its README.
  2. Compare the released schema with commit 76f185c. Where a field the profiles use has moved, revise the converter, the validator's 2.0 reading and the mapping.
  3. Regenerate the examples with tools/build_keycloak_examples.py, then the perspectives and the demonstration reports.
  4. Run the test suite. It validates every example against the schema and checks every expected verdict.

The carrier range keeps tested at 2.0, so the profiles' acceptance rule does not change. Conformance claims and policy results bind a document by digest. Where a regenerated example changes, its digest changes, and the claims and results that cite it are issued again. A document that a producer wrote against the pinned commit also says specVersion 2.0. If a field moved before the release, such a document may not validate against the released schema, and the producer should regenerate it.

Supporting recommendations

PKIC CBOM Profiles Working Group · draft for comment.