OOXML Namespaces

What Are XML Namespaces?

Namespaces prevent naming conflicts when combining XML from different specifications. Think of them as "last names" for XML elements.

Without namespaces:

<table>  <!-- HTML table? Database table? Word table? -->

With namespaces:

<w:tbl>  <!-- Word table -->
<html:table>  <!-- HTML table -->
<db:table>  <!-- Database table -->

Why OOXML Needs Namespaces

Office Open XML combines multiple specifications:

WordprocessingML (Word documents)
DrawingML (Shapes, images, charts)
Relationships (Connecting parts)
Extended properties (Word 2010+ features)
Custom XML (Your data)

Each needs its own namespace to avoid conflicts.

Primary OOXML Namespaces

Namespace Declarations

Where They Live

Namespaces are declared in the root element of each XML file:

<w:document 
    xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
    xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
    xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
    xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"
    xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture"
    xmlns:v="urn:schemas-microsoft-com:vml"
    xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml">
  
  <w:body>
    <!-- Content using these namespaces -->
  </w:body>
</w:document>

Format: xmlns:prefix="namespace-uri"

prefix - Short name used in document (e.g., w, r)
namespace-uri - Full URI identifying the specification

Core Namespace: `w:` (WordprocessingML)

URI: http://schemas.openxmlformats.org/wordprocessingml/2006/main

Purpose: Main Word document elements

Elements:

w:document - Root
w:body - Body
w:p - Paragraph
w:r - Run
w:t - Text
w:tbl - Table
w:tr - Table row
w:tc - Table cell
w:pPr - Paragraph properties
w:rPr - Run properties
w:sdt - Content control

Usage:

<w:p>
  <w:r>
    <w:t>Hello World</w:t>
  </w:r>
</w:p>

💡 This is the most commonly used namespace in Word documents!

Relationships Namespace: `r:`

URI: http://schemas.openxmlformats.org/officeDocument/2006/relationships

Purpose: Reference relationships to other parts

Attributes:

r:id - Relationship ID
r:embed - Embedded resource reference
r:link - Linked resource reference

Usage:

<!-- Image reference -->
<a:blip r:embed="rId5"/>

<!-- Hyperlink -->
<w:hyperlink r:id="rId7">
  <w:r><w:t>Click here</w:t></w:r>
</w:hyperlink>

<!-- Header reference -->
<w:headerReference w:type="default" r:id="rId8"/>

🔗 See Also: Relationship Files

WordprocessingDrawing Namespace: `wp:`

URI: http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing

Purpose: Image and shape positioning in Word documents

Elements:

wp:inline - Inline image (in text flow)
wp:anchor - Floating image (positioned independently)
wp:extent - Image dimensions
wp:docPr - Drawing properties

Usage:

<w:drawing>
  <wp:inline>  <!-- Image flows with text -->
    <wp:extent cx="914400" cy="914400"/>  <!-- 1 inch × 1 inch -->
    <wp:docPr id="1" name="Picture 1"/>
    <!-- Image content -->
  </wp:inline>
</w:drawing>

DrawingML Namespace: `a:`

URI: http://schemas.openxmlformats.org/drawingml/2006/main

Purpose: Graphics, colors, effects, transforms

Elements:

a:graphic - Graphic container
a:graphicData - Graphic data
a:blip - Binary large image or picture (the actual image reference)
a:solidFill - Solid color fill
a:gradFill - Gradient fill
a:ln - Line
a:prstGeom - Preset geometry (shapes)

Usage:

<a:graphic>
  <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/picture">
    <pic:pic>
      <pic:blipFill>
        <a:blip r:embed="rId5"/>  <!-- Image reference -->
        <a:stretch>
          <a:fillRect/>
        </a:stretch>
      </pic:blipFill>
    </pic:pic>
  </a:graphicData>
</a:graphic>

Picture Namespace: `pic:`

URI: http://schemas.openxmlformats.org/drawingml/2006/picture

Purpose: Picture-specific elements

Elements:

pic:pic - Picture container
pic:blipFill - Image fill
pic:spPr - Shape properties
pic:nvPicPr - Non-visual picture properties

