✨ --validate

# CLI and validation

- Added --validate and --validate-file flags in Cyclonedx::BomBuilder.
- After writing the BOM, if --validate is set, validate JSON via JSON Schema and XML via XSD with local files under spec/specification-1.7/schema.
- Added logic to validate an existing file with --validate --validate-file <path>, inferring format from extension unless --format is provided.</path>
- In validate-only mode, project path isn’t required.

# Validation helpers

- Added Cyclonedx::BomHelpers.validate_bom_content(content, format, spec_version) which:
  - For JSON: uses json_schemer to validate against bom-<ver>.schema.json.</ver>
  - For XML: uses Nokogiri::XML::Schema with bom-<ver>.xsd.</ver>
- Uses local schemas at spec/specification-1.7/schema and surfaces compact error messages; returns non-zero exit on failure.

# Dependencies

- Added json_schemer (~> 2.2) to cyclonedx-ruby.gemspec.
- Required json_schemer in lib/cyclonedx/ruby.rb.

# Cucumber tests

- Updated features/help.feature to show the new flags.
- Added features/validate.feature:
  - Validate XML BOM succeeds.
  - Validate JSON BOM succeeds.
  - Validate fails for invalid XML BOM (corrupts namespace and expects exit 1).

# Small extras

- Infer format from file extension when using --validate-file and no --format provided.

Signed-off-by: Peter H. Boling <[email protected]>

Author: pboling

Gemfile.lock

@@ -4,6 +4,7 @@ PATH
     cyclonedx-ruby (1.2.0)
       activesupport (~> 7.0)
       json (~> 2.6)
+      json_schemer (~> 2.2)
       nokogiri (~> 1.15)
       ostruct (~> 0.5.5)
       rest-client (~> 2.0)
