SBOM field reference

This page says exactly how Bomly writes, reads, and converts each part of an SBOM. Read it when you integrate Bomly's SBOMs with another tool, or when a field does not look the way you expected. The how-to is on SBOM formats.

What both formats carry

How licenses are written

A license value can be an SPDX identifier, a compound expression, or free text. The formats keep these apart, and tools score them differently. Bomly therefore checks each value instead of guessing from its source:

When a source lists several licenses for one package, it says which licenses it found, not how they relate. Bomly does not fill that gap. CycloneDX lists them as separate entries, which asserts no relationship. SPDX 2.3 has one expression field and no way to list licenses without relating them, so Bomly joins them with AND. That overstates obligations rather than understating them. It is the one place the two formats differ on purpose.

When a source does state the relationship, it writes one expression (Apache-2.0 OR MIT is how registries record dual licensing), and both formats publish it as given. Bomly never rewrites an OR into an AND.

SPDX licenseConcluded is always NOASSERTION for packages Bomly resolved itself. "Concluded" means the license the document's author determined by examining the package. Bomly reports what a lockfile or registry declares and examines no contents, so it has nothing to conclude. An ingested document that concluded a license re-exports it as concluded.

Where a package came from

Each detector reports a package's origin from the field its own lockfile records it in. Bomly does not infer origin from the shape of a URL, because the same string means different things in different ecosystems. A detector reports one of two things, or nothing:

A pinned repository is written as the same string in both formats, git+<url>@<revision>. That is the version-control locator form SPDX 2.3 defines, and the form the package-URL vcs_url qualifier uses. CycloneDX has no field of its own for a revision, so the locator goes in the URL; a reader who sees git+ knows to parse a revision from it rather than open it. A repository with nothing to pin stays a plain URL in CycloneDX, because that is a location a reader can open.

What each ecosystem yields:

With --enrich and the scorecard matcher selected, a package can also get a source repository resolved from its identity by OpenSSF Scorecard. It is used whenever the detector reported no repository, including for packages that already have a download location: an artifact and a repository answer different questions, so a package can carry both. The artifact stays the SPDX downloadLocation and CycloneDX distribution reference; the repository becomes the vcs reference and, in SPDX, the source info. A Scorecard repository is a network lookup, not a lockfile claim, so it is weaker evidence and carries no revision.

Four kinds of value are never published:

• Registry and index roots (https://rubygems.org/, https://pub.dev, the crates.io index). They say where an ecosystem fetches from, not where a package came from, and a private server URL out of context looks like a repository.
• Local paths: workspace members, editable installs, file: and path: dependencies. These describe the machine that ran the scan.
• Non-web locations: ssh://, git@host:org/repo, and similar transport addresses.
• URLs with credentials. A private registry URL can embed a token.

Every published origin is an absolute http or https URL with a host, a non-empty path, and no credentials. Values are re-serialized from a parse rather than copied, and the same check runs again at export, so a plugin's origin is held to the same rule as a built-in detector's. Both formats then compose the validated repository URL into the git+<url>@<revision> locator when a revision is recorded; CycloneDX keeps the plain URL when none is.

Document identity

Every generated document carries:

• A serial number. A generated urn:uuid (CycloneDX serialNumber; the same value forms the SPDX document namespace, so the two exports of one scan can be correlated).
• The producing tool and version (CycloneDX metadata.tools[]; SPDX Creator: Tool: bomly-cli-<version>), plus one tool entry per detector that contributed.
• A project version on the primary component and the project's own modules: git describe --tags --always --dirty on the scanned checkout. When Git cannot describe it, the resolved commit is used, then the --ref value as typed. When none is available the version is omitted.
• A CycloneDX lifecycle phase (pre-build for source scans, post-build for images) and a composition completeness declaration: complete for unfiltered, warning-free scans, incomplete when --scope dropped part of the graph, unknown when resolution was degraded. SPDX 2.3 has no equivalent.
• A primary component for the scanned project. When the graph has one root, that root is the primary component. When a scan finds several manifests, Bomly synthesizes one named after the project with a pkg:generic PURL that depends on every root, so the exported graph is connected. The synthesized component is not repeated in the CycloneDX component list, and Bomly skips it when reading its own SBOMs.

Two cases change the serial number, and both apply only when the scan read SBOMs rather than lockfiles:

Source links are read back on import, so a merged document converted again still names the documents behind it. People and tools credited by any source are credited by the merged document.

What enrichment adds

With --enrich, components are enriched from the package registry, keyed by PURL:

Reachability results and other Bomly-specific data go to JSON output, not to the SBOM formats. See Output formats.

Strict ingest limits

Bomly refuses a document whose JSON has more than one reading (see What Bomly refuses to read). Checking for a repeated member name means remembering the names open in every object currently being read. Bomly refuses a document that would hold more than 100,000 open names or more than 16 MB of them. Neither format comes close: components live in an array, so only a handful of small objects are open at once, however many components the document lists.

Preservation and conversion limits

Bomly preserves component identity (including PURL), dependency edges, roots, scope, package type, licenses, digests, CPEs, and the enrichment fields above whenever the destination format can hold them. An ingested document also keeps supplier, originator, description, homepage, copyright, its own external references, and its own assertions. Encoding is deterministic when the scan timestamp and document identifiers are fixed.

Some data becomes less specific when it crosses formats:

See also

• SBOM formats — write, read, convert, and compare
• Output formats — the -o rules and JSON output
• SBOM detector — ingest specifics