Project

svg_conform

0.0
The project is in a healthy, maintained state
svg_conformclaricle/svg_conformHomepageDocumentationSource CodeBug TrackerWiki
SVG profile conformance checker for Ruby.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
 Popularity
Downloads
2,682
Stars
3
Forks
1
Watchers
0
 Releases
Current version
0.1.6
Total releases
7
First release
2025-10-12
Latest release
2025-11-26
 Issues
Open Issues
0
Closed Issues
54
Total Issues
54
Issue Closure Rate
100%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
1
Merged Pull Requests
13
Pull Request Acceptance Rate
92%
 Development
Primary Language
HTML
Licenses
BSD-2-Clause
Average date of last 50 commits
2025-11-09
Reverse Dependencies
1

 Dependencies

Runtime

lutaml-model
~> 0.7
moxml
~> 0.1, >= 0.1.10
table_tennis
>= 0
thor
>= 0
 Project Readme

SvgConform: Ruby library for validating and fixing SVG files

Table of Contents
  • Purpose
  • Features
  • Concepts
    • General
    • SVG document
    • SVG profile
    • SVG requirement
    • SVG remediation action
    • Defining profiles with configuration
    • Two-mode architecture
    • Reporting
    • Compatibility with other tools
  • Usage
    • Installation
    • Command line usage
      • Quick start
    • Ruby API usage
      • Quick start
      • Accepting multiple input types
    • Reference manifest
  • External compliance
  • Documentation
    • User documentation
    • Developer documentation
  • Development
  • Contributing
  • License

Purpose

SvgConform is an SVG conformance processor that validates SVG documents against defined SVG profiles, and supports automatic remediation of profile requirement violations when possible.

SvgConform is designed to ensure SVG files meet specific requirements for different use cases, such as those required in:

  • Metanorma documents

  • PDF and PDF/A compliance

  • IETF XMLRFC documents (RFC 7996)

SvgConform is distributed as a Ruby gem.

Features

  • Profile-based validation: Validate SVG files against predefined or custom profiles

  • Remediation: Automatically fix common SVG conformance issues

  • Reference manifest: Complete tracking of IDs and references for consumer-level validation

  • Extensible architecture: Easy to add new rules and profiles

  • Command-line interface: Validate and fix files from the command line

  • Ruby API: Integrate validation into Ruby applications

  • Multiple report output formats: Text and JSON output formats

  • 100% SVGCheck compatibility: Perfect error report matching with Python svgcheck tool

  • Configurable RDF metadata support: Choose strict or permissive RDF/Dublin Core handling

  • Generic namespace handling: Configuration-driven foreign namespace validation

Concepts

General

SvgConform is built upon a set of core concepts that define its architecture and functionality.

SVG document

An SVG document is a file that contains Scalable Vector Graphics (SVG) content.

In SvgConform, an SVG document is represented by the SvgConform::Document class, which wraps the Moxml XML document and provides SVG-specific functionality.

SVG profile

An SVG profile is a defined set of requirements that an SVG document must meet.

These requirements represent concerns that go beyond the SVG standards, such as accessibility or stylistic concerns.

In SvgConform, a Profile object is a collection of requirements and remediations that define a specific SVG conformance standard.

Each Profile object consists of:

  • Requirement objects: Validation checks that determine if an SVG document conforms to the profile

  • Remediation objects: Automatic fixes that can be applied when requirements fail

  • Configuration objects: Profile-specific settings and parameters

Conformance to an SVG profile is a measure of the degree to which an SVG document meets the requirements of a specific profile.

In SvgConform, SVG conformance is determined by whether an SVG document passes all the requirements defined in the profile.

SVG requirement

An SVG requirement is a specific condition or set of conditions that an SVG document must meet.

In SvgConform, a Requirement object encapsulates the logic to check for a specific requirement.

Each Requirement object is designed to be modular and focuses on a single concern, such as color usage, font family restrictions, or structural validity.

SVG remediation action

An SVG remediation action is an automatic fix or adjustment applied to an SVG document to resolve one or more SVG requirement failures.

A remediation action may imply a lossless or lossy change.

In SvgConform, a Remediation object encapsulates the logic to perform a specific remediation action.

Each Remediation object targets one or more specific requirements through a mapping system.

Defining profiles with configuration

Requirements and remediations can be configured with specific parameters to customize their behavior.

In SvgConform, Requirement and Remediation objects are customizable executable components that can be tailored to specific use cases.

These parameters can be set in the profile YAML configuration to influence how requirements and remediations operate.

In combination, it allows for flexible definition and authoring of new deterministic SVG profiles, with the ability to enforce specific requirements and remediation strategies.

Each remediation action can be linked to a particular requirement to indicate their relationship, defined in the profile.

Two-mode architecture

SvgConform uses two distinct operating modes for optimal performance and functionality:

SAX Validation Mode (always used for validation):

  • Memory-safe streaming XML parser

  • Constant memory usage regardless of file size

  • Handles files of any size (tested with 100MB+ files)

  • Read-only - cannot modify documents