@@ -75,12 +76,18 @@ GEM
     ffi (1.17.2-x86_64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     ffi (1.17.2-x86_64-linux-musl)
+    hana (1.3.7)
     http-accept (1.7.0)
     http-cookie (1.1.0)
       domain_name (~> 0.5)
     i18n (1.14.7)
       concurrent-ruby (~> 1.0)
     json (2.15.2)
+    json_schemer (2.4.0)
+      bigdecimal
+      hana (~> 1.3)
+      regexp_parser (~> 2.0)
+      simpleidn (~> 0.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -90,13 +97,9 @@ GEM
       mime-types-data (~> 3.2025, >= 3.2025.0507)
     mime-types-data (3.2025.0924)
     mini_mime (1.1.5)
-    mini_portile2 (2.8.9)
     minitest (5.26.0)
     multi_test (1.1.0)
     netrc (0.11.0)
-    nokogiri (1.18.10)
-      mini_portile2 (~> 2.8.2)
-      racc (~> 1.4)
     nokogiri (1.18.10-aarch64-linux-gnu)
       racc (~> 1.4)
     nokogiri (1.18.10-aarch64-linux-musl)
@@ -163,6 +166,7 @@ GEM
       simplecov_json_formatter (~> 0.1)
     simplecov-html (0.13.2)
     simplecov_json_formatter (0.1.4)
+    simpleidn (0.2.3)
     sys-uname (1.4.1)
       ffi (~> 1.1)
       memoist3 (~> 1.0.0)
@@ -179,7 +183,6 @@ PLATFORMS
   arm-linux-gnu
   arm-linux-musl
   arm64-darwin
-  ruby
   x86_64-darwin
   x86_64-linux-gnu
   x86_64-linux-musl

cucumber.yml

@@ -1 +1,2 @@
-default: --publish-quiet
+default: --publish-quiet --format progress features
+

cyclonedx-ruby.gemspec

@@ -64,6 +64,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency('ostruct', '~> 0.5.5')
   spec.add_dependency('rest-client', '~> 2.0')
   spec.add_dependency('activesupport', '~> 7.0')
+  spec.add_dependency('json_schemer', '~> 2.2')
   spec.add_development_dependency 'rake', '~> 13'
   spec.add_development_dependency 'rspec', '~> 3.12'
   spec.add_development_dependency 'cucumber', '~> 10.1', '>= 10.1.1'

exe/cyclonedx-ruby

@@ -3,8 +3,12 @@
 
 if ENV.fetch("MIMIC_NEXT_MAJOR_VERSION", "false").casecmp?("true")
   require 'cyclonedx/ruby'
-  Cyclonedx::BomBuilder.build(ARGV[0])
+  path_arg = ARGV[0]
+  path_arg = nil if path_arg&.start_with?('-')
+  Cyclonedx::BomBuilder.build(path_arg)
 else
   require 'bom_builder'
-  Bombuilder.build(ARGV[0])
+  path_arg = ARGV[0]
+  path_arg = nil if path_arg&.start_with?('-')
+  Bombuilder.build(path_arg)
 end

features/help.feature

@@ -13,5 +13,7 @@ Scenario: Generate help on demand
       -o, --output bom_file_path       (Optional) Path to output the bom.xml file to
       -f, --format bom_output_format   (Optional) Output format for bom. Currently support xml (default) and json.
       -s, --spec-version version       (Optional) CycloneDX spec version to target (default: 1.7). Supported: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
+          --validate                   Validate the produced BOM against the selected CycloneDX schema
+          --validate-file PATH         Validate an existing BOM file instead of generating one
       -h, --help                       Show help message
   """

features/validate.feature

@@ -0,0 +1,47 @@
+Feature: Validate generated BOM against CycloneDX schema
+
+  Scenario: Validate XML BOM succeeds
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format xml --validate`
+    Then the output should contain:
+    """
+    5 gems were written to BOM located at ./bom.xml
+    """
+    And a file named "bom.xml" should exist
+
+  Scenario: Validate JSON BOM succeeds
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format json --validate`
+    Then the output should contain:
+    """
+    5 gems were written to BOM located at ./bom.json
+    """
+    And a file named "bom.json" should exist
+
+  Scenario: Validate fails for invalid XML BOM
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format xml`
+    Then a file named "bom.xml" should exist
+    When I run `sh -lc "sed -i 's|http://cyclonedx.org/schema/bom/1.7|http://cyclonedx.org/schema/bom/9.9|' bom.xml"`
+    And I run `cyclonedx-ruby --validate --validate-file bom.xml --spec-version 1.7`
+    Then the exit status should be 1
+
+  Scenario: Validate existing XML BOM succeeds
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format xml`
+    Then a file named "bom.xml" should exist
+    When I run `cyclonedx-ruby --validate --validate-file bom.xml --spec-version 1.7`
+    Then the output should contain:
+    """
+    Validation succeeded for bom.xml (spec 1.7)
+    """
+
+  Scenario: Validate existing JSON BOM succeeds
+    Given I use a fixture named "simple"
+    And I run `cyclonedx-ruby --path . --format json`
+    Then a file named "bom.json" should exist
+    When I run `cyclonedx-ruby --validate --validate-file bom.json --spec-version 1.7`
+    Then the output should contain:
+    """
+    Validation succeeded for bom.json (spec 1.7)
+    """

lib/cyclonedx/bom_builder.rb

@@ -8,6 +8,26 @@ class BomBuilder
     def self.build(path)
       original_working_directory = Dir.pwd
       setup(path)
+
+      # If asked to validate an existing file, do not generate a new one
+      if @options[:validate] && @options[:validate_file]
+        content = begin
+          File.read(@options[:validate_file])
+        rescue StandardError => e
+          @logger.error("Unable to read file for validation: #{@options[:validate_file]}. #{e.message}")
+          exit(1)
+        end
+        # Use explicitly provided format if set, otherwise infer from file extension
+        format = @options[:bom_output_format] || infer_format_from_path(@options[:validate_file])
+        success, message = validate_bom_content(content, format, @spec_version)
+        unless success
+          @logger.error(message)
+          exit(1)
+        end
+        puts "Validation succeeded for #{@options[:validate_file]} (spec #{@spec_version})" unless @options[:verbose]
+        return
+      end
+
       specs_list
       bom = build_bom(@gems, @bom_output_format, @spec_version)
 
@@ -40,7 +60,22 @@ def self.build(path)
         @logger.error("Unable to write BOM to #{@bom_file_path}. #{e.message}: #{Array(e.backtrace).join("\n")}")
         abort
       end
+
+      if @options[:validate]
+        success, message = validate_bom_content(bom, @bom_output_format, @spec_version)
+        unless success
+          @logger.error(message)
+          exit(1)
+        end
+        @logger.info("BOM validation succeeded for spec #{@spec_version}") if @options[:verbose]
+      end
+    end
+
+    # Infer format from file extension when not explicitly provided
+    def self.infer_format_from_path(path)
+      File.extname(path).downcase == '.json' ? 'json' : 'xml'
     end
+
     private
     def self.setup(path)
       @options = {}
@@ -62,6 +97,12 @@ def self.setup(path)
         opts.on('-s', '--spec-version version', '(Optional) CycloneDX spec version to target (default: 1.7). Supported: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7') do |spec_version|
           @options[:spec_version] = spec_version
         end
+        opts.on('--validate', 'Validate the produced BOM against the selected CycloneDX schema') do
+          @options[:validate] = true
+        end
+        opts.on('--validate-file PATH', 'Validate an existing BOM file instead of generating one') do |path|
+          @options[:validate_file] = path
+        end
         opts.on_tail('-h', '--help', 'Show help message') do
           puts opts
           exit
@@ -84,26 +125,31 @@ def self.setup(path)
       licenses_file = File.read(licenses_path)
       @licenses_list = JSON.parse(licenses_file)
 
-      if @options[:path].nil?
-        @logger.error('missing path to project directory')
-        abort
-      end
+      # If only validating a file, project path is optional; otherwise require
+      if @options[:validate_file].nil? || !@options[:validate]
+        if @options[:path].nil?
+          @logger.error('missing path to project directory')
+          abort
+        end
 
-      unless File.directory?(@options[:path])
-        @logger.error("path provided is not a valid directory. path provided was: #{@options[:path]}")
-        abort
+        unless File.directory?(@options[:path])
+          @logger.error("path provided is not a valid directory. path provided was: #{@options[:path]}")
+          abort
+        end
       end
 
       # Normalize to an absolute project path to avoid relative path issues later
-      @project_path = File.expand_path(@options[:path])
+      @project_path = File.expand_path(@options[:path]) if @options[:path]
       @provided_path = @options[:path]
 
-      begin
-        @logger.info("Changing directory to Ruby project directory located at #{@provided_path}")
-        Dir.chdir @project_path
-      rescue StandardError => e
-        @logger.error("Unable to change directory to Ruby project directory located at #{@provided_path}. #{e.message}: #{Array(e.backtrace).join("\n")}")
-        abort
+      if @project_path
+        begin
+          @logger.info("Changing directory to Ruby project directory located at #{@provided_path}")
+          Dir.chdir @project_path
+        rescue StandardError => e
+          @logger.error("Unable to change directory to Ruby project directory located at #{@provided_path}. #{e.message}: #{Array(e.backtrace).join("\n")}")
+          abort
+        end
       end
 
       if @options[:bom_output_format].nil?
@@ -130,20 +176,22 @@ def self.setup(path)
                          @options[:bom_file_path]
                        end
 
-      @logger.info("BOM will be written to #{@bom_file_path}")
-
-      begin
-        # Use absolute path so it's correct regardless of current working directory
-        gemfile_path = File.join(@project_path, 'Gemfile.lock')
-        # Compute display path for logs: './Gemfile.lock' when provided path is '.', else '<provided>/Gemfile.lock'
-        display_gemfile_path = (@provided_path == '.' ? './Gemfile.lock' : File.join(@provided_path, 'Gemfile.lock'))
-        @logger.info("Parsing specs from #{display_gemfile_path}...")
-        gemfile_contents = File.read(gemfile_path)
-        @specs = Bundler::LockfileParser.new(gemfile_contents).specs
-        @logger.info('Specs successfully parsed!')
-      rescue StandardError => e
-        @logger.error("Unable to parse specs from #{gemfile_path}. #{e.message}: #{Array(e.backtrace).join("\n")}")
-        abort
+      @logger.info("BOM will be written to #{@bom_file_path}") if @project_path
+
+      if @project_path
+        begin
+          # Use absolute path so it's correct regardless of current working directory
+          gemfile_path = File.join(@project_path, 'Gemfile.lock')
+          # Compute display path for logs: './Gemfile.lock' when provided path is '.', else '<provided>/Gemfile.lock'
+          display_gemfile_path = (@provided_path == '.' ? './Gemfile.lock' : File.join(@provided_path, 'Gemfile.lock'))
+          @logger.info("Parsing specs from #{display_gemfile_path}...")
+          gemfile_contents = File.read(gemfile_path)
+          @specs = Bundler::LockfileParser.new(gemfile_contents).specs
+          @logger.info('Specs successfully parsed!')
+        rescue StandardError => e
+          @logger.error("Unable to parse specs from #{gemfile_path}. #{e.message}: #{Array(e.backtrace).join("\n")}")
+          abort
+        end
       end
     end
 

lib/cyclonedx/bom_helpers.rb

@@ -104,6 +104,62 @@ def build_bom_xml(gems, spec_version)
       builder.to_xml
     end
 
+    # Validate content against the selected CycloneDX schema (local files, offline)
+    # Returns [true, nil] on success; [false, "message"] on failure
+    def validate_bom_content(content, format, spec_version)
+      schema_dir = File.expand_path("../../schema", __dir__)
+      case format
+      when 'json'
+        schema_path = File.join(schema_dir, "bom-#{spec_version}.schema.json")
+        begin
+          schema = JSON.parse(File.read(schema_path))
+          resolver = lambda do |uri|
+            begin
+              u = uri.is_a?(URI) ? uri : URI.parse(uri.to_s)
+              basename = File.basename(u.path.to_s)
+              local_path = File.join(schema_dir, basename)
+              return JSON.parse(File.read(local_path)) if File.exist?(local_path)
+            rescue StandardError
+              # fall through to unknown ref handling in schemer
+            end
+            nil
+          end
+          schemer = JSONSchemer.schema(schema, ref_resolver: resolver)
+          data = JSON.parse(content)
+          errors = schemer.validate(data).to_a
+          return [true, nil] if errors.empty?
+          # Build a compact error message
+          msgs = errors.first(5).map do |e|
+            path = Array(e['data_pointer']).join
+            "#{e['type']}: #{e['message']} at #{path}"
+          end
+          [false, "JSON schema validation failed (#{errors.size} errors). First: #{msgs.join('; ')}"]
+        rescue Errno::ENOENT
+          [false, "JSON schema not found at #{schema_path}"]
+        rescue StandardError => e
+          [false, "JSON schema validation error: #{e.class}: #{e.message}"]
+        end
+      else
+        schema_path = File.join(schema_dir, "bom-#{spec_version}.xsd")
+        begin
+          # Use local XML catalog to resolve imports like http://cyclonedx.org/schema/spdx
+          previous_catalog = ENV['XML_CATALOG_FILES']
+          ENV['XML_CATALOG_FILES'] = File.join(schema_dir, 'xmlcatalog.xml')
+          xsd = Nokogiri::XML::Schema(File.read(schema_path))
+          doc = Nokogiri::XML(content) { |cfg| cfg.nonet }
+          errors = xsd.validate(doc)
+          return [true, nil] if errors.empty?
+          [false, "XML schema validation failed: #{errors.first.message}"]
+        rescue Errno::ENOENT
+          [false, "XML schema not found at #{schema_path}"]
+        rescue StandardError => e
+          [false, "XML schema validation error: #{e.class}: #{e.message}"]
+        ensure
+          ENV['XML_CATALOG_FILES'] = previous_catalog
+        end
+      end
+    end
+
     def get_gem(name, version)
       url = "https://rubygems.org/api/v1/versions/#{name}.json"
       begin

lib/cyclonedx/ruby.rb

@@ -11,6 +11,7 @@
 require 'rest_client'
 require 'securerandom'
 require 'active_support/core_ext/hash'
+require 'json_schemer'
 
 # This gem
 require_relative "ruby/version"