Use IntelliJ for XML File Editing

2024-03-28

Editing and statement completion in XML files is made easier by using XSDs (XML Schema Definitions). This topic helps you configure IntelliJ to find and use these files.

Using XSDs

In an XML file, you can use information from XSD files by including syntax like this:

<tables xmlns="http://labkey.org/data/xml">

In this example, the tableinfo.xsd will be loaded and when editing your XML, you will have options like statement completion: if you enter a '<' character (to start an element), you will see a popup of valid options to assist you:

Configuring IntelliJ to Recognize XSDs

If you are not seeing XSDs registered and available as expected, check to ensure that your IntelliJ is configured to find them in the correct location.

One symptom of an incorrect configuration is that the XML elements will be shown in IntelliJ in red. Select the path value and click 'Alt-Enter' for a menu of options. Choose Manually setup external resource.

In the popup, find and double click the relevant xsd file, in this example, tableinfo.xsd. Click OK. After you begin to edit your XML file, you will see the red alerts disappear and your XSD will be available.

You can also directly edit IntelliJ's settings as follows:

  • In IntelliJ, select File > Settings > Languages and Frameworks.
  • Select Schemas and DTDs.
  • In the top panel, you should see (or add) an entry for http://labkey.org/data/xml pointing to the tableinfo.xsd file in your enlistment.
    • To edit an existing entry, click to select it and use the pencil icon to edit.
  • Click OK.

Learn more about how to manually setup external resources in IntelliJ here:

Once you have configured IntelliJ to use the XSD, you can more easily find and fix problems in your XML files. When you see a red squiggle underlining an element, hover for more detail:

In the above example, a sequencing issue in the XML source is causing an error.

Common Namespace URIs

The following are some common LabKey XSD namespace URIs and their paths in the source tree.

URILocation
http://cpas.fhcrc.org/exp/xml<LABKEY_HOME>/server/modules/platform/api/schemas/expTypes.xsd
http://labkey.org/data/xml<LABKEY_HOME>/server/modules/platform/api/schemas/tableinfo.xsd
http://labkey.org/data/xml/query<LABKEY_HOME>/server/modules/platform/api/schemas/query.xsd
http://labkey.org/data/xml/queryCustomView<LABKEY_HOME>/server/modules/platform/api/schemas/queryCustomView.xsd
http://labkey.org/moduleProperties/xml/<LABKEY_HOME>/server/modules/platform/api/schemas/module.xsd
http://labkey.org/data/xml/webpart<LABKEY_HOME>/server/modules/platform/api/schemas/webpart.xsd
http://labkey.org/study/xml<LABKEY_HOME>/server/modules/platform/api/schemas/datasets.xsd

Troubleshooting XML Files

Sequence of Elements

Some, but not all content types include a <sequence> element as part of the XSD. When this is present, the sequence of elements in the XML file matter. For example, for a *.view.xml file (using this XSD), the sequence (abbreviated here) is:

<xsd:sequence>
<xsd:element name="permissions" .../>
<xsd:element name="permissionClasses" .../>
<xsd:element name="dependencies" .../>
<xsd:element name="requiredModuleContext" .../>
</xsd:sequence>

If you were to put a <permissions> element after a <dependencies> section, as shown in the image above, the error message would suggest that a <requiredModuleContext> element is missing, as this is the only valid element after dependencies. To address this error, put the <permissions> element before the <dependencies>.

An error message might look similar to:

View XML file failed validation
org.labkey.api.util.XmlValidationException: Document does not conform to its XML schema, D=view@http://labkey.org/data/xml/view ([ModuleName] views/begin.view.xml)
line -1: Expected element 'requiredModuleContext@http://labkey.org/data/xml/view' instead of 'permissions@http://labkey.org/data/xml/view' here in element view@http://labkey.org/data/xml/view

If viewed in IntelliJ while editing, the same scenario would show an error reading:

Invalid content was found starting with element '{"http://labkey.org/data/xml/view":permissions}'. One of '{"http://labkey.org/data/xml/view":requiredModuleContext}' is expected.

Related Topics