Publishing and transforming XML web content using XSLT

You can now publish XML files as web content, and have the XML source be automatically transformed to a web page using XSL transforms (XSLT). This feature is available from build 2025-08-26. The XSLT can transform the XML to either Markdown or directly to HTML. By doing this you can publish the content directly using its source in XML, without worrying about having to update any corresponding content pages. The XSLT will automatically transform the underlying source data to its presentable form when a user wants to see it.

Example

Consider the following source XML file. It describes a harmonized interface, and the XML acts as a definition for the interface:

<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet type="text/xsl" href="/Xsl/InterfaceToMarkdown.xslt"?>
<interface xmlns="urn:nfi:iot:hi:1.0" id="urn:nfi:iot:hi:actuator:analogOutput:1.0">
	<description>Generical analog output.</description>
	<sensorData>
		<field name="Analog Output" use="Optional" m="true" type="q" description="Momentary output value."/>
		<field name="Analog Output, Raw" use="Optional" m="true" type="integer" description="Momentary raw binary output value."/>
		<field name="Analog Output, Bits" use="Optional" s="true" type="integer" description="Number of bits of precision of output value."/>
		<field name="Analog Output, Range, Low" use="Optional" s="true" type="q" description="Lowest possible value."/>
		<field name="Analog Output, Range, High" use="Optional" s="true" type="q" description="Highest possible value."/>
		<comment><![CDATA[The output value must be reported using the correct precision and unit. Examples of units that could be used:

* `%` - for instance 0-100 %
* `mA` - for instance 4-20 mA
* `V` - for instance 0-10 V]]></comment>
	</sensorData>
	<controlParameters>
		<parameter name="Analog Output" use="Mandatory" type="numeric" range="RangeElement" description="Desired state of output."/>
		<parameter name="Analog Output, Raw" use="Optional" type="integer" range="RangeElement" description="Desired raw state of output. The int version must always be supported. If the range supports numbers larger than that supported by the int type, the device must also support the long version."/>
	</controlParameters>
</interface>

Notice the second row. It contains a processing instruction that references an XSL Transform document that can be used to transform the XML:

<?xml-stylesheet type="text/xsl" href="/Xsl/InterfaceToMarkdown.xslt"?>

You can review the XSLT transform referenced here. See if you can see how it works. Otherwise, review the XSLT tutorial on w3schools to learn how XSLT works.

XSLT on the Neuron

On the TAG Neuron®, the XSL Transform procedure works a bit differently than on a traditional web server. In the traditional case, it is the browser that transforms the XML into a presentable page. This means that all the information is returned, including information you might not want to present. The process is also somewhat slowed down, since two requests have to be made.

On the Neuron, it is the the web server that transforms the XML into a presentable page, not the browser. This means that only one request has to be made. Furthermore, the web server can transform the content in two passes, simplifying the construction of the XSLT: The developer can choose to transform the XML to Markdown first. This Markdown then gets implicitly transformed into HTML in a second step:

A developer can also choose to transform the XML directly to HTML, as in the traditional case. Still, on the Neuron, this transform would be performed on the server:

An added benefit of transforming the content on the web server, is that you get consistent results regardless of browser used to view the page.

#web, #xml, #xsl, #markdown, #new, #features

XML autocomplete and validation in VSCode from xsd files

Editing XML files with VSCode can be a bit of a hassle, especially when it comes to lacking autocomplete and validation features.
The following guide will show you how I got XSD validation working in VSCode.

Setting Up XML Autocomplete and validation

Follow these steps to enable XML autocomplete and linting in VSCode:

1. Install the Red Hat XML Language Server Extension

Open VSCode and navigate to the Extensions view by clicking on the Extensions icon in the sidebar. Search for “Red Hat XML Language Server” and click the Install button to install the extension.
In some cases this is enough for the extension to do it’s magic, but it is only really reliable when the xsd file is next to the current xml file on the local machine.

2. Configure the XML Catalog

The XML Catalog is a feature that allows you to map XML namespaces to their corresponding XSD files. Here’s how to configure it:

Create an XML file (e.g., xml-catalog.xml) and define namespace-to-XSD mappings within it. Here’s an example taken from the extensions documentation:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
  <rewriteSystem
    systemIdStartString="http://www.example.com/"
    rewritePrefix="path/to/your/local/xsd/file.xsd"
  />
</catalog>

In the above example, replace http://www.example.com/ with the XML namespace you want to map, and path/to/your/local/xsd/file.xsd with the path to your XSD file on your local machine.

There are few ways to map xsd files so here’s my catalog I use for smart contracts:

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">
    <uri
        name="https://paiwise.tagroot.io/Schema/StateMachines.xsd"
        uri="https://paiwise.tagroot.io/Schema/StateMachines.xsd" />
    <uri
        name="https://paiwise.tagroot.io/Schema/NeuroFeatures.xsd"
        uri="https://paiwise.tagroot.io/Schema/NeuroFeatures.xsd" />
</catalog>

3. Configure VSCode Settings

Open your VSCode settings (File > Preferences > Settings) and search for “Catalogs” You should see a setting named “XML: Catalogs.” Click the “Add item” butten, and add the path to your XML Catalog file.

4. Done

Now when you edit XML files it will recognize namespaces defined in the catalog and will show you all valid tags if you just type <

#xml, #vscode