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
- Reporting
- Compatibility with other tools
Usage
- Installation
- Command line usage
- Ruby API usage
Core components
- Architecture
- Profiles
- Requirements
- Remediations
- Requirement and remediation mapping
- Validation and remediation flow
- Classes
  - Document (SvgConform::Document)
  - Validator (SvgConform::Validator)
  - Profile (SvgConform::Profile)
  - Requirements
  - Remediations
Command line interface
- General
- svg_conform profiles
- svg_conform check
- svg_conform version
Ruby API
- Basic usage
- Advanced usage
- Working with loaded SVG content
Configuration
- Profile configuration
- Requirement configuration
- Remediation configuration
Extending SvgConform
- Custom profiles
External compliance
- General
- svgcheck
- svgcheck testing workflow
- svgcheck compatibility architecture
- svgcheck compatibility commands
  - General
  - svg_conform svgcheck compatibility
  - svg_conform svgcheck generate
  - svg_conform svgcheck compare
Testing
Changelog
Copyright and 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
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.

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 Command line interface.

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/

Ruby API usage

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

require 'svg_conform'

# Load a profile and validate
profile = SvgConform::Profile.load_from_file("config/profiles/svg_1_2_rfc.yml")
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.has_remediations?
  engine = SvgConform::RemediationEngine.new(profile)
  remediation_results = engine.apply_remediations(document, result)

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

Core components

Architecture

The SvgConform architecture is built around a modular design that separates concerns and allows for easy extension.

╭────────────────────────────────────────────────────────────────╮
│                        SvgConform                              │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ╭─────────────╮    ╭─────────────╮    ╭─────────────╮         │
│  │     CLI     │    │  Ruby API   │    │   Profiles  │         │
│  │             │    │             │    │   Registry  │         │
│  ╰─────┬───────╯    ╰──────┬──────╯    ╰─────┬───────╯         │
│        │                   │                 │                 │
│        └───────────────────┼─────────────────┘                 │
│                            │                                   │
│  ╭─────────────────────────▼─────────────────────────╮         │
│  │                     Validator                     │         │
│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
│  │ │  Document   │  │ Validation  │  │ Remediation │ │         │
│  │ │   Parser    │  │   Engine    │  │   Engine    │ │         │
│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
│  ╰─────────────────────────┬─────────────────────────╯         │
│                            │                                   │
│  ╭─────────────────────────▼─────────────────────────╮         │
│  │                  Profile System                   │         │
│  │                                                   │         │
│  │ ╭─────────────╮ ╭─────────────╮ ╭─────────────╮   │         │
│  │ │ SVG 1.2 RFC │ │ Metanorma   │ │   Future    │   │         │
│  │ │   Profile   │ │ SVG Profile │ │  Profiles   │   │         │
│  │ │             │ │             │ │             │   │         │
│  │ │ • svgcheck  │ │ • ID links  │ │ • Custom    │   │         │
│  │ │ compatible  │ │ • No ext.   │ │   rules     │   │         │
│  │ │ • Grayscale │ │   fonts     │ │ • Org       │   │         │
│  │ │ • RFC 7996  │ │ • Font def. │ │   standards │   │         │
│  │ ╰─────────────╯ ╰─────────────╯ ╰─────────────╯   │         │
│  ╰─────────────────────────┬─────────────────────────╯         │
│                            │                                   │
│  ╭─────────────────────────▼─────────────────────────╮         │
│  │        Requirements & Remediations Engine         │         │
│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
│  │ │Requirements │  │Remediations │  │ Validation  │ │         │
│  │ │   System    │  │   System    │  │   Results   │ │         │
│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
│  ╰─────────────────────────┬─────────────────────────╯         │
│                            │                                   │
│  ╭─────────────────────────▼─────────────────────────╮         │
│  │             svgcheck Compatibility                │         │
│  │ ╭─────────────╮  ╭─────────────╮  ╭─────────────╮ │         │
│  │ │ svgcheck    │  │    YAML     │  │   Report    │ │         │
│  │ │   Parser    │  │   Mapping   │  │ Comparator  │ │         │
│  │ ╰─────────────╯  ╰─────────────╯  ╰─────────────╯ │         │
│  ╰─────────────────────────┬─────────────────────────╯         │
│                            │                                   │
│  ╭─────────────────────────▼─────────────────────────╮         │
│  │                       Moxml                       │         │
│  │                  (XML Processing)                 │         │
│  ╰───────────────────────────────────────────────────╯         │
│                                                                │
╰────────────────────────────────────────────────────────────────╯

