class

CycloneDX::BOM

Inherits JSON::Serializable / Reference / Object

Represents a CycloneDX Bill of Materials (BOM). This class manages a collection of components and provides methods for serializing the BOM into different formats (JSON, XML, CSV).

Constants

BOM_FORMAT = "CycloneDX"
BOM_VERSION = 1
CSV_FORMULA_PREFIXES = {'=', '+', '-', '@'}

Characters that make a spreadsheet treat a cell as a formula rather than as text. Excel, LibreOffice and Google Sheets all evaluate such cells on open.

JSON_SCHEMA = "http://cyclonedx.org/schema/bom"
SUPPORTED_VERSIONS = ["1.4", "1.5", "1.6", "1.7"]
XML_NAMESPACE = "http://cyclonedx.org/schema/bom"

Constructors

new(components : Array(Component), spec_version : String, metadata : Metadata | Nil = nil, dependencies : Array(Dependency) | Nil = nil, properties : Array(Property) | Nil = nil, vulnerabilities : Array(Vulnerability) | Nil = nil, services : Array(Service) | Nil = nil, compositions : Array(Composition) | Nil = nil, annotations : Array(Annotation) | Nil = nil, formulation : Array(Formula) | Nil = nil, declarations : Declarations | Nil = nil, external_references : Array(ExternalReference) | Nil = nil, definitions : Definitions | Nil = nil, serial_number : String | Nil = nil)

Initializes a new CycloneDX BOM.

Source
new(pull : JSON::PullParser)
Source
new(*, __pull_for_json_serializable pull : JSON::PullParser)
Source

Instance methods

annotations
Source
bom_format

Specifies the format of the BOM (always "CycloneDX" for JSON serialization).

Source
bom_version

The version of the BOM itself (not the spec version), typically 1.

Source
components

An array of CycloneDX::Component objects included in the BOM.

components is optional in every CycloneDX version, so it defaults to empty rather than being required on parse — a BOM that inventories only services, or that carries nothing but vulnerabilities, legitimately omits it.

Source
compositions

An array of CycloneDX::Composition objects for completeness assertions.

Source
declarations
Source
definitions

Definitions for standards (1.5+).

Source
dependencies

An array of CycloneDX::Dependency objects describing component relationships.

Source
external_references

An array of CycloneDX::ExternalReference objects for the BOM itself.

Source
formulation
Source
metadata

Metadata about the BOM.

Source
properties

An array of CycloneDX::Property objects for extensibility.

Source
raw_json

The document as JSON::Serializable produces it, before spec-version gating.

Validator diffs this against the gated document to find fields that are newer than the declared specVersion, so the rules for what gets stripped live only in VersionGate and cannot drift out of sync with the validator. The two documents therefore differ in exactly the places the gate edited.

Source
schema_url

The $schema value for the declared spec version. The 1.4 and 1.5 JSON schemas constrain this key to one exact URL, so it is always derived rather than caller-supplied. XML carries the same information in xmlns.

Source
serial_number

The unique serial number of the BOM. Randomly generated unless the caller supplies one; a caller-supplied value is what makes byte-reproducible output possible (see the CLI's --reproducible).

Source
services

An array of CycloneDX::Service objects for SaaSBOM.

Source
spec_version

The CycloneDX specification version.

Source
to_csv

Serializes the BOM to CSV format.

The root component lives in metadata.component (not in components), so it is emitted as the first row to keep the CSV consistent with the JSON/XML output, which both represent the root component.

Scope and BOM-Ref are appended after the original four columns so a consumer reading by column index is unaffected.

Source
to_json(json : JSON::Builder) : Nil

Serializes the BOM to JSON.

The object model may carry fields newer than the declared specVersion (e.g. a 1.4 BOM that was handed lifecycles). To keep the output schema-valid, the raw serialization is filtered through VersionGate, which strips or downgrades anything newer than @spec_version.

This overrides the JSON::Serializable implementation rather than wrapping only the no-arg to_json, because every other JSON entry point in stdlib (to_pretty_json, to_json(IO), and serialization as part of a larger document) funnels through this method. Gating only the no-arg form left all of those emitting ungated output.

Source
to_xml

Serializes the BOM to XML format.

Source
vulnerabilities

An array of CycloneDX::Vulnerability objects for VDR/VEX.

Source