Author: Bob Jacobsen
Keywords: JMRI technical code xml usage

# 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 them.

Each file contains a DOCTYPE line that specifies a DTD name. There are three different methods used to locate the actual DTD file:

- Web browsers look exactly where the DOCTYPE line specifies, and must find the DTD there to function.
- 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 line:
  - name.dtd
  - ../DTD/name.dtd
  Early XML files used both; the program itself could generate either depending on the circumstances.
- 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 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 DTD file.
  - 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 directory.
  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.

Starting with JMRI 2.9.4, JMRI uses XML schema instead of DTDs, and this process is different.