Profiles

SvgConform includes predefined profiles that can be used out-of-the-box. Each profile is designed for different use cases and compliance standards.

Table 1. Predefined SVG profiles included in SvgConform

Profile	Use Case	Key Features	Documentation
`base`	Foundation profile	Basic validation, namespace checks, starting point for custom profiles.	Details
`metanorma`	Metanorma SVG profile	Standard SVG for Metanorma documents. Valid HREFs and ID linking. No external fonts, images and CSS. No non-SVG elements or attributes.	Details
`svg_1_2_rfc`	IETF RFC SVG 1.2 profile	RFC 7996/6949 compliant. Black/white color only, limited elements, generic fonts. Fully compatible with `svgcheck` outcomes.	Details
`svg_1_2_rfc_with_rdf`	IETF RFC SVG 1.2 profile with RDF metadata	Same as `svg_1_2_rfc`, but allows RDF/Dublin Core metadata from design tools. Supported by `svgcheck`.	Details
`no_external_css`	Self-contained SVG	No external references, security-focused, offline usage.	Details
`lucid_fix`	Lucid cleanup	Remove Lucid-specific metadata, clean standard SVG output	Details

For complete profile documentation, including inheritance, customization, RDF metadata support, and selection guides, see SVG Profiles Documentation.

For detailed information about configuring RDF metadata support in profiles, see RDF Metadata Support Documentation.

Requirements

SvgConform includes different requirement checkers that validate various aspects of SVG documents.

There are two main categories of requirements:

structural requirements: requirements set towards the XML structure and syntax of SVG documents
logical requirements: requirements set towards content and stylistic aspects of SVG documents

Table 2. SvgConform supported requirement classes

Type	Requirement	Description
Structural	`NamespaceRequirement`	Ensures proper SVG namespace declarations
Structural	`NamespaceAttributesRequirement`	Validates namespace attributes are from allowed namespaces
Structural	`AllowedElementsRequirement`	Restricts which SVG elements are permitted
Structural	`ViewboxRequiredRequirement`	Requires viewBox attributes on root elements
Logical	`ColorRestrictionsRequirement`	Enforces color usage restrictions (e.g., grayscale only)
Logical	`FontFamilyRequirement`	Controls font family usage and validates font specifications
Logical	`NoExternalCssRequirement`	Prevents external CSS references to ensure self-contained documents
Logical	`NoExternalFontsRequirement`	Validates that no external font references are present
Logical	`NoExternalImagesRequirement`	Validates that no external image references are present
Logical	`ForbiddenContentRequirement`	Prevents inclusion of forbidden elements and attributes
Logical	`IdReferenceRequirement`	Validates that ID references point to existing elements
Logical	`InvalidIdReferencesRequirement`	Detects and validates broken ID references in SVG documents
Logical	`LinkValidationRequirement`	Validates that links use only ASCII characters (IETF requirement)
Logical	`StyleRequirement`	Comprehensive CSS style validation including syntax and properties
Logical	`StylePromotionRequirement`	Detects style properties that should be promoted to SVG attributes

Remediations

Remediations are automatic fixing actions that can resolve requirement failures. Each remediation targets one or more specific requirements.

SvgConform includes different remediation actions that can automatically fix SVG documents to resolve requirement violations.

Table 3. SvgConform supported remediation classes

Type	Remediation	Description	Targets
Content Conversion	`ColorRemediation`	Converts invalid colors to allowed alternatives using threshold-based conversion	`ColorRestrictionsRequirement`
Content Conversion	`FontRemediation`	Maps font families to generic alternatives (serif, sans-serif, monospace)	`FontFamilyRequirement`
Content Conversion	`FontEmbeddingRemediation`	Converts external font references to embedded data URIs	`NoExternalFontsRequirement`
Content Conversion	`ImageEmbeddingRemediation`	Converts external image references to embedded data URIs	`NoExternalImagesRequirement`
Element/Attribute Removal	`NamespaceRemediation`	Removes invalid namespace elements and cleans up namespace declarations	`NamespaceRequirement`
Element/Attribute Removal	`NamespaceAttributeRemediation`	Removes attributes from disallowed namespaces	`NamespaceAttributesRequirement`
Element/Attribute Removal	`NoExternalCssRemediation`	Removes external CSS references including @import and external stylesheets	`NoExternalCssRequirement`
Addition	`ViewboxRemediation`	Adds missing viewBox attributes to root SVG elements	`ViewboxRequiredRequirement`
Style Processing	`StylePromotionRemediation`	Promotes CSS style properties to equivalent SVG attributes	`StylePromotionRequirement`
Reference Fixing	`InvalidIdReferencesRemediation`	Fixes or removes broken ID references and invalid href attributes	`IdReferenceRequirement`, `InvalidIdReferencesRequirement`