Usage:

<pic:pic>
  <pic:nvPicPr>
    <pic:cNvPr id="0" name="Property Photo"/>
    <pic:cNvPicPr/>
  </pic:nvPicPr>
  
  <pic:blipFill>
    <a:blip r:embed="rId5"/>
  </pic:blipFill>
  
  <pic:spPr>
    <a:xfrm>
      <a:ext cx="914400" cy="914400"/>
    </a:xfrm>
  </pic:spPr>
</pic:pic>

From AppraiSys: Property photos in appraisal reports use this structure.

VML Namespace: `v:`

URI: urn:schemas-microsoft-com:vml

Purpose: Vector Markup Language (legacy from Word 2003)

Status: Legacy but still used for backward compatibility

Elements:

v:shape - Vector shape
v:textbox - Text box
v:imagedata - Image data

Usage (less common now):

<v:shape style={{"width": "100pt", "height": "100pt"}}>
  <v:textbox>
    <w:txbxContent>
      <w:p><w:r><w:t>Text in box</w:t></w:r></w:p>
    </w:txbxContent>
  </v:textbox>
</v:shape>

💡 Modern approach: Use DrawingML (a:) instead when possible.

Extension Namespaces: `w14:`, `w15:`

URIs:

w14: - http://schemas.microsoft.com/office/word/2010/wordml
w15: - http://schemas.microsoft.com/office/word/2012/wordml

Purpose: Features added in Word 2010 and later

Examples:

w14:textFill - Text fill effects
w14:shadow - Shadow effects
w14:reflection - Reflection effects
w15:appearance - Appearance settings

Usage:

<w:rPr>
  <w14:textFill>
    <w14:gradFill>
      <!-- Gradient text fill (Word 2010+) -->
    </w14:gradFill>
  </w14:textFill>
</w:rPr>

⚠️ Compatibility: These features won't work in older Word versions.

Complete Example: Image with All Namespaces

<w:document 
    xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"
    xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"
    xmlns:wp="http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing"
    xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"
    xmlns:pic="http://schemas.openxmlformats.org/drawingml/2006/picture">
  
  <w:body>
    <w:p>  <!-- WordprocessingML: paragraph -->
      <w:r>  <!-- WordprocessingML: run -->
        
        <w:drawing>  <!-- WordprocessingML: drawing container -->
          
          <wp:inline>  <!-- WordprocessingDrawing: inline positioning -->
            <wp:extent cx="914400" cy="914400"/>
            <wp:docPr id="1" name="Photo"/>
            
            <a:graphic>  <!-- DrawingML: graphic -->
              <a:graphicData uri="...">
                
                <pic:pic>  <!-- Picture: picture element -->
                  <pic:nvPicPr>
                    <pic:cNvPr id="0" name="image.jpg"/>
                    <pic:cNvPicPr/>
                  </pic:nvPicPr>
                  
                  <pic:blipFill>
                    <a:blip r:embed="rId5"/>  <!-- Relationships: reference -->
                    <a:stretch>
                      <a:fillRect/>
                    </a:stretch>
                  </pic:blipFill>
                  
                  <pic:spPr>
                    <a:xfrm>
                      <a:ext cx="914400" cy="914400"/>
                    </a:xfrm>
                  </pic:spPr>
                </pic:pic>
                
              </a:graphicData>
            </a:graphic>
          </wp:inline>
        </w:drawing>
        
      </w:r>
    </w:p>
  </w:body>
</w:document>

Namespaces used:

w: - Document structure (document, body, p, r, drawing)
wp: - Image positioning (inline, extent, docPr)
a: - Graphics (graphic, graphicData, blip, xfrm, ext)
pic: - Picture specifics (pic, nvPicPr, blipFill, spPr)
r: - Relationship reference (embed)

Namespace Declaration Rules

Rule 1: Declare Before Use

<!-- WRONG: namespace not declared -->
<w:document>
  <w:p><w:r><a:blip/></w:r></w:p>  <!-- a: not declared! -->
</w:document>

<!-- CORRECT: namespace declared -->
<w:document 
    xmlns:w="..."
    xmlns:a="...">
  <w:p><w:r><a:blip/></w:r></w:p>
</w:document>

Rule 2: Declare at Root

Best practice: declare all namespaces at the root element.

<!-- GOOD: All at root -->
<w:document xmlns:w="..." xmlns:r="..." xmlns:a="...">
  ...
</w:document>

<!-- WORKS but not ideal: Declare where used -->
<w:document xmlns:w="...">
  <w:drawing xmlns:a="...">
    <a:graphic>...</a:graphic>
  </w:drawing>
</w:document>

Rule 3: Prefix Can Vary (URI Matters)

The URI is what matters, not the prefix:

<!-- These are equivalent -->
<w:p xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
  ...
</w:p>

<word:p xmlns:word="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
  ...
</word:p>

However, stick to standard prefixes for clarity!

Standard Prefix Conventions

Prefix	Namespace Purpose	Standard?
`w`	WordprocessingML	Yes
`r`	Relationships	Yes
`wp`	WordprocessingDrawing	Yes
`a`	DrawingML	Yes
`pic`	Picture	Yes
`v`	VML	Yes
`w14`	Word 2010 extensions	Yes
`w15`	Word 2013 extensions	Yes
`mc`	Markup compatibility	Yes
`o`	Office	Yes

Always use standard prefixes to avoid confusion!

What Happens When Namespaces Are Wrong?

Missing Namespace Declaration

<w:document>  <!-- w: declared -->
  <w:body>
    <a:graphic>  <!-- ERROR: a: not declared! -->
      ...
    </a:graphic>
  </w:body>
</w:document>

Result: Word can't parse the document. Shows "repair" dialog or fails to open.

Wrong Namespace URI

<w:document xmlns:w="http://wrong-uri.com/word">
  <w:p><w:r><w:t>Text</w:t></w:r></w:p>
</w:document>

Result: Word doesn't recognize elements. Document may open but content is missing or malformed.

Missing Prefix

<w:document xmlns:w="...">
  <body>  <!-- Should be w:body -->
    <p>   <!-- Should be w:p -->
      ...
    </p>
  </body>
</w:document>

Result: Elements not recognized. Document structure broken.

AppraiSys Namespace Usage

In C# with OpenXML SDK

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Wordprocessing;
using A = DocumentFormat.OpenXml.Drawing;
using DW = DocumentFormat.OpenXml.Drawing.Wordprocessing;
using PIC = DocumentFormat.OpenXml.Drawing.Pictures;

// SDK handles namespaces automatically
var paragraph = new Paragraph();  // Creates w:p
var run = new Run();              // Creates w:r
var text = new Text("Hello");     // Creates w:t

// Drawing elements with alias
var blip = new A.Blip { Embed = relationshipId };  // Creates a:blip
var inline = new DW.Inline();  // Creates wp:inline

The SDK:

✅ Automatically adds namespace declarations
✅ Uses correct prefixes
✅ Validates namespace usage

Namespace Quick Reference

Common Element→Namespace Mapping

Element	Namespace	Purpose
`document`, `body`, `p`, `r`, `t`	`w:`	Document content
`tbl`, `tr`, `tc`	`w:`	Tables
`pPr`, `rPr`, `tblPr`	`w:`	Properties
`sdt`, `sdtPr`, `sdtContent`	`w:`	Content controls
`id`, `embed`, `link`	`r:`	Relationship references
`inline`, `anchor`, `extent`	`wp:`	Image positioning
`graphic`, `blip`, `xfrm`	`a:`	Graphics and shapes
`pic`, `blipFill`	`pic:`	Pictures

Debugging Namespace Issues

Using OpenXML SDK Productivity Tool

Open document in the tool
Look at XML view

Check root element declarations:

<w:document xmlns:w="..." xmlns:r="...">

Verify all used prefixes are declared

Using Validator

using DocumentFormat.OpenXml.Validation;

var validator = new OpenXmlValidator();
var errors = validator.Validate(wordDoc);

foreach (var error in errors)
{
    if (error.Description.Contains("namespace"))
    {
        Console.WriteLine($"Namespace issue: {error.Description}");
    }
}

Manual Check

Extract DOCX and open XML files:

# Extract
Expand-Archive document.docx -DestinationPath extracted

# Check namespaces
Get-Content extracted/word/document.xml | Select-String "xmlns:"

Best Practices

✅ DO:

Declare all namespaces at root element
Use standard prefix conventions (w:, r:, a:, etc.)
Let OpenXML SDK handle namespaces when possible
Validate documents after generation

❌ DON'T:

Forget to declare namespaces
Use custom prefixes without good reason
Mix different namespace declarations across parts
Manually write namespace URIs (use SDK constants)

Next Steps

Now that you understand namespaces, learn about the three most common fatal mistakes:

➡️ Next: Common Fatal Mistakes - The errors that corrupt documents

Related:

WordprocessingML Core - Elements that use these namespaces
Element Hierarchy Rules - Valid nesting

Test Your Understanding

Question 1

What happens if you use <p> instead of <w:p> in document.xml?

Answer

Word won't recognize it as a paragraph because it's not in the WordprocessingML namespace. The document will likely fail to open or show a repair dialog. Always use the namespace prefix: <w:p>.

Question 2

Can you use a different prefix for the same namespace?

Answer

Technically yes, as long as the URI is correct:

<word:document xmlns:word="http://schemas.openxmlformats.org/wordprocessingml/2006/main">

However, this is confusing. Stick to standard prefixes (w:) for clarity.

Question 3

Where should you declare namespaces?

Answer

Best practice: Declare all namespaces in the root element of each XML file:

<w:document 
    xmlns:w="..."
    xmlns:r="..."
    xmlns:a="...">
  <!-- All namespaces declared here -->
</w:document>

This makes them available throughout the document.

💡 Remember: Namespaces are XML's way of preventing conflicts. Get them right, and elements work together harmoniously!

What Are XML Namespaces?​

Why OOXML Needs Namespaces​

Primary OOXML Namespaces​

Namespace Declarations​

Where They Live​

Core Namespace: w: (WordprocessingML)​

Relationships Namespace: r:​

WordprocessingDrawing Namespace: wp:​

DrawingML Namespace: a:​

Picture Namespace: pic:​

VML Namespace: v:​

Extension Namespaces: w14:, w15:​

Complete Example: Image with All Namespaces​

Namespace Declaration Rules​

Rule 1: Declare Before Use​

Rule 2: Declare at Root​

Rule 3: Prefix Can Vary (URI Matters)​

Standard Prefix Conventions​

What Happens When Namespaces Are Wrong?​

Missing Namespace Declaration​

Wrong Namespace URI​

Missing Prefix​

AppraiSys Namespace Usage​

In C# with OpenXML SDK​

Namespace Quick Reference​

Common Element→Namespace Mapping​

Debugging Namespace Issues​

Using OpenXML SDK Productivity Tool​

Using Validator​

Manual Check​

Best Practices​

✅ DO:​

❌ DON'T:​

Next Steps​

Test Your Understanding​

Question 1​

Question 2​

Question 3​

What Are XML Namespaces?

Why OOXML Needs Namespaces

Primary OOXML Namespaces

Namespace Declarations

Where They Live

Core Namespace: `w:` (WordprocessingML)

Relationships Namespace: `r:`

WordprocessingDrawing Namespace: `wp:`

DrawingML Namespace: `a:`

Picture Namespace: `pic:`

VML Namespace: `v:`

Extension Namespaces: `w14:`, `w15:`

Complete Example: Image with All Namespaces

Namespace Declaration Rules

Rule 1: Declare Before Use

Rule 2: Declare at Root

Rule 3: Prefix Can Vary (URI Matters)

Standard Prefix Conventions

What Happens When Namespaces Are Wrong?

Missing Namespace Declaration

Wrong Namespace URI

Missing Prefix

AppraiSys Namespace Usage

In C# with OpenXML SDK

Namespace Quick Reference

Common Element→Namespace Mapping

Debugging Namespace Issues

Using OpenXML SDK Productivity Tool

Using Validator

Manual Check

Best Practices

✅ DO:

❌ DON'T:

Next Steps

Test Your Understanding

Question 1

Question 2

Question 3