class CycloneDX::BOM

Overview

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).

Included Modules

Defined in:

cyclonedx/bom.cr

Constant Summary

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

Instance Method Summary

Constructor Detail

def self.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.


[View source]
def self.new(pull : JSON::PullParser) #

[View source]

Instance Method Detail

def annotations : Array(Annotation) | Nil #

[View source]
def bom_format : String #

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


[View source]
def bom_version : Int32 #

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


[View source]
def components : Array(Component) #

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.


[View source]
def compositions : Array(Composition) | Nil #

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


[View source]
def declarations : Declarations | Nil #

[View source]
def definitions : Definitions | Nil #

Definitions for standards (1.5+).


[View source]
def dependencies : Array(Dependency) | Nil #

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


[View source]
def external_references : Array(ExternalReference) | Nil #

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


[View source]
def formulation : Array(Formula) | Nil #

[View source]
def metadata : Metadata | Nil #

Metadata about the BOM.


[View source]
def properties : Array(Property) | Nil #

An array of CycloneDX::Property objects for extensibility.


[View source]
def raw_json : String #

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.


[View source]
def schema_url : String #

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.


[View source]
def serial_number : String #

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).


[View source]
def services : Array(Service) | Nil #

An array of CycloneDX::Service objects for SaaSBOM.


[View source]
def spec_version : String #

The CycloneDX specification version.


[View source]
def to_csv : String #

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.


[View source]
def 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.


[View source]
def to_xml : String #

Serializes the BOM to XML format.


[View source]
def vulnerabilities : Array(Vulnerability) | Nil #

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


[View source]