Requirement and remediation mapping

Remediations are mapped to requirements using the targets configuration in profile YAML files.

remediations:
  - id: "fix_invalid_colors"
    type: "ColorRemediationAction"
    description: "Convert invalid colors to black or white"
    targets: ["color_restrictions"]  # Maps to ColorRestrictionsRequirement

This mapping system allows:

Targeted fixes: Remediations only run when their target requirements fail
Flexible configuration: Multiple remediations can target the same requirement
Conditional application: Remediations can be enabled/disabled per profile

Validation and remediation flow

The following steps illustrates the data flow through the core components of SvgConform.

An SVG file is read and parsed into a Document object.
The Document is validated against a Profile using the Validator.
The Validator applies Requirements and collects results in a ConformanceReport object.
If fixing is enabled, the Validator uses the RemediationEngine to apply Remediations.
The fixed Document is returned along with the validation results in the ConformanceReport.

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│  SVG File   │───▶│  Document   │───▶│  Validator  │
│             │    │   Parser    │    │             │
└─────────────┘    └─────────────┘    └─────┬───────┘
                                            │
                   ┌─────────────┐          │
                   │   Profile   │◀─────────┘
                   └─────┬───────┘
                         │
                   ┌─────▼───────┐
                   │    Rules    │
                   └─────┬───────┘
                         │
                   ┌─────▼───────┐    ┌─────────────┐
                   │Requirements │───▶│ Validation  │
                   │             │    │   Result    │
                   └─────────────┘    └─────┬───────┘
                                            │
                   ┌─────────────┐          │
                   │Remediations │◀─────────┘
                   └─────┬───────┘
                         │
                 ┌───────▼────────┐
                 │ Fixed Document │
                 └────────────────┘

Classes

Document (`SvgConform::Document`)

Represents an SVG document. The SVG document in XML is parsed using the Moxml library, and provides SVG-specific functionality through the Document class.

Validator (`SvgConform::Validator`)

The validator is the main entry point for SVG validation. It orchestrates the validation process with loading profiles, applying rules, and collecting results.

Profile (`SvgConform::Profile`)

A profile is a collection of requirements and remediations that define a specific SVG conformance standard. Profiles are defined in YAML configuration files and are loaded dynamically at runtime.

Notice that there are requirement violations that cannot be automatically remediated. For example, if an SVG uses a forbidden element, the remediation may simply remove it, which could lead to loss of important content.

Requirements

An SvgConform requirement is a specific validation check that determines if an SVG document meets certain criteria. Requirements are implemented as classes that inherit from SvgConform::Requirements::BaseRequirement.

Each requirement class focuses on a single concern implemented using XML tree traversal and validation logic.

Every requirement check can be configured with specific parameters to fine-tune its behavior.

Profiles can include multiple requirements to cover various aspects of SVG conformance.

Remediations

An SvgConform remediation is an automatic fixing action that can be applied to an SVG document to resolve one or more requirement failures. Remediations are implemented as classes that inherit from SvgConform::Remediations::BaseRemediation.

Each remediation class focuses on a specific fixing action implemented using XML tree manipulation and editing.

Every remediation can be configured with specific parameters to customize its behavior. A remediation can target one or more specific requirements through configuration options.

Command line interface

General

The svg_conform command provides a comprehensive CLI for validation and fixing.

`svg_conform profiles`

The profiles command lists all available SVG profiles included in SvgConform.

Syntax:

svg_conform profiles [OPTIONS]

Options:
  -v, --verbose           Show detailed profile information

# List all profiles
$ svg_conform profiles

Available SVG Profiles
========================================

