Quick Reference Cheatsheet

🚨 THE BIG THREE (Never Do This!)

❌ 1. Text Without Run

<!-- WRONG -->
<w:p>
  <w:t>Text</w:t>
</w:p>

<!-- CORRECT -->
<w:p>
  <w:r><w:t>Text</w:t></w:r>
</w:p>

❌ 2. Table Inside Run

<!-- WRONG -->
<w:r>
  <w:tbl>...</w:tbl>
</w:r>

<!-- CORRECT -->
<w:body>
  <w:tbl>...</w:tbl>
</w:body>

❌ 3. SDT Inside Run

<!-- WRONG -->
<w:r>
  <w:sdt>...</w:sdt>
</w:r>

<!-- CORRECT (Block SDT) -->
<w:body>
  <w:sdt>...</w:sdt>
</w:body>

<!-- OR (Inline SDT) -->
<w:p>
  <w:sdt>
    <w:sdtContent>
      <w:r><w:t>Text</w:t></w:r>
    </w:sdtContent>
  </w:sdt>
</w:p>

Element Hierarchy

w:document
  └─ w:body
      ├─ w:p (paragraph)
      │   ├─ w:pPr (properties)
      │   └─ w:r (run)
      │       ├─ w:rPr (properties)
      │       └─ w:t (text)
      │
      ├─ w:tbl (table)
      │   ├─ w:tblPr (properties)
      │   ├─ w:tblGrid (grid definition)
      │   └─ w:tr (row)
      │       ├─ w:trPr (properties)
      │       └─ w:tc (cell)
      │           ├─ w:tcPr (properties)
      │           └─ w:p (REQUIRED)
      │
      └─ w:sdt (content control, block-level)
          ├─ w:sdtPr (properties)
          └─ w:sdtContent (content)

Unit Conversions

Unit	Conversion	Example
Twips → Points	Divide by 20	1440 twips = 72 pt (1 inch)
Half-points → Points	Divide by 2	w:sz="24" = 12pt
EMUs → Points	Divide by 12700	914400 EMUs = 72 pt (1 inch)
Percentage	5000 = 100%	w:w="2500" = 50%
Inches → Twips	Multiply by 1440	1 inch = 1440 twips
Inches → Points	Multiply by 72	1 inch = 72 points

Common Elements

Paragraph

<w:p>
  <w:pPr>
    <w:pStyle w:val="Normal"/>
    <w:jc w:val="center"/>
    <w:spacing w:before="120" w:after="120"/>
  </w:pPr>
  <w:r>
    <w:rPr>
      <w:b/>
      <w:sz w:val="24"/>
    </w:rPr>
    <w:t>Text</w:t>
  </w:r>
</w:p>

Table

<w:tbl>
  <w:tblPr>
    <w:tblW w:w="5000" w:type="pct"/>
  </w:tblPr>
  <w:tblGrid>
    <w:gridCol w:w="3000"/>
  </w:tblGrid>
  <w:tr>
    <w:tc>
      <w:tcPr>
        <w:tcW w:w="3000" w:type="dxa"/>
      </w:tcPr>
      <w:p>...</w:p>
    </w:tc>
  </w:tr>
</w:tbl>

Content Control (Block)

<w:sdt>
  <w:sdtPr>
    <w:tag w:val="FieldName"/>
    <w:alias w:val="Display Name"/>
  </w:sdtPr>
  <w:sdtContent>
    <w:p>...</w:p>
  </w:sdtContent>
</w:sdt>

Text Formatting

Property	XML	Code
Bold	`<w:b/>`	`new Bold()`
Italic	`<w:i/>`	`new Italic()`
Underline	`<w:u w:val="single"/>`	`new Underline { Val = UnderlineValues.Single }`
Font	`<w:rFonts w:ascii="Arial"/>`	`new RunFonts { Ascii = "Arial" }`
Font Size	`<w:sz w:val="24"/>`	`new FontSize { Val = "24" }` (12pt)
Color	`<w:color w:val="FF0000"/>`	`new Color { Val = "FF0000" }`
Highlight	`<w:highlight w:val="yellow"/>`	`new Highlight { Val = HighlightColorValues.Yellow }`

Paragraph Formatting

