Uniword provides comprehensive DOCX verification through a three-layer pipeline that checks ZIP integrity, XML schema compliance, and semantic correctness.

1. CLI Usage 

# Full verification (OPC + semantic)
uniword verify document.docx

# Enable XSD schema validation (slower, thorough)
uniword verify document.docx --xsd

# Machine-readable output
uniword verify document.docx --json
uniword verify document.docx --yaml

# Show all issues including info-level
uniword verify document.docx --verbose

Exit code 0 for valid documents, 1 for invalid.

2. The Three Layers

Layer Checks Examples

OPC Package

ZIP integrity, content types, relationships, part presence

OPC-001 (ZIP opens), OPC-004 (document.xml exists), OPC-006 (relationship targets resolve)

XSD Schema

XML schema validation against bundled XSD files

Namespace-aware validation using 40 bundled XSD schemas from ISO, ECMA, and Microsoft

Word Document

Semantic checks for cross-references, styles, numbering, footnotes, etc.

DOC-001 (undefined style), DOC-020 (footnotePr without footnotes.xml), DOC-040 (duplicate bookmark)

3. Layer 1: OPC Package Validation

The first layer checks the physical package structure:

  • ZIP file can be opened and is not corrupted

  • [Content_Types].xml exists and lists all parts

  • _rels/.rels exists and is well-formed

  • Required parts (word/document.xml) are present

  • All relationship targets resolve to existing parts

4. Layer 2: XSD Schema Validation

The second layer validates XML parts against their schemas:

  • 40+ bundled XSD schemas from ISO, ECMA, and Microsoft

  • Namespace-aware validation with correct prefix resolution

  • Validates word/document.xml, word/styles.xml, docProps/core.xml, and other parts

  • MCE-aware preprocessing (1.4+): each part is preprocessed per its own mc:Ignorable declaration before validation — ignorable-marked attributes (e.g. w14:paraId, w14:textId) and the mc:Ignorable attribute itself are stripped, so real documents no longer drown in false errors for MCE extension content they carry by default. Extension elements are kept; their findings remain classified as MCE-attributable.

XSD validation is opt-in (--xsd flag) because it is slower than the other layers.

5. Layer 3: Semantic Rules

The third layer checks document-level invariants via a single Validation::Engine over Rules::Registry (consolidated in 1.3+):

  • Built-in rule categories: styles, numbering, footnotes, headers, bookmarks, images, tables, fonts, theme, settings

  • New model-level rules: DOC-200 (body required), DOC-201 (bookmark pairing), DOC-202 (bookmark name uniqueness), DOC-203 (empty paragraphs), DOC-204 (tbl requires tblGrid), DOC-205 (tbl requires tblPr)

  • Custom rules can be registered via Uniword::Validation::Rules.register

uniword validate runs the same engine in-memory on a loaded document; uniword verify runs it as the third layer of the package pipeline. Both front-ends share the same Report::ValidationIssue model.

See Semantic Rules for the full list of rule categories.

6. Programmatic Usage 

require 'uniword'

# Three-layer verification
result = Uniword::Verification.verify('document.docx')
puts result.valid?           # => true or false
puts result.issues.count     # => number of issues
result.issues.each do |issue|
  puts "#{issue.code}: #{issue.message}"
end

# With XSD validation
result = Uniword::Verification.verify('document.docx', xsd: true)

# In-memory model rules only (no ZIP, no XSD)
doc = Uniword::DocumentFactory.from_file('document.docx')
issues = Uniword::Validation::Engine.run(
  Uniword::Validation::Rules::ModelContext.new(doc)
)
puts issues.map { |i| "#{i.code}: #{i.message}" }