DOM Remediation Mode (only when applying fixes):

  • Full document tree loaded in memory

  • XPath queries and tree modification

  • Memory scales with file size

  • Only used when fix: true option is specified

This architecture ensures validation is always safe for large files, while modifications are only performed when explicitly requested and necessary.

See SAX Validation Mode Guide for details on writing SAX-compatible requirements.

Reporting

SvgConform provides detailed reporting on SVG conformance issues.

  • Validation results: Summary of passed and failed checks

  • Report formats: The resulting validation report can be exported in machine-readable formats, including JSON and YAML

  • Error messages: Descriptions of specific conformance issues

Compatibility with other tools

SvgConform aims to deliver accurate results for compatibility with existing SVG profile conformance tools.

See External compliance for details.

Usage

Installation

Add this line to your application’s Gemfile:

gem 'svg_conform'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install svg_conform

Command line usage

Details and examples of command line usage can be found in CLI Guide.

Quick start

List available profiles:

$ svg_conform profiles

Check/validate an SVG file against a profile:

$ svg_conform check file.svg --profile=metanorma

Check and fix an SVG file to conform to a profile:

$ svg_conform check file.svg --profile=metanorma -f --fix-output=fixed.svg

Batch process a directory of SVG files:

$ svg_conform check --directory=images/ --profile=metanorma -f --output-dir=fixed/

For comprehensive CLI documentation including all options, workflows, and troubleshooting, see CLI Guide.

Ruby API usage

Details and examples of Ruby API usage can be found in API Reference.

Quick start

require 'svg_conform'

# Load a profile and validate
profile = SvgConform::Profiles.get(:svg_1_2_rfc)
document = SvgConform::Document.new(svg_content)
result = profile.validate(document)

puts "Valid: #{result.valid?}"
puts "Errors: #{result.errors.count}"
puts "Warnings: #{result.warnings.count}"

# Apply remediations to fix issues
if !result.valid? && profile.remediation_count > 0
  changes = profile.apply_remediations(document)

  puts "Applied #{changes.length} remediations"
  puts "Fixed SVG:"
  puts document.to_xml
end

Accepting multiple input types

The validator accepts multiple input types and always uses SAX validation for memory-safe processing:

validator = SvgConform::Validator.new

# String input: Direct SAX parsing
result = validator.validate(svg_string, profile: :metanorma)

# Moxml documents/elements: Serialize once, then SAX validate
moxml_doc = Moxml.new.parse(svg_string)
result = validator.validate(moxml_doc, profile: :metanorma)

moxml_element = moxml_doc.root
result = validator.validate(moxml_element, profile: :metanorma)

# Nokogiri documents/elements: Serialize once, then SAX validate
nokogiri_doc = Nokogiri::XML(svg_string)
result = validator.validate(nokogiri_doc, profile: :metanorma)

nokogiri_element = nokogiri_doc.root  # Common in metanorma integration
result = validator.validate(nokogiri_element, profile: :metanorma)

Why SAX validation for all inputs?

SAX (Simple API for XML) parsing is memory-safe and can handle arbitrarily large SVG files without hanging. DOM-based validation loads the entire tree into memory, which can cause performance issues or crashes with large files.

Benefits of accepting DOM objects:

When integrating with tools like Metanorma where SVG elements are already parsed:

# ❌ Old way: User manually serializes
result = validator.validate(svg_element.to_xml, profile: :metanorma)

# ✅ New way: Library handles serialization internally
result = validator.validate(svg_element, profile: :metanorma)

Benefits: - Cleaner API: No need to call .to_xml explicitly - Type flexibility: Works with Nokogiri, Moxml, or strings - Safe for large files: Always uses memory-efficient SAX parsing - Backward compatible: String input still works as before

For comprehensive API documentation including all classes, methods, advanced usage, and integration patterns, see API Reference.

Reference manifest

SvgConform provides comprehensive ID and reference tracking through its reference manifest system:

result = validator.validate(svg_content, profile: :metanorma)

# Access the reference manifest
manifest = result.reference_manifest

# Get all defined IDs
manifest.available_ids.each do |id_def|
  puts "ID: #{id_def.id_value} at line #{id_def.line_number}"
end

# Check for unresolved internal references
if result.has_unresolved_references?
  result.unresolved_internal_references.each do |ref|
    puts "Unresolved reference: #{ref.value} at line #{ref.line_number}"
  end
end

# Check for external references
if result.has_external_references?
  result.external_references.each do |ref|
    puts "External reference: #{ref.value}"
  end
end

See Reference Manifest Documentation for complete details.

External compliance

SvgConform provides compatibility with existing SVG validation tools:

  • SVGCheck: 100% error report matching with Python svgcheck tool

  • Profile compatibility modes for different validation tools

See Compatibility Documentation for details.

Documentation

User documentation

Developer documentation

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/metanorma/svg_conform.

License

The gem is available as open source under the terms of the BSD 2-Clause License.