Property	XML	Code
Alignment	`<w:jc w:val="center"/>`	`new Justification { Val = JustificationValues.Center }`
Before Spacing	`<w:spacing w:before="240"/>`	`new SpacingBetweenLines { Before = "240" }`
After Spacing	`<w:spacing w:after="120"/>`	`new SpacingBetweenLines { After = "120" }`
Line Spacing	`<w:spacing w:line="276" w:lineRule="auto"/>`	`new SpacingBetweenLines { Line = "276", LineRule = LineSpacingRuleValues.Auto }`
Left Indent	`<w:ind w:left="720"/>`	`new Indentation { Left = "720" }`
First Line Indent	`<w:ind w:firstLine="360"/>`	`new Indentation { FirstLine = "360" }`

Table Properties

Property	XML	Code
Width (%)	`<w:tblW w:w="5000" w:type="pct"/>`	`new TableWidth { Width = "5000", Type = TableWidthUnitValues.Pct }`
Width (abs)	`<w:tblW w:w="5000" w:type="dxa"/>`	`new TableWidth { Width = "5000", Type = TableWidthUnitValues.Dxa }`
Alignment	`<w:jc w:val="center"/>`	`new TableJustification { Val = TableRowAlignmentValues.Center }`
Cell Span	`<w:gridSpan w:val="2"/>`	`new GridSpan { Val = 2 }`
V-Merge Start	`<w:vMerge w:val="restart"/>`	`new VerticalMerge { Val = MergedCellValues.Restart }`
V-Merge Continue	`<w:vMerge w:val="continue"/>`	`new VerticalMerge { Val = MergedCellValues.Continue }`
Can't Split	`<w:cantSplit/>`	`new CantSplit()`

Border Styles

new TableBorders(
    new TopBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
    new BottomBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
    new LeftBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
    new RightBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
    new InsideHorizontalBorder { Val = BorderValues.Single, Size = 4, Color = "000000" },
    new InsideVerticalBorder { Val = BorderValues.Single, Size = 4, Color = "000000" }
)

Border Values:

Single - Single line
Double - Double line
Dotted - Dotted line
Dashed - Dashed line
None - No border

Size: Eighths of a point (4 = 0.5pt, 8 = 1pt)

Namespaces

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;  // w:
using DocumentFormat.OpenXml.Drawing;         // a:
using DocumentFormat.OpenXml.Drawing.Wordprocessing;  // wp:
using DocumentFormat.OpenXml.Drawing.Pictures;  // pic:

Prefix	Namespace	Purpose
`w:`	WordprocessingML	Core document elements
`r:`	Relationships	References between parts
`wp:`	Drawing WordprocessingML	Inline/anchored drawings
`pic:`	Picture	Images
`a:`	Drawing	Graphic properties
`v:`	VML	Legacy shapes

OOXML ↔ SFDT Quick Mapping

OOXML	SFDT	Notes
`w:p`	`block` with `inlines`	Paragraph
`w:r` + `w:t`	`inline` with `text`	Text run
`w:tbl`	`table`	Table
`w:tr`	`row`	Table row
`w:tc`	`cell`	Table cell
`w:pPr`	`paragraphFormat`	Paragraph properties
`w:rPr`	`characterFormat`	Character properties
`w:sz` (half-pts)	`fontSize` (pts)	Font size: divide by 2
Spacing (twips)	Spacing (pts)	Divide by 20
`w:drawing`	`imageString` (base64)	Image

Common Code Patterns

Create Document

using (var doc = WordprocessingDocument.Create(
    filepath, WordprocessingDocumentType.Document))
{
    var mainPart = doc.AddMainDocumentPart();
    mainPart.Document = new Document();
    var body = mainPart.Document.AppendChild(new Body());
    
    // Add content
    
    mainPart.Document.Save();
}

Add Paragraph

var para = new Paragraph();
var run = new Run();
run.AppendChild(new Text("Hello World"));
para.AppendChild(run);
body.AppendChild(para);

Add Formatted Text

var run = new Run();
var runProps = new RunProperties(
    new Bold(),
    new FontSize { Val = "28" },
    new Color { Val = "FF0000" }
);
run.AppendChild(runProps);
run.AppendChild(new Text("Bold Red Text"));

Create Table Cell

var cell = new TableCell();
cell.AppendChild(new TableCellProperties(
    new TableCellWidth { Width = "3000", Type = TableWidthUnitValues.Dxa }
));
var para = new Paragraph(new Run(new Text("Cell content")));
cell.AppendChild(para);

