JMRI: XML DTD Usage
This page describes the former usage of XML DTDs in JMRI before version
2.9.4. The use of these DTDs in JMRI was replaced with XML
schema in JMRI 2.9.4.
In the JMRI distributions, the DTDs are stored in the xml/DTD
directory. Note that they are not stored in each directory alongside the XML files. There are
just too many locations to keep such a set of DTD files up to date. JMRI itself, via the
jmri.jmrit.XmlFile class, provides support for locating those files when the XML parser needs
Each file contains a DOCTYPE line that specifies a DTD name. There are three different
methods used to locate the actual DTD file:
Starting with JMRI 2.9.4, JMRI uses XML schema instead
of DTDs, and this process is different.
- Web browsers look exactly where the DOCTYPE line specifies, and must find the DTD there
- JMRI 1.8 and earlier assumes that the name is relative to the program's xml/DTD
directory, and looks for it using that. In practice, this allows two forms for the DOCTYPE
Early XML files used both; the program itself could generate either depending on the
- JMRI 1.9.2 and later provide a more powerful DTD search procedure using the jmri.util.JmriLocalEntityResolver
class. It parses the reference in the DOCTYPE and handles it in several ways:
If the file can't be found, the XML file isn't opened. These JMRI versions write just the
DTD filename in the DOCTYPE line when writing XML files. This provides complete backward
compatibility with existing files and older versions of JMRI back to 1.7.1. At the same
time, since it can handle HTTP URLs even without an Internet connection, it allows us to
eventually move forward.
- If it's an HTTP URL, JMRI first attempts to find the corresponding file in the
local distribution. If so, it uses the local copy, otherwise it attempts to load a copy
from the Internet using the URL.
- If it's a file path that starts with "../DTD/", JMRI looks in it's local xml/DTD
directory for the DTD file.
- If the path is just a filename, JMRI looks in it's local xml/DTD directory for the
- In any other case, e.g. a local or absolute pathname, JMRI looks there for the DTD
file. Relative pathnames are interpreted as starting from the JMRI install