In CycloneDX, externalReferences link a component to places outside the file. The most useful types to fill are vcs for the source repository, distribution for the download location, website, and license, then advisories, bom and build-meta where they exist. Each reference needs a url and a type, and the rest is optional.
What the schema offers
The 1.6 JSON reference lists many external reference types. A selection with the spec's descriptions follows.
| Type | Meaning |
|---|---|
| vcs | Version control system |
| issue-tracker | Issue, defect or lifecycle tracking system |
| website | Website |
| advisories | Security advisories |
| bom | A bill of materials such as SBOM, OBOM, HBOM or SaaSBOM |
| documentation | Guides and how-to instructions |
| support | Community or commercial support |
| source-distribution | Where the source distributable can be obtained, often an archive |
| distribution | Direct or repository download location |
| distribution-intake | Where a component was published to, which may be an intermediary |
| license | Reference to the license file |
| build-meta | Build system metadata file such as pom.xml, package.json or a nuspec |
| build-system | An automated build system |
| release-notes | Release notes |
Each entry has a required url, a required type, and an optional comment. Entries can also carry hashes.
A priority order
For an inventory used in security work, fill in this order.
- vcs, so a reviewer can find the source and its history.
- distribution, so someone can fetch exactly what you used.
- advisories, where the producer publishes security notices.
- license, when the license text lives at a stable URL. The spec says that if a license URL is set inside the license node, it should also be listed as an external reference for completeness.
- bom, when the component's own producer publishes an SBOM, which lets you link to it instead of copying it.
- build-meta and build-system for your own components.
Example
"externalReferences": [
{ "type": "vcs", "url": "https://git.example.org/project.git" },
{ "type": "distribution", "url": "https://registry.example.org/pkg/1.2.3.tgz" },
{ "type": "advisories", "url": "https://example.org/security" }
]
Mistakes
Pointing at a moving page. A URL to a repository's main branch is fine for vcs, but the distribution link should name the exact version.
Mixing up distribution and distribution-intake. Distribution is where to download. Distribution-intake is where it was published, which may be a staging or intermediary location.
Adding links that expose internals. Private repository URLs and internal build servers can reveal structure you may not want customers or the public to see. Review these before sharing an SBOM externally.
Treating the link as verified. A reference says where to look. It does not prove the content there matches what you shipped. Add a hash on the reference or on the component if integrity matters.
Safeguard can generate SBOMs and run dependency scanning across your repositories, so the fields discussed here are checked on real projects instead of by hand. You can try the free scan at gold.safeguard.sh/scan.
Quick check
Is externalReferences required?
No. It is optional, but vcs and distribution links make an SBOM much easier to verify.
Can I link a component's own SBOM?
Yes. The bom type exists for that, which avoids copying data you do not own.
Sources
Last reviewed: 19 October 2026.