Validation

Open XML SDK Tool

Download from GitHub releases
Open DOCX file
Click "Validate"
Review errors

Programmatic Validation

using (var doc = WordprocessingDocument.Open("file.docx", false))
{
    var validator = new OpenXmlValidator();
    var errors = validator.Validate(doc);
    
    foreach (var error in errors)
    {
        Console.WriteLine($"{error.Path}: {error.Description}");
    }
}

File Structure

document.docx (ZIP)
├─ [Content_Types].xml
├─ _rels/
│   └─ .rels
├─ word/
│   ├─ document.xml          ← Main content
│   ├─ styles.xml            ← Styles
│   ├─ numbering.xml         ← Lists
│   ├─ settings.xml
│   ├─ fontTable.xml
│   ├─ _rels/
│   │   └─ document.xml.rels ← Relationships
│   └─ media/
│       ├─ image1.png
│       └─ image2.jpg
└─ docProps/
    ├─ app.xml
    └─ core.xml

AppraiSys Specific

Default Styles

Normal - Base paragraph style
Heading1 - 16pt bold, centered
Heading2 - 14pt bold, left
NormalTable - Standard table
PropertyImagesTable - Photo gallery table
ImageLineSpacing1_15 - For image paragraphs

Standard Measurements

Font size: 11pt (22 half-points)
Line spacing: 1.15 (276 twips)
Cell margins: 108 twips left/right, 0 top/bottom
Page margins: 1 inch (1440 twips)

Content Control Tags

PropertyAddress
PropertyType
SubjectPropertyInfo
ComparablesTable
PropertyPhotos

Debugging Tips

Document Won't Open

Rename .docx to .zip
Extract contents
Check word/document.xml for XML errors
Use OpenXML SDK tool

Images Missing

Check /word/media/ folder exists
Check document.xml.rels has image relationships
Verify relationship IDs match

Formatting Lost

Check styles.xml exists
Verify style IDs match in document.xml
Ensure w:pStyle or w:rStyle references valid style

Error Messages

Error	Cause	Fix
"Element X cannot be child of Y"	Wrong nesting	Check hierarchy rules
"Required element missing"	Missing required child	Add required element
"Invalid attribute value"	Wrong value type	Check valid values
"Relationship not found"	Missing .rels entry	Add relationship

Quick Formulas

Points to Twips:    points × 20
Twips to Points:    twips ÷ 20
Half-pts to Points: halfPoints ÷ 2
Points to Half-pts: points × 2
EMUs to Points:     emus ÷ 12700
Inches to Twips:    inches × 1440
Inches to Points:   inches × 72
Percentage (width): (percent ÷ 100) × 5000

Resources

💡 Print this page and keep it at your desk for quick reference!

🚨 THE BIG THREE (Never Do This!)​

❌ 1. Text Without Run​

❌ 2. Table Inside Run​

❌ 3. SDT Inside Run​

Element Hierarchy​

Unit Conversions​

Common Elements​

Paragraph​

Table​

Content Control (Block)​

Text Formatting​

Paragraph Formatting​

Table Properties​

Border Styles​

Namespaces​

OOXML ↔ SFDT Quick Mapping​

Common Code Patterns​

Create Document​

Add Paragraph​

Add Formatted Text​

Create Table Cell​

Validation​

Open XML SDK Tool​

Programmatic Validation​

File Structure​

AppraiSys Specific​

Default Styles​

Standard Measurements​

Content Control Tags​

Debugging Tips​

Document Won't Open​

Images Missing​

Formatting Lost​

Error Messages​

Quick Formulas​

Resources​

🚨 THE BIG THREE (Never Do This!)

❌ 1. Text Without Run

❌ 2. Table Inside Run

❌ 3. SDT Inside Run

Element Hierarchy

Unit Conversions

Common Elements

Paragraph

Table

Content Control (Block)

Text Formatting

Paragraph Formatting

Table Properties

Border Styles

Namespaces

OOXML ↔ SFDT Quick Mapping

Common Code Patterns

Create Document

Add Paragraph

Add Formatted Text

Create Table Cell

Validation

Open XML SDK Tool

Programmatic Validation

File Structure

AppraiSys Specific

Default Styles

Standard Measurements

Content Control Tags

Debugging Tips

Document Won't Open

Images Missing

Formatting Lost

Error Messages

Quick Formulas

Resources