w:dataBinding (Structured Document Tag Data Binding)

Binds a structured document tag to a specific node in a custom XML part using an XPath expression, enabling two-way data synchronisation.

Parent elements

w:sdtPr

Description

w:dataBinding establishes a link between an SDT and a node in a custom XML part stored in the document package. When data binding is active, changes to the SDT content are reflected in the XML part and vice versa.

It is defined in ECMA-376 Part 1 §17.5.2.6.

Three attributes work together to pinpoint the target XML node:

w:xpath — an XPath 1.0 expression selecting the node.
w:storeItemID — identifies the custom XML part by its store item ID (a GUID).
w:prefixMappings — declares namespace prefix bindings used in the XPath expression.

Attributes

Attribute	Type	Possible Values	Description
`w:xpath`	`xsd:string`	XPath 1.0 expression	Selects the target element or attribute in the custom XML part.
`w:storeItemID`	`xsd:string`	GUID string (e.g. `{XXXXXXXX-…}`)	Identifies the custom XML part that contains the target node.
`w:prefixMappings`	`xsd:string`	Space-separated `xmlns:prefix='uri'` declarations	Namespace prefix declarations used in `w:xpath`.

Examples

<w:sdtPr>
  <w:alias w:val="Customer Name"/>
  <w:tag w:val="customerName"/>
  <w:dataBinding
    w:prefixMappings="xmlns:ns0='http://example.com/order'"
    w:xpath="/ns0:order/ns0:customer/ns0:name"
    w:storeItemID="{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}"/>
  <w:richText/>
</w:sdtPr>

using DocumentFormat.OpenXml.Wordprocessing;

var sdtPr = new SdtProperties(
    new SdtAlias { Val = "Customer Name" },
    new Tag { Val = "customerName" },
    new DataBinding
    {
        PrefixMappings = "xmlns:ns0='http://example.com/order'",
        XPath = "/ns0:order/ns0:customer/ns0:name",
        StoreItemId = "{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}"
    },
    new SdtContentText()
);

Notes

The custom XML part identified by w:storeItemID must exist in the document package (in the customXml/ folder).
If the XPath does not resolve to a node, the SDT displays its placeholder or empty content.
Data binding supports both element and attribute nodes, but not text nodes selected directly via XPath functions.
Custom XML parts and data binding are defined in ECMA-376 Part 1 §17.5.1 (custom XML) and §17.5.2.6 (data binding).