Tools often write SPDX 2.3 because it is widely read by other tools, even though the SPDX site lists 3.0 as current. A format version is a compatibility choice. Pick the one your recipients can parse, state it in writing, and ask your tool whether newer output is on its plan.
What the sources show
The SPDX specifications page lists 3.0 as the current version, with 2.3, 2.2, 2.1, 2.0 and older versions listed as previous. Formats differ by version: 3.0 is offered as PDF, HTML and SHACL, while 2.3 is offered as HTML, RDF and OWL.
The pnpm documentation for its sbom command gives a live example of a tool choice. It writes SPDX 2.3 as JSON, and CycloneDX 1.7 as the default for the other format, with older CycloneDX spec versions selectable. So within one tool, the two formats can sit at different points in their version history.
Why tools lag
Writers of SBOM tools weigh three things: what consumers can read, how big the schema change is, and what users ask for. A newer version of a spec is just useful if downstream tools ingest it. That is why version choices vary.
A decision guide
| Your situation | Sensible default |
|---|---|
| Recipient names a version | Match it exactly |
| Recipient is unknown | Offer the version most tools read, and say which |
| You publish for the public | Consider offering two versions if you can keep both in sync |
| You are choosing a tool | Ask what versions it writes and reads today |
Steps to handle it
- Look at the top of your SBOM file. The version appears in the document header.
- List who consumes the file: customers, scanners, your own platform.
- Test an import in each consumer with a sample file.
- Write the version into your SBOM policy and your customer cover note.
- Review the choice when a major tool in your chain adds support.
What not to do
Do not rename or hand edit the version string to make a file look newer. The content must follow the schema of the version you declare, and a validator will catch the mismatch. Also avoid assuming that a higher number means better data. A newer version offers more ways to express things. Whether your tool fills them in is a separate question.
Questions for a vendor
- Which SPDX and CycloneDX versions do you write, and which do you read?
- Can I pick the version per export?
- What happens to fields that a version cannot express?
- How do you announce new version support?
A worked example
A mid sized software company, call it Acme, sells to three kinds of customers. Customer A has a procurement team that asks for SPDX and has not said which version. Customer B runs an internal tool that ingests CycloneDX solely. Customer C asks for whatever is easiest. The company's build tool writes SPDX 2.3 JSON and CycloneDX. This scenario is made up to illustrate the decision.
Acme's team follows a simple process:
- Ask customer A which SPDX version their tooling reads. They reply 2.3.
- Confirm that the build tool writes 2.3. It does, so no conversion is needed.
- For customer B, send CycloneDX at the version their tool lists.
- For customer C, send CycloneDX and state the version.
- Record each decision in the account notes so the next release reuses it.
No one needed SPDX 3.0 to finish this work. The version question was answered by asking, not by guessing.
How versions differ in practice
The SPDX specifications page shows 3.0 as current and lists the earlier versions with different file formats. Version 2.3 is available as HTML, RDF and OWL, while 3.0 is offered as PDF, HTML and SHACL. That tells you the specification documents themselves are packaged differently, which hints at real structural changes between major versions.
A conversion between versions is not a rename. Fields move, and some concepts are expressed differently. If a tool converts, check what was lost, the same way you would when converting between SPDX and CycloneDX.
A comparison of strategies
| Strategy | Good when | Risk |
|---|---|---|
| Emit the version your recipients read | You know your audience | May lag the newest spec |
| Emit the newest version | Recipients are ready | Older tools reject it |
| Emit two versions | Mixed audience | Files can drift apart |
| Convert at export | Tool supports it | Silent field loss |
Pick one strategy per audience, not per file.
Test before you commit
Create a sample SBOM with a few components, export it in each version you consider, and import it into every tool in your chain: your own scanner, a customer's tool if they share a sample, and any registry or portal. Note what each tool accepts, warns about or rejects. That half hour of testing prevents weeks of back and forth.
Watch the roadmap
Ask your tool vendor when newer versions will be supported, and how they will announce it. If they cannot answer, treat that as information. Add a calendar reminder to revisit the choice each quarter.
What to put in the cover note
A single line is enough: the format, the version, how the file was generated, the date, and the release it describes. When a customer later asks why you sent 2.3 and not 3.0, the note and your test results answer the question.
Where Safeguard fits
Safeguard handles SBOM import and scanning. To check how a file in your preferred version reads, try the free scan at gold.safeguard.sh/scan.
Try it yourself
Click through it at your own pace, or open it full screen.
Click into a few components and note how direct and transitive packages are separated.
Quick check
Is SPDX 2.3 outdated?
It is a previous version per the SPDX site, but it remains widely usable. Decide by what your recipients can read.
Should I send both 2.3 and 3.0?
Just if you can keep them consistent. Two files that disagree cause more trouble than one clear file.
Is it risky to convert SPDX 2.3 to 3.0 myself?
It can be, because fields and concepts are expressed differently. Convert with a tool, then validate and compare the content.
Sources
Last reviewed: 19 October 2026.