╭──────────────────────┬───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Profile              │ Description                                                                                                       │
├──────────────────────┼───────────────────────────────────────────────────────────────────────────────────────────────────────────────────┤
│ base                 │ Base SVG validation profile with common requirements                                                              │
│ lucid_fix            │ Lucid SVG Fix Profile - Removes invalid use element references and namespace attributes from Lucid-generated SVGs │
│ metanorma            │ Metanorma SVG Profile - SVG requirements for Metanorma technical documents with embedded resources                │
│ no_external_css      │ Security-focused profile that disallows external CSS references                                                   │
│ svg_1_2_rfc          │ SVG 1.2 RFC Profile (RFC 7996) - Black and white diagrams for technical documents                                 │
│ svg_1_2_rfc_with_rdf │ SVG 1.2 RFC Profile with RDF metadata support - Allows RDF/Dublin Core metadata in SVG files                      │
╰──────────────────────┴───────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

`svg_conform check`

The check command validates SVG files against a specified profile and optionally applies automatic remediations. It supports single files, multiple files via shell glob expansion, and directory scanning.

Syntax:

svg_conform check [*FILES] [OPTIONS]
svg_conform check --directory PATH [OPTIONS]

Required Options:
  -p, --profile PROFILE         Profile to validate against

Input Options:
  -d, --directory PATH          Directory to scan recursively for SVG files

Remediation Options:
  -f, --fix                     Enable automatic remediation
      --output-dir DIR          Output directory for remediated files (required for multi-file)
      --in-place                Replace original files (requires --force)
      --force                   Confirm destructive operations
      --fix-output FILE         Output file for single file mode (default: FILE.fixed.svg)

Reporting Options:
      --format FORMAT           Output format for single file: table, yaml, json (default: table)
  -o, --output FILE             Output file for single file mode
      --report-format FORMAT    Batch report format: json, yaml
      --report-output FILE      Save detailed batch report to file
      --manifest FILE           Manifest file path (default: manifest.json with --fix)
  -q, --quiet                   Suppress per-file output, show summary only
  -v, --verbose                 Show detailed progress

The check command supports three operational modes:

Single File Mode:

Validates a single SVG file and outputs a detailed validation report.

# Basic validation
svg_conform check file.svg -p metanorma

# With remediation
svg_conform check file.svg -p metanorma -f --fix-output fixed.svg

# Output YAML report
svg_conform check file.svg -p metanorma --format yaml -o report.yaml

Multiple Files Mode (Shell Glob):

Validates multiple files specified via shell glob patterns. The shell expands patterns like *.svg before passing to the command.

# Validate all SVG files in current directory
svg_conform check *.svg -p metanorma

