Riverscapes relies on several different Extensible Markup Language (XML) files. They are used to define the individual projects, the data warehouses that store these projects and also how the projects are displayed in RAVE.
Each of these types of XML has a different set of rules that define the tag names, attributes and how these are laid out in the file. These rules are defined in a XSD schema files that are available online.
Whenever writing XML by hand or, more likely, writing code to do so, it is absolutely vital that the XML produced is validated against the XSD schema file to check for errors and omissions. This process will verify that all tag names are valid, that the required tags are present and that the nesting of all the tags meets the XSD rules.
There are lots of tools available for validating XML. Indeed, most modern Integrated Development Environments (IDE) software can perform this task. There are even online validation tools, although they tend rely on the files being uploaded and so they only tend work on one file at a time.
Our preferred tool for validating XML is Microsoft’s free Visual Studio Code. The following instructions describe how to configure and perform XML validation using Visual Studio Code. A video description at the bottom of this page demonstrates these steps.
- Visual Studio Code.
- Java Development Kit (JDK). On Windows it’s recommended that you download and use the MSI installer to walk through the installation. At the time of writing the
jdk-8u252-x64MSI is the most appropriate download.
- Install Red Hat XML Tools in Visual Studio Code:
- Open Visual Studio Code.
- Switch to the extension Marketplace (5th icon down the left side).
- Search for “Red Hat XML Tools”.
- Click Install.
- Close and restart Visual Studio Code.
Open the XML file that you want to validate. Ensure that the XML file refers to a schema namespace in the root XML tag of the file. Here’s an example from the top of a riverscapes project file referring to the XSD file online in the GitHub repository. The namespace reference is on line 3:
<?xml version="1.0"?> <Project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/NorthArrowResearch/riverscapes-programs/master/Projects/BRAT/XSD/V1/Project.xsd"> <Name>Riverscapes Context for HUC 17120007</Name> <ProjectType>RSContext</ProjectType> <Warehouse><Meta name="id">3f286d71-6191-4f5b-a6fc-468759e7f18e</Meta><Meta name="user">eeb79d24-68b5-405a-be55-8e23fdf929dc</Meta><Meta name="program">Anabranch</Meta></Warehouse><MetaData> <Meta name="ModelVersion">1.0.0</Meta> <Meta name="dateCreated">2020-05-06T12:29:43.807018</Meta> <Meta name="dateCreated">2020-05-06T12:29:43.817540</Meta> <Meta name="HUC8">17120007</Meta> <Meta name="Watershed">Warner Lakes</Meta> </MetaData> <Realizations> ...
Open the terminal pane (CTRL+J on Windows) and switch to the “Problems” tab. Any problems with the XML should be underlined in red and also appear in this Problems pane. Test that validation is working by writing some invalid XML (either a nonsense tag name or deleting an angle bracket etc.).
- When typing XML tags use intellisense (CTRL+Space) to suggest valid tags and attributes.
- Right click anywhere in the XML file to “reformat” the document. This will reindent the nested tags.