Relationship Files (.rels)

What Are Relationship Files?

Relationship files (.rels) are the glue that holds a DOCX document together. They define how different parts of the document connect to each other.

Think of them as a map that tells Word:

"When you see rId5 in the document, it refers to media/image2.png"
"This hyperlink with rId12 goes to https://example.com"
"The header for this section is in header1.xml"

Why Relationships Exist

The Problem They Solve

Imagine if every time you referenced an image, you had to write the full path in your document XML:

<!-- Without relationships (doesn't actually work this way) -->
<w:drawing>
  <pic:pic source="/word/media/image1.png">
</w:drawing>

Problems:

Path changes break everything
Can't have external links
Hard to track what resources are used
Difficult to reuse resources

The Solution: Indirect References

Instead, OOXML uses relationship IDs:

<!-- In document.xml -->
<w:drawing>
  <a:blip r:embed="rId5"/>  <!-- Just an ID -->
</w:drawing>

<!-- In word/_rels/document.xml.rels -->
<Relationship Id="rId5"
              Type="http://...relationships/image"
              Target="media/image1.png"/>

Benefits:

Change the target without touching document content
Track all dependencies in one place
Support external resources
Reuse relationships across document

Relationship File Structure

Two Types of Relationship Files

1. Package Relationships (`/_rels/.rels`)

Purpose: Root-level relationships for the entire package

Location: /_rels/.rels (always at root)

What it links:

Main document part (/word/document.xml)
Core properties (/docProps/core.xml)
Extended properties (/docProps/app.xml)
Custom properties (if any)

Example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
  
  <!-- Main document -->
  <Relationship 
    Id="rId1" 
    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" 
    Target="word/document.xml"/>
  
  <!-- Document properties -->
  <Relationship 
    Id="rId2" 
    Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" 
    Target="docProps/core.xml"/>
  
  <Relationship 
    Id="rId3" 
    Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties" 
    Target="docProps/app.xml"/>
  
</Relationships>

2. Part Relationships (`/word/_rels/*.xml.rels`)

Purpose: Relationships for a specific part

Location: Parallel to the part, in _rels subfolder

Example: For /word/document.xml, relationships are in /word/_rels/document.xml.rels

What it links: Everything the document content references:

Images
Hyperlinks
Headers and footers
Footnotes and endnotes
Comments
Embedded objects
Charts
Styles
Numbering

Anatomy of a Relationship

Each relationship has three key attributes:

<Relationship 
  Id="rId5"                                    <!-- 1. Unique ID -->
  Type="http://...relationships/image"         <!-- 2. Type -->
  Target="media/image1.png"                    <!-- 3. Target -->
  TargetMode="Internal"/>                      <!-- 4. Mode (optional) -->

1. Id Attribute - The Reference Key

Unique within this relationships file
Convention: rId1, rId2, etc. (but can be anything)
Referenced from the parent part's content
Must be unique within the file

⚠️ Common Pitfall: Duplicate IDs in the same .rels file cause corruption!

2. Type Attribute - What Kind of Resource

Defines the relationship type using a URI. Common types:

Type URI Suffix	Purpose	Example Usage
`/image`	Embedded image	Photos, diagrams
`/hyperlink`	External hyperlink	URLs, email links
`/header`	Header XML	Page headers
`/footer`	Footer XML	Page footers
`/styles`	Styles XML	Document styles
`/numbering`	Numbering XML	List definitions
`/footnotes`	Footnotes XML	Document footnotes
`/comments`	Comments XML	Reviewer comments
`/chart`	Chart part	Embedded charts

Full URIs (namespace prefix omitted above):

http://schemas.openxmlformats.org/officeDocument/2006/relationships/[type]

3. Target Attribute - Where to Find It

Relative path from the part's location
For internal resources: path within the ZIP
For external resources: full URL

Examples:

<!-- Internal: relative path -->
<Relationship Target="media/image1.png"/>

<!-- Internal: absolute path from package root -->
<Relationship Target="/word/media/image1.png"/>

<!-- External: full URL -->
<Relationship Target="https://example.com" TargetMode="External"/>

4. TargetMode Attribute - Internal or External

Internal (default): Resource is inside the DOCX package
External: Resource is outside (e.g., web URL)

When external:

<Relationship 
  Id="rId10" 
  Type="http://...relationships/hyperlink" 
  Target="https://www.appraisys.com"
  TargetMode="External"/>

Common Relationship Types in Detail

Images

Type: http://schemas.openxmlformats.org/officeDocument/2006/relationships/image

In document.xml:

<w:drawing>
  <wp:inline>
    <a:graphic>
      <a:graphicData>
        <pic:pic>
          <pic:blipFill>
            <a:blip r:embed="rId5"/>  <!-- References relationship -->
          </pic:blipFill>
        </pic:pic>
      </a:graphicData>
    </a:graphic>
  </wp:inline>
</w:drawing>

In document.xml.rels:

<Relationship 
  Id="rId5" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" 
  Target="media/image1.png"/>

💡 Pro Tip: In AppraiSys, images for property photos use this pattern. Check DefaultDocument.cs for image embedding code.

Hyperlinks

Type: http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink

In document.xml:

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

In document.xml.rels:

<Relationship 
  Id="rId7" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink" 
  Target="https://www.example.com"
  TargetMode="External"/>

Headers and Footers

Type: http://schemas.openxmlformats.org/officeDocument/2006/relationships/header (or /footer)

In document.xml (within section properties):

<w:sectPr>
  <w:headerReference w:type="default" r:id="rId8"/>
  <w:footerReference w:type="default" r:id="rId9"/>
</w:sectPr>

In document.xml.rels:

<Relationship 
  Id="rId8" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/header" 
  Target="header1.xml"/>

<Relationship 
  Id="rId9" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/footer" 
  Target="footer1.xml"/>

Styles

Type: http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles

In document.xml.rels:

<Relationship 
  Id="rId1" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" 
  Target="styles.xml"/>

Note: Usually rId1 because styles are fundamental to the document.

Relationship ID Management

How IDs Are Generated

In AppraiSys codebase, when you add a part:

// Adding an image part
var imagePart = mainPart.AddImagePart(ImagePartType.Png);
imagePart.FeedData(imageStream);

// OpenXML SDK automatically creates relationship and assigns ID
string relationshipId = mainPart.GetIdOfPart(imagePart);
// Returns something like "rId5"

The SDK handles:

Generating unique IDs
Creating the relationship entry
Updating the .rels file

Manual ID Assignment (Advanced)

If creating relationships manually (rare):

var relationship = mainPart.AddExternalRelationship(
    "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink",
    new Uri("https://example.com"),
    "rId10"  // Explicitly specify ID
);

⚠️ Warning: Make sure the ID is unique! Duplicates will corrupt the document.

Relationship File Flow

Common Relationship Errors

Error 1: Missing Relationship

Symptom: Image doesn't appear, or Word shows "repair" dialog

In document.xml:

<a:blip r:embed="rId99"/>  <!-- References rId99 -->

In document.xml.rels:

<!-- rId99 doesn't exist! -->
<Relationship Id="rId5" ... />
<Relationship Id="rId6" ... />

Fix: Create the relationship with Id="rId99"

Error 2: Wrong Target Path

Symptom: Image doesn't load, broken content

In document.xml.rels:

<Relationship 
  Id="rId5" 
  Type="...relationships/image" 
  Target="media/image1.png"/>  <!-- File is at media/photo1.png -->

Fix: Ensure target path matches actual file location in ZIP

Error 3: Duplicate IDs

Symptom: Document corruption, unpredictable behavior

In document.xml.rels:

<Relationship Id="rId5" Target="media/image1.png"/>
<Relationship Id="rId5" Target="media/image2.png"/>  <!-- Duplicate! -->

Fix: Use unique IDs for each relationship

Error 4: Missing TargetMode for External Links

Symptom: Hyperlink treated as internal path, doesn't work

Wrong:

<Relationship 
  Id="rId7" 
  Type="...relationships/hyperlink" 
  Target="https://example.com"/>  <!-- Missing TargetMode -->

Correct:

<Relationship 
  Id="rId7" 
  Type="...relationships/hyperlink" 
  Target="https://example.com"
  TargetMode="External"/>  <!-- Explicit external mode -->

Relationship Files in AppraiSys

When Images Are Added

From your codebase (DefaultDocument.cs):

public static void AddImageToBodyFromPixels(
    this WordprocessingDocument wordDoc, 
    string relationshipId,
    int imageWidthPixels, 
    int imageHeightPixels, 
    ...)
{
    // Relationship already created before this method
    // Just use the relationshipId in the drawing element
    var element = new Drawing(
        new DW.Inline(
            ...
            new A.Blip { Embed = relationshipId },  // Uses the relationship
            ...
        )
    );
}

The relationship is created earlier:

// In your image processing pipeline
var imagePart = mainPart.AddImagePart(ImagePartType.Png);
imagePart.FeedData(imageStream);
string relationshipId = mainPart.GetIdOfPart(imagePart);

// This automatically creates entry in document.xml.rels

When Documents Are Merged

From MergeReportSectionsConsumer pattern:

When merging multiple sections:

Each section has its own relationships
IDs might conflict (both use rId5)
Must renumber relationships to avoid conflicts
Update all references in content

Strategy:

// Pseudo-code from your merge logic
foreach (var section in sections)
{
    var idMap = new Dictionary<string, string>();
    
    foreach (var rel in section.Relationships)
    {
        string newId = GenerateUniqueId();  // e.g., rId100, rId101...
        idMap[rel.Id] = newId;
        
        // Create relationship with new ID
        targetDoc.AddRelationship(rel.Type, rel.Target, newId);
    }
    
    // Update all r:id references in content
    UpdateRelationshipReferences(section.Content, idMap);
}

🔗 See Also: Document Assembly for complete merging patterns

Visualizing Relationships

Key Insight: Relationships can chain! A header can have its own relationships to images.

Practical Example: Adding an Image

Step-by-Step Process

Add image file to /word/media/
```
/word/media/property_photo.jpg
```

Create relationship in /word/_rels/document.xml.rels

<Relationship 
  Id="rId15" 
  Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" 
  Target="media/property_photo.jpg"/>

Reference in /word/document.xml

<w:p>
  <w:r>
    <w:drawing>
      <wp:inline>
        <a:graphic>
          <a:graphicData>
            <pic:pic>
              <pic:blipFill>
                <a:blip r:embed="rId15"/>  <!-- References relationship -->
              </pic:blipFill>
            </pic:pic>
          </a:graphicData>
        </a:graphic>
      </wp:inline>
    </w:drawing>
  </w:r>
</w:p>

Update [Content_Types].xml (if file type not already listed)
```
<Default Extension="jpg" ContentType="image/jpeg"/>
```

Miss any step? → Image won't appear or document corrupts!

Debugging Relationship Issues

Using OpenXML SDK Productivity Tool

Open your DOCX in the tool
Navigate to Document Parts
Find /_rels/.rels and /word/_rels/document.xml.rels
Inspect relationships visually
Validate for errors

Manual Inspection

# Extract DOCX
Expand-Archive document.docx -DestinationPath extracted

# View relationships file
cat extracted/word/_rels/document.xml.rels

Look for:

Duplicate IDs
Missing targets
Incorrect types
Missing TargetMode for external links

Using Validator

using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Validation;

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

foreach (var error in errors)
{
    if (error.Description.Contains("relationship"))
    {
        Console.WriteLine($"Relationship error: {error.Description}");
        Console.WriteLine($"Location: {error.Path.XPath}");
    }
}

Quick Reference: Relationship Types

Resource	Type URI Suffix	TargetMode	Example Target
Image	`/image`	Internal	`media/image1.png`
Hyperlink	`/hyperlink`	External	`https://example.com`
Header	`/header`	Internal	`header1.xml`
Footer	`/footer`	Internal	`footer1.xml`
Styles	`/styles`	Internal	`styles.xml`
Numbering	`/numbering`	Internal	`numbering.xml`
Footnotes	`/footnotes`	Internal	`footnotes.xml`
Comments	`/comments`	Internal	`comments.xml`

Full Type URI: http://schemas.openxmlformats.org/officeDocument/2006/relationships/[suffix]

Next Steps

Now that you understand how document parts connect, learn about the actual content structure:

➡️ Next: WordprocessingML Core - Paragraphs, runs, and text

Related Topics:

Element Hierarchy Rules - Valid nesting
Image Handling - Code examples

Test Your Understanding

Question 1

You add an image to /word/media/photo.jpg but forget to create a relationship. What happens?

Answer

The image file exists in the DOCX archive, but Word can't display it because there's no relationship mapping an ID to the file. The document will open, but the image location will be blank or show an error placeholder.

Question 2

Can two different images share the same relationship ID?

Answer

No! Each relationship ID must be unique within a .rels file. However, the same image file can be referenced by multiple relationship IDs if you want to use the same image in different places.

Question 3

What's the difference between Target="image.png" and Target="media/image.png"?

Answer

Both are relative paths from the location of the .rels file. If the .rels file is at /word/_rels/document.xml.rels:

Target="image.png" → looks for /word/image.png
Target="media/image.png" → looks for /word/media/image.png

Always use paths relative to the part, not the package root.

💡 Remember: Relationships are the glue! Break them, and your document falls apart. Master them, and you control how every part connects!

What Are Relationship Files?​

Why Relationships Exist​

The Problem They Solve​

The Solution: Indirect References​

Relationship File Structure​

Two Types of Relationship Files​

1. Package Relationships (/_rels/.rels)​

2. Part Relationships (/word/_rels/*.xml.rels)​

Anatomy of a Relationship​

1. Id Attribute - The Reference Key​

2. Type Attribute - What Kind of Resource​

3. Target Attribute - Where to Find It​

4. TargetMode Attribute - Internal or External​

Common Relationship Types in Detail​

Images​

Hyperlinks​

Headers and Footers​

Styles​

Relationship ID Management​

How IDs Are Generated​

Manual ID Assignment (Advanced)​

Relationship File Flow​

Common Relationship Errors​

Error 1: Missing Relationship​

Error 2: Wrong Target Path​

Error 3: Duplicate IDs​

Error 4: Missing TargetMode for External Links​

Relationship Files in AppraiSys​

When Images Are Added​

When Documents Are Merged​

Visualizing Relationships​

Practical Example: Adding an Image​

Step-by-Step Process​

Debugging Relationship Issues​

Using OpenXML SDK Productivity Tool​

Manual Inspection​

Using Validator​

Quick Reference: Relationship Types​

Next Steps​

Test Your Understanding​

Question 1​

Question 2​

Question 3​

What Are Relationship Files?

Why Relationships Exist

The Problem They Solve

The Solution: Indirect References

Relationship File Structure

Two Types of Relationship Files

1. Package Relationships (`/_rels/.rels`)

2. Part Relationships (`/word/_rels/*.xml.rels`)

Anatomy of a Relationship

1. Id Attribute - The Reference Key

2. Type Attribute - What Kind of Resource

3. Target Attribute - Where to Find It

4. TargetMode Attribute - Internal or External

Common Relationship Types in Detail

Images

Hyperlinks

Headers and Footers

Styles

Relationship ID Management

How IDs Are Generated

Manual ID Assignment (Advanced)

Relationship File Flow

Common Relationship Errors

Error 1: Missing Relationship

Error 2: Wrong Target Path

Error 3: Duplicate IDs

Error 4: Missing TargetMode for External Links

Relationship Files in AppraiSys

When Images Are Added

When Documents Are Merged

Visualizing Relationships

Practical Example: Adding an Image

Step-by-Step Process

Debugging Relationship Issues

Using OpenXML SDK Productivity Tool

Manual Inspection

Using Validator

Quick Reference: Relationship Types

Next Steps

Test Your Understanding

Question 1

Question 2

Question 3