# Validate with pattern matching
svg_conform check images/*/*.svg -p metanorma

# Fix multiple files
svg_conform check *.svg -p metanorma -f --output-dir fixed/

# With JSON batch report
svg_conform check *.svg -p metanorma --report-format json --report-output report.json

Directory Mode:

Recursively scans a directory for all SVG files using the --directory or -d flag.

# Scan directory and validate
svg_conform check -d images/ -p metanorma

# Scan and remediate to new directory
svg_conform check -d images/ -p metanorma -f --output-dir fixed/

# Replace files in place (requires confirmation)
svg_conform check -d images/ -p metanorma -f --in-place --force

# Quiet mode with detailed JSON report
svg_conform check -d images/ -p metanorma -f --output-dir fixed/ --quiet \
  --report-format json --report-output report.json

# With custom manifest file
svg_conform check -d images/ -p metanorma -f --output-dir fixed/ --manifest mappings.json

Batch Report Format:

When processing multiple files or directories, a batch summary is displayed:

BATCH VALIDATION SUMMARY
Directory: /path/to/images
Profile: metanorma
Files processed: 56
Valid before: 0
Remediated: 56
Valid after: 56
Failed: 0
Success rate: 100.0%
Manifest written to manifest.json

If --report-format is specified, a detailed report is generated in JSON or YAML format using lutaml-model serialization:

{
  "directory": "/path/to/images",
  "profile": "metanorma",
  "timestamp": "2025-10-12T15:36:25+08:00",
  "total_files": 56,
  "valid_before": 0,
  "valid_after": 56,
  "remediated": 56,
  "failed": 0,
  "success_rate": 100.0,
  "files": [
    {
      "filename": "diagram.svg",
      "original_path": "/path/to/images/diagram.svg",
      "valid_before": false,
      "valid_after": true,
      "errors_before": 3,
      "errors_after": 0,
      "remediated_path": "/path/to/fixed/diagram.svg",
      "status": "remediated"
    }
  ],
  "manifest": {
    "/path/to/images/diagram.svg": "/path/to/fixed/diagram.svg"
  }
}

Manifest File:

When using --fix, a manifest file is automatically created (or can be explicitly specified with --manifest). The manifest maps original file paths to their remediated counterparts:

{
  "timestamp": "2025-10-12T15:00:00+08:00",
  "profile": "metanorma",
  "mappings": {
    "/original/path/file1.svg": "/fixed/path/file1.svg",
    "/original/path/file2.svg": "/fixed/path/file2.svg"
  }
}

`svg_conform version`

The version command displays the current version of SvgConform.

Syntax:

svg_conform version

$ svg_conform version
SvgConform 0.1.0

Ruby API

Basic usage

require 'svg_conform'

# Validate a file
result = SvgConform.validate_file('diagram.svg', profile: :svg_1_2_rfc)

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

# Get detailed error information
result.errors.each do |error|
  puts "#{error.rule.id}: #{error.message}"
  puts "  Element: #{error.element}" if error.element
  puts "  Location: #{error.location}" if error.location
end

Advanced usage

# Create validator instance
validator = SvgConform::Validator.new

# Validate with custom options
result = validator.validate_file('diagram.svg',
  profile: :svg_1_2_rfc,
  fix: true,
  strict: false
)

# Access fixed document
if result.fixed?
  fixed_svg = result.fixed_document.to_xml
  File.write('diagram_fixed.svg', fixed_svg)
end

# Get profile information
profile_info = validator.profile_info(:svg_1_2_rfc)
puts "Profile: #{profile_info[:name]}"
puts "Description: #{profile_info[:description]}"
puts "Rules: #{profile_info[:rules].map { |r| r[:id] }.join(', ')}"

Working with loaded SVG content

# Parse SVG content
document = SvgConform::Document.from_content(svg_string)

# Access document elements
root = document.root
puts "Root element: #{root.name}"
puts "Namespace: #{root.namespace}"

# Find elements
circles = document.find_elements('circle')
texts = document.find_elements('text')

# Modify document
fixer = SvgConform::Fixer.new(document)
fixer.remove_element(some_element)
fixer.set_attribute(element, 'fill', 'black')

# Get modified XML
modified_svg = fixer.to_xml

Configuration

Profile configuration

Profiles can be configured using YAML files in the config/profiles/ directory:

# config/profiles/custom.yml
name: "Custom Profile"
description: "Custom SVG profile for specific requirements"
extends: "base"  # Optional: inherit from another profile

rules:
  - id: "namespace"
    type: "namespace_rule"
    config:
      required_namespace: "http://www.w3.org/2000/svg"

  - id: "allowed_elements"
    type: "allowed_elements_rule"
    config:
      allowed_elements:
        - "svg"
        - "g"
        - "rect"
        - "circle"
        - "path"
        - "text"

  - id: "color_restrictions"
    type: "color_restrictions_rule"
    config:
      grayscale_only: true
      allowed_colors:
        - "black"
        - "white"
        - "gray"

Requirement configuration

TODO.

Remediation configuration

TODO.

Extending SvgConform

Custom profiles

Create a new profile by defining a YAML configuration:

# config/profiles/my_organization.yml
profile:
  name: "My Organization SVG Profile"
  description: "SVG profile for internal use"
  import: "base"  # Optional: inherit from another profile

requirements:
  - id: "namespace"
    type: "NamespaceRequirement"
    description: "Ensure proper SVG namespace"

  - id: "custom_requirement"
    type: "CustomRequirement"
    description: "Validate custom elements"
    config:
      custom_option: "organization_value"

  - id: "security_restrictions"
    type: "NoExternalCssRequirement"
    description: "Prevent external CSS references"

remediations:
  - id: "fix_namespace"
    type: "NamespaceRemediationAction"
    description: "Add missing SVG namespace"
    targets: ["namespace"]

  - id: "fix_custom_elements"
    type: "CustomRemediationAction"
    description: "Fix custom element issues"
    targets: ["custom_requirement"]
    config:
      default_value: "organization_default"

Then load the profile:

# Load and use the custom profile
profile = SvgConform::Profile.load_from_file('config/profiles/my_organization.yml')
document = SvgConform::Document.new(svg_content)
result = profile.validate(document)

# Apply remediations if needed
if !result.valid? && profile.has_remediations?
  engine = SvgConform::RemediationEngine.new(profile)
  remediation_results = engine.apply_remediations(document, result)
end

External compliance

General

SvgConform supports external compliance validation through compatibility testing and comparison with external SVG validation tools.

SvgConform provides validation report comparison capabilities that enable assessment of compatibility with external SVG validation tools. This supports migration workflows and quality assurance processes.

svgcheck

IETF provides the svgcheck tool, a Python-based SVG validator and fixer that checks SVG files against the SVG 1.2 RFC profile defined in RFC 7996.

SvgConform supports validation compatibility testing against the IETF Python svgcheck tool for SVG 1.2 RFC validation.

SvgConform includes a compatibility analysis feature that compares its validation results with those of svgcheck, helping users identify any discrepancies or issues.

Important

As of version 2025-10-12, SvgConform’s SVG 1.2 RFC profile provides a 100% match in check and repair modes of svgcheck for all test files, except for the full-tiny.svg file, which svgcheck marks as invalid and fails to repair.

svgcheck testing workflow

The external compliance testing workflow involves generating reference outputs from external tools and comparing validation results:

# 1. Generate external tool outputs for reference
svg_conform svgcheck generate SVGCHECK_REPO_LOCAL_PATH --mode both

# 2. Generate comparison reports
svg_conform svgcheck compatibility --output comparison_report.json

svgcheck compatibility architecture

SvgConform provides compatibility with the IETF Python svgcheck tool through a sophisticated mapping and comparison system that enables validation against the SVG 1.2 RFC profile.

Architecture of svgcheck compatibility checks

╭────────────────────────────────────────────────────────────────╮
│                svgcheck Compatibility System                   │
│           (SvgConform ↔ svgcheck Python tool)                  │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│  ╭─────────────╮    ╭─────────────────────────────────────╮    │
│  │ svgcheck    │    │        YAML Mapping                 │    │
│  │ Raw Errors  │───▶│    config/svgcheck_mapping.yml      │    │
│  │ (Python)    │    │                                     │    │
│  ╰─────────────╯    │ • Pattern matching with regex       │    │
│                     │ • Requirement categorization        │    │
│                     │ • Semantic meaning extraction       │    │
│                     │ • Unmapped error detection          │    │
│                     ╰─────────────┬───────────────────────╯    │
│                                   │                            │
│  ╭────────────────────────────────▼────────────────────────╮   │
│  │              SvgcheckParser                             │   │
│  │                                                         │   │
│  │ • Applies YAML mapping during parsing                   │   │
│  │ • Categorizes errors by requirement                     │   │
│  │ • Marks unmapped errors for RED display                 │   │
│  │ • Creates properly structured ConformanceReport         │   │
│  ╰─────────────────────────┬───────────────────────────────╯   │
│                            │                                   │
│                            ▼                                   │
│  ╭─────────────────────────────────────────────────────────╮   │
│  │              Parallel Processing                        │   │
│  │                                                         │   │
│  │ ╭─────────────────────╮   ╭─────────────────────────╮   │   │
│  │ │   SvgConform        │   │     svgcheck            │   │   │
│  │ │   Validation        │   │   ConformanceReport     │   │   │
│  │ │                     │   │   (mapped)              │   │   │
│  │ │ • Native Ruby       │   │ • Parsed from YAML      │   │   │
│  │ │ • Direct profile    │   │ • Requirement-mapped    │   │   │
│  │ │ • ConformanceReport │   │ • Compatible structure  │   │   │
│  │ ╰─────────────────────╯   ╰─────────────────────────╯   │   │
│  ╰─────────────┬───────────────────────┬───────────────────╯   │
│                │                       │                       │
│                └───────────┬───────────┘                       │
│                            │                                   │
│  ╭─────────────────────────▼─────────────────────────╮         │
│  │              ReportComparator                     │         │
│  │                                                   │         │
│  │ • Direct ConformanceReport comparison             │         │
│  │ • Unified requirement-based display               │         │
│  │ • Side-by-side error mapping                      │         │
│  │ • 🚨 RED highlighting for unmapped errors         │         │
│  │ • Compatibility metrics and analysis              │         │
│  ╰───────────────────────────────────────────────────╯         │
│                                                                │
╰────────────────────────────────────────────────────────────────╯

svgcheck compatibility commands

General

In order to run the compatibility commands, you need to have the svgcheck tool installed and accessible in your PATH.

Note	The `svgcheck` tool can be installed via `pip install svgcheck`.

The commands in this section provide functionality to generate svgcheck outputs for test files and perform compatibility analysis between SvgConform and svgcheck results.

The test files from svgcheck are included in the SvgConform repository under spec/fixtures/svgcheck to ensure consistent testing.

The mapping configuration file config/svgcheck_mapping.yml defines how svgcheck error messages are interpreted and mapped to SvgConform requirements.

The data flow steps for compatibility analysis is as follows:

svgcheck outputs are generated for test files using the svgcheck generate command.
For each test file, svgcheck outputs are generated in both check-only and repair modes through the svgcheck generate command, and are then parsed by the Svgcheck::Parser class into the ReportGenerator class.
SvgConform validates the same test files using the SVG 1.2 RFC profile, which provides a ConformanceReport object.
The ReportComparator class compares the ConformanceReport from SvgConform with the svgcheck ReportGenerator results. The ReportComparator handles both check-only and repair mode outputs, and maps svgcheck messages to SvgConform requirements and remediations outcomes.
A detailed comparison report is generated, highlighting matches and discrepancies.

`svg_conform svgcheck compatibility`

The svgcheck compatibility command performs a comprehensive compatibility analysis between SvgConform validation results and the IETF svgcheck tool output.

svg_conform svgcheck compatibility [OPTIONS] [FILE]

Options:
  -p, --profile PROFILE    Profile to use (default: svg_1_2_rfc)
  -f, --file FILE          Analyze specific file instead of all test files
  -o, --output FILE        Output clean report to file (no color codes)
  -v, --verbose            Verbose output

# Run comprehensive compatibility analysis
svg_conform svgcheck compatibility

# Analyze specific file
svg_conform svgcheck compatibility --file example.svg

# Generate clean report for documentation
svg_conform svgcheck compatibility --output compatibility-report.md

# Analyze specific file and save to file
svg_conform svgcheck compatibility --file example.svg --output analysis.md

`svg_conform svgcheck generate`

The svgcheck generate command generates svgcheck outputs for test files to facilitate compatibility analysis.

These files are generated in a structured output directory, with separate subdirectories for check-only and repair modes.

Usage:
  svg_conform svgcheck generate SVGCHECK_REPO_PATH

Options:
  -m, [--mode=MODE]                                  # Generation mode: check, repair, or both
                                                     # Default: both
                                                     # Possible values: check, repair, both
      [--svgcheck-exec=SVGCHECK_EXEC]                # Path to svgcheck executable
      [--fixtures-path=FIXTURES_PATH]                # Output directory (default: spec/fixtures/svgcheck)
  -f, [--single-file=SINGLE_FILE]                    # Process single file only
      [--force]                                      # Overwrite existing outputs
                                                     # Default: false
  -v, [--verbose], [--no-verbose], [--skip-verbose]  # Verbose output
                                                     # Default: false

Description:
  Generate svgcheck outputs for test files by running svgcheck on them.

  SVGCHECK_REPO_PATH: Path to the svgcheck repository (e.g., svgcheck-reference)

  By default, processes all test files in SVGCHECK_REPO_PATH/svgcheck/Tests/ and generates BOTH check and repair
  outputs in separate subdirectories.

  Examples: svg_conform svgcheck generate svgcheck-reference svg_conform svgcheck generate svgcheck-reference --mode
  check svg_conform svgcheck generate svgcheck-reference --single-file example.svg

This command provides a bridge between SvgConform and the Python svgcheck tool, enabling comprehensive compatibility testing and analysis. By default, it generates both check and repair outputs in separate subdirectories.

The command creates a structured output directory with separate subdirectories for different svgcheck modes:

spec/fixtures/svgcheck/
├── check/          # Check-only outputs (validation without remediation)
│   ├── file1.svg.out   # Validation messages from svgcheck
│   ├── file1.svg.err   # Error messages from svgcheck
│   └── file1.svg.code  # Exit status from svgcheck
└── repair/         # Repair outputs (validation + remediation)
    ├── file1.svg.out   # Validation messages from svgcheck
    ├── file1.svg.err   # Error messages from svgcheck
    ├── file1.svg.code  # Exit status from svgcheck
    └── file1.svg.file  # Remediated SVG content

Some svgcheck test files are renamed to indicate their actual type of content, which is defined in svgcheck_generate.rb:

svgcheck full-tiny.xml is renamed to full-tiny.svg
svgcheck rfc-svg.xml is renamed to rfc-svg.svg

The generated outputs are used by the compatibility command to perform detailed comparisons between SvgConform and svgcheck validation results. The structured directory layout enables:

Targeted analysis: Compare check-only vs repair mode behaviors
Comprehensive testing: Validate against both validation and remediation workflows
Regression testing: Track changes in svgcheck behavior over time
Profile development: Use svgcheck outputs as reference for profile refinement

There are three modes of operation for generating svgcheck outputs:

Check Mode (--mode check):

Runs svgcheck without the --repair flag
Only validates SVG files and reports errors
Generates .out, .err, and .code files
No remediated content is produced

Repair Mode (--mode repair):

Runs svgcheck with the --repair flag
Validates SVG files and generates remediated content
Generates .out, .err, .code, and .file files
The .file contains the remediated SVG content

Both Mode (--mode both, default):

Runs both check and repair modes for each file
Generates complete output sets in both subdirectories
Provides comprehensive data for compatibility analysis

# Generate both check and repair outputs for all test files
svg_conform svgcheck generate /path/to/svgcheck-reference

# Generate only check outputs
svg_conform svgcheck generate /path/to/svgcheck-reference --mode check

# Generate only repair outputs
svg_conform svgcheck generate /path/to/svgcheck-reference --mode repair

# Process a single file with verbose output
svg_conform svgcheck generate /path/to/svgcheck-reference --single-file example.svg --verbose

# Force regeneration of existing outputs
svg_conform svgcheck generate /path/to/svgcheck-reference --force

# Use custom output directory
svg_conform svgcheck generate /path/to/svgcheck-reference --fixtures-path /path/to/custom/output

`svg_conform svgcheck compare`

The svgcheck compare command compares SvgConform validation results with existing svgcheck reports to assess compatibility.

This command is useful for verifying that SvgConform produces equivalent results to the IETF svgcheck tool.

Syntax:

svg_conform svgcheck compare FILE [OPTIONS]

Options:
  -p, --profile PROFILE        Profile to use (default: svg_1_2_rfc)
      --svgcheck-report FILE   Path to svgcheck report (default: auto-detect)

# Compare with auto-detected svgcheck report
$ svg_conform svgcheck compare diagram.svg -p svg_1_2_rfc

# Specify svgcheck report explicitly
$ svg_conform svgcheck compare diagram.svg --svgcheck-report diagram.svg.svgcheck.yaml

Testing

Run the test suite:

bundle exec rspec

Run specific test categories:

# Unit tests
bundle exec rspec spec/unit/

# Integration tests
bundle exec rspec spec/integration/

# SVGCheck compatibility tests
bundle exec rspec spec/svgcheck_compatibility_spec.rb

Changelog

See CHANGELOG.md for version history and changes.

Copyright and license

This gem is available as open source under the terms of the Ribose 2-clause BSD license.

svg_conform

Runtime

SvgConform: Ruby library for validating and fixing SVG files

Purpose

Features

Concepts

General

SVG document

SVG profile

SVG requirement

SVG remediation action

Defining profiles with configuration

Reporting

Compatibility with other tools

Usage

Installation

Command line usage

Ruby API usage

Core components

Architecture

Profiles

Requirements

Remediations

Requirement and remediation mapping

Validation and remediation flow

Classes

Document (SvgConform::Document)

Validator (SvgConform::Validator)

Profile (SvgConform::Profile)

Requirements

Remediations

Command line interface

General

svg_conform profiles

svg_conform check

svg_conform version

Ruby API

Basic usage

Advanced usage

Working with loaded SVG content

Configuration

Profile configuration

Requirement configuration

Remediation configuration

Extending SvgConform

Custom profiles

External compliance

General

svgcheck

svgcheck testing workflow

svgcheck compatibility architecture

svgcheck compatibility commands

General

svg_conform svgcheck compatibility

svg_conform svgcheck generate

svg_conform svgcheck compare

Testing

Changelog

Copyright and license

Document (`SvgConform::Document`)

Validator (`SvgConform::Validator`)

Profile (`SvgConform::Profile`)

`svg_conform profiles`

`svg_conform check`

`svg_conform version`

`svg_conform svgcheck compatibility`

`svg_conform svgcheck generate`

`svg_conform svgcheck compare`