Three small fields keep a CycloneDX file coherent. The bom-ref gives a component a handle inside the file. The serialNumber identifies the BOM. The version counts revisions of that BOM. Mixing them up leads to broken links and confusing update histories.
bom-ref
A bom-ref is an identifier that lets other parts of the BOM refer to a component. Per the 1.7 JSON reference, each bom-ref must be unique within the BOM, must be at least one character long, and should not start with the BOM-Link prefix urn:cdx:.
Typical use: the dependency graph points at components by their bom-ref. If two components accidentally share a value, the graph silently connects the wrong things. Generate them from something stable, such as the package URL, and check uniqueness.
serialNumber
The serialNumber is an optional string that identifies the BOM, and the page recommends using it. If present it must match the pattern urn:uuid followed by a lowercase UUID in the 8-4-4-4-12 form. The reference says every generated BOM should have a unique serial number, even if its contents have not changed.
Think of it as the identity of a document. A new generation run gets a new serial number.
version
The version is an integer. It defaults to 1 and the minimum is 1. The reference says to increment it by 1 whenever the BOM is modified, by hand or by automation. When several BOMs share a serial number, systems should use the one with the highest version.
So the serial number says which BOM, and the version says which revision of it.
How they work together
Two patterns are legitimate:
- Generate a fresh BOM each build, with a new serial number and version 1.
- Keep one BOM identity and revise it, keeping the serial number and raising the version each time.
Pick one and tell your consumers. Do not change the content and keep both the serial number and the version, since consumers will not know there is a newer file.
The 2026 connection
The 2026 CISA elements add SBOM version as a minimum data field, alongside the SBOM timestamp. If you use CycloneDX, the version field is the natural place for it. Check how the final document defines it before you map your fields.
Mistakes to avoid
- Reusing bom-ref values across components
- Starting a bom-ref with urn:cdx:
- Editing a BOM by script without raising the version
- Omitting the serial number, which makes referencing the file harder
Quick check
Should a new build get a new serial number?
If you generate a new BOM, yes. The reference says every generated BOM should have a unique serial number.
Which version wins if two share a serial number?
The highest version.
Sources
Last reviewed: 19 October 2026.
