Kataba (片刃) provides XML Schema Definition (XSD) mirroring and offline validation for Nokogiri
- Configuration to enable optional mirror list for XSD files
- Configuration to alter offline storage location
- Recursive XSD search to ensure total depth processing (i.e. XSD -> import -> etc.)
The cache layout — every transitively-imported XSD stored as
<md5(URL)>.xsd in one flat directory, with each schemaLocation
attribute in the cached files rewritten to those MD5'd filenames — is a
deliberate workaround for two stacked constraints in the
Nokogiri / libxml / JRuby stack. Capturing the rationale here so the
gem's "weirdness" stays explained even if the upstream links rot.
1. libxml resolves xs:import schemaLocation against the working
directory at schema-parse time. If the schemaLocation is an absolute
URL, libxml goes off and fetches it over the network — slow, fragile,
and the reason this gem exists in the first place. The classic
workaround (documented by Ktulu in 2011) is to put every
imported XSD in one directory, rewrite each import to a relative
filename, and Dir.chdir to that directory at schema-load time.
Kataba automates that recipe: fetch_schema wraps the
Nokogiri::XML::Schema(...) call in a Dir.chdir(offline_storage)
block.
2. Under JRuby + nokogiri-java, Dir.chdir doesn't propagate to the
Java code that handles imports (reproduction repo;
JRuby's lead maintainer has stated on JIRA that Dir.chdir is fragile
under JRuby and full paths should be preferred). The portable fix is to
remove path resolution from the picture entirely: store every cached
XSD as a flat sibling, and rewrite every schemaLocation to a bare
filename with no directory components. With nothing to resolve, neither
MRI's libxml nor nokogiri-java has anything to get wrong.
MD5(URL) is the collision-free flat-name function. In real-world
schemas, imports collide on basename — http://www.loc.gov/mods/xml.xsd
and http://www.w3.org/2001/xml.xsd both end in xml.xsd. Hashing the
full URL gives a stable, deterministic per-source filename without
inventing a path-flattening scheme. (MD5 here is a content-addressable
name, not a security primitive — collision resistance against random
URLs is more than enough.)
download_xsd is recursive because xs:import chains aren't always
one level deep: mods-3-5.xsd imports xlink.xsd and xml.xsd, and
other schemas chain further. After each fetch, every schemaLocation
in the file is captured and rewritten in place, then the loop runs
again on any new URIs that surfaced.
gem install kataba
Kataba.configuration.offline_storage = "/tmp/kataba"
Kataba.configuration.mirror_list = File.join(Rails.root, 'config', 'mirror.yml')
The fetch_schema method returns a Nokogiri::XML::Schema object
xsd = Kataba.fetch_schema("http://www.loc.gov/standards/mods/v3/mods-3-5.xsd")