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
| Axis | Example | Changes when |
|---|---|---|
| Carrier format | CycloneDX specVersion 1.7 → 2.0 | the SBOM/CBOM standard is revised |
| Profile | interface-disclosure v0.8 → v0.9 | the requirements change |
| Content revision | a product's CBOM version over time | the 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:
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.7 | CycloneDX 2.0 |
|---|---|
bomFormat | specFormat |
metadata.component | inventories[0].subject |
components[], services[] | inventories[0].components[], a service having type: "service" |
purl on a component | identifiers[], each asserted by a declared party |
supplier, manufacturer on a component | parties[], each with a role |
cryptoRefArray, algorithmRef and the certificate references | relatedCryptographicAssets[] |
curve (deprecated in 1.7) | ellipticCurve, enumerated |
certificationLevel; module validation as a property | certifications[] |
compositions[].assemblies | compositions[].targets, kind components |
property pkic:profile:subjectIdentifier | an 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:
- Paths change, attributes do not. The validator reads the subject, services, package URLs and in-use algorithms from their 2.0 locations. Attribute names, levels and vocabularies are unchanged.
- Native fields for some profile attributes.
certifications[]carries module validation on the implementing library and product certification on the subject.rotationandrenewaldescribe how keys and certificates are replaced; no rule reads them yet. The capability-by-purpose group still has no native field. - Supported and in use.
cipherSuitesstill mean the supported set. The in-use set moved fromcryptoRefArraytorelatedCryptographicAssets. - Risks are ignored. The root
risksarray carries status, owner, response and target date. These values are judgements, not product facts. The validator ignores them for conformance, and a supplier's product record should not contain them (decisions 0002 and 0007). - Perspectives mark JSONPath expressions as required, recommended or optional. They cannot express conditions or vocabularies. Each profile publishes one, generated from its rules, as an informative companion. The rules file stays normative.
- Terminology. CycloneDX 2.0 uses "profile" and "interface" for other concepts. The documentation says "PKIC CBOM profile" and "cryptographic interface" wherever both could be meant.
- The edge gap remains. CycloneDX 2.0 adds a blueprint model with flows and boundaries. That model describes a deployed system for threat analysis. It does not describe a product's cryptographic interface, so it does not close the gap.
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:
- Replace the files in
tests/schemas/cyclonedx-2.0/with the released schema, and record the release in its README. - 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. - Regenerate the examples with
tools/build_keycloak_examples.py, then the perspectives and the demonstration reports. - 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
- Normalize at the adapter. Prefer Cryptography Registry identifiers where they are present, and the enumerated
ellipticCurvein 2.0. CycloneDX 1.6 CBOMs use free-text algorithm names. For those, apply a versioned name map before the rules are evaluated. - Upgrade rather than reject. Convert a legacy but supported CBOM mechanically rather than rejecting it.
cdx17_to_20.pyconverts 1.6 and 1.7 to 2.0. The conversion re-encodes existing facts and adds no new ones. This is consistent with the expectation in the minimum elements guidance that organizations accommodate updates to bill-of-materials data, including corrections. - Pin the profile version in every conformance claim. When a rule is tightened, enforce the tightening only after a dated grace window. During that window the validator emits a warning, so that the warning comes before the result changes to a failure.
- Deprecate, rather than delete, vocabulary. If
interfaceTypevalues change, retain recognition of the former values (mapped to their replacements) for at least one profile major version. - Treat freshness as a policy question. A claim stays true about the revision it names, even after a newer revision replaces it. A consumer's policy decides how old a revision may be, so that an older revision is not treated as wrong without cause.