XML Proposal: Use a Single `node` Element for MaterialX Node Instances

[kwokcb]

Background

MaterialX currently serializes node categories as XML element names. For example:

<image name="abc" type="float"/>
<add name="sum" type="float"/>
<fractal3d name="noise" type="float"/>

For schema definition, as MaterialX allows custom node definitions and custom categories the set of valid XML element names is effectively unbounded:

<my_custom_def1 name="n1" type="float"/>
<my_custom_def2 name="n1" type="float"/>
<my_custom_def3 name="n1" type="float"/>
<my_custom_def4 name="n1" type="float"/>
etc

This makes it difficult to define a complete XML Schema (XSD), since every new category introduces a new XML element type.

Proposal

Replace category-specific XML elements with a single generic node element and a new nodetype attribute.

Instead of:

<image name="abc" type="float"/>

use:

<node name="abc" type="float" nodetype="image"/>

or using a nodedef identifier:

<node name="abc" type="float" nodedef="ND_image_float"/>

or both:

<node  name="abc" type="float" nodetype="image" nodedef="ND_image_float"/>

Additional examples:

Current:

<image name="abc" type="float"/>
<add name="sum" type="float"/>
<fractal3d name="noise" type="float"/>

Proposed:

<node name="abc" type="float" nodetype="image"/>
<node name="sum" type="float" nodetype="add"/>
<node name="noise" type="float" nodetype="fractal3d"/>

Summary

This proposal replaces category-specific XML elements:

<image/>
<add/>
<fractal3d/>
<my_custom_node/>

with a single extensible node element:

<node nodetype="image"/>
<node nodetype="add"/>
<node nodetype="fractal3d"/>
<node nodetype="my_custom_node"/>

The primary advantages are:

• A practical and stable XML schema.
• Natural support for unlimited custom node categories.
• Simpler streaming as every element is handled the same way
• Simpler incremental parsing and resolve node type / definition afterward
• Closer alignment with the OpenUSD Shader + info:id model.
• Consistent representation across MaterialX XML, OpenUSD, serializations.
• Node identity becomes data (nodetype or nodedef) rather than XML syntax.

Details

Simplified XML Schema Definition

With the current representation, every node category appears as a distinct XML element:

<image/>
<add/>
<fractal3d/>
<my_custom_node/>

Since custom categories are allowed, the set of valid element names is effectively unlimited.

Using a single node element allows the schema to define only one node type:

<xsd:element name="node">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="input" minOccurs="0" maxOccurs="unbounded"/>
      <xsd:element name="output" minOccurs="1" maxOccurs="unbounded"/>
    </xsd:sequence>

    <xsd:attribute name="name" type="xsd:string" use="required"/>
    <xsd:attribute name="type" type="xsd:string" use="required"/>
    <xsd:attribute name="nodetype" type="xsd:string" use="required"/>
    <xsd:attribute name="nodedef" type="xsd:string" use="optional"/>
  </xsd:complexType>
</xsd:element>

Node identity becomes data rather than syntax:

<node nodetype="image"/>

instead of:

<image/>

This simplifies schema definition and validation.

Better Support for Extensions

Custom nodes can be introduced without requiring new XML element names:

<node
    name="custom1"
    nodetype="my_company_noise"
    type="float"/>

No schema updates are required regardless of how many custom categories are introduced.

Simpler Generic Processing

Tools can identify all node instances uniformly without inspecting element names:

for (ElementPtr elem : graph->getChildrenOfNodeType("node"))
{
    ...
}

Alignment with OpenUSD / glTF

OpenUSD

OpenUSD represents shader nodes using a single schema type and stores node identity as metadata.

Example:

def Shader "abc"
{
    uniform token info:id = "ND_image_float"
}

Conceptually:

OpenUSD	Meaning
Shader	Node instance type
info:id	Node definition identifier
abc	Instance name

The proposed MaterialX representation follows the same model:

<node
    name="abc"
    nodedef="ND_image_float"/>

MaterialX	Meaning
node	Node instance type
nodedef	Node definition identifier
abc	Instance name

glTF MaterialX Proposal Representation

JSON-based formats naturally represent node identity as data rather than object type.

Example:

{
    "nodes": [
        {
            "name": "abc",
            "nodetype": "image",
            "type": "float"
        }
    ]
}

or:

{
    "nodes": [
        {
            "name": "abc",
            "nodedef": "ND_image_float"
        }
    ]
}

The JSON representation maps directly to the proposed XML representation:

<node
    name="abc"
    nodetype="image"
    type="float"/>

[ld-kerley]

+1 - I think this would be a fantastic step forward for the mtlx file format.

I wonder if it might even be possible to make this an additive change now - allowing for both syntaxes to be used for reading - and potentially serializing - and just removing the old syntax in a versioned upgrade function in the future?

[kwokcb]

Hi @ld-kerley,

This can be additive as long as there is:

1. A write option (e.g. XMLWriteOption.useNodeSyntax) to allow writing to the new syntax, defaulting to false (write current syntax).
2. read supports node instances in either form -- which means adding support for the new syntax.

Basically making it forward and backward compatible.

[kwokcb]

A draft PR which implements this has been added with a few examples.