OFD (Open Fixed-layout Document)

OFD is a page-description format like PDF: every page has text, vector graphics and images at fixed positions. Unlike PDF it’s a ZIP archive of XML files, close in spirit to XPS. China created it as a domestic alternative to PDF, with built-in support for Chinese commercial cryptography (SM2, SM3, SM4) for signatures, electronic seals and encryption.

In China OFD is the standard format for electronic invoices (fully digitalized e-invoices are issued as OFD, PDF and XML), government documents, electronic archives (OFD-A, GB/T 42133) and many bank and tax records. Outside China it’s rare.

When to use OFD#

• Use when Chinese regulations or a counterparty require it: e-invoices, government submissions, electronic archives.
• Use when you need signatures and seals with Chinese national cryptography (SM2/SM3) that Chinese verification systems accept.
• Avoid for documents shared internationally: most people can’t open OFD. Use PDF, or convert OFD to PDF before sending.
• Avoid when the reader may lack the right fonts: many OFD files reference fonts by name (宋体, 楷体) instead of embedding them, so pages look different on systems without those fonts.

File structure#

An OFD file is a ZIP archive. The root file OFD.xml points to one or more documents; each document has its own folder (Doc_0) with a Document.xml, resources and one folder per page:

OFD.xml                       entry point: document info, path of Document.xml
Doc_0/
  Document.xml                page list, page size, outline, links to resources
  PublicRes.xml               fonts and color spaces shared by pages
  DocumentRes.xml             images and other multimedia
  Pages/
    Page_0/Content.xml        content of page 1: text, paths, images
    Page_1/Content.xml
  Res/                        image files (PNG, JPEG, JBIG2), embedded fonts (TTF, OTF)
  Tpls/Tpl_0/Content.xml      template pages (shared backgrounds)
  Annots/Annotations.xml      annotations, stamps, watermarks
  Attachs/Attachments.xml     file attachments (an e-invoice puts its XML data here)
  Tags/CustomTags.xml         semantic tags linking page objects to data fields
  Signs/Signatures.xml        list of signatures
  Signs/Sign_0/Signature.xml  what is signed (file digests) and the seal position
  Signs/Sign_0/SignedValue.dat  signature value (SES electronic seal or PKCS#7)

All files use the XML namespace http://www.ofdspec.org/2016 with the prefix ofd:. Coordinates and sizes are in millimeters, with the origin at the top-left corner of the page.

OFD.xml#

<ofd:OFD xmlns:ofd="http://www.ofdspec.org/2016" Version="1.0" DocType="OFD">
  <ofd:DocBody>
    <ofd:DocInfo>
      <ofd:DocID>220c5913ebfe4f6e8070dabd3647f157</ofd:DocID>
      <ofd:CreationDate>2020-09-21</ofd:CreationDate>
      <ofd:Creator>OFD R&amp;W</ofd:Creator>
    </ofd:DocInfo>
    <ofd:DocRoot>Doc_0/Document.xml</ofd:DocRoot>
  </ofd:DocBody>
</ofd:OFD>

DocInfo holds metadata (title, author, subject, dates, keywords, custom data). A DocBody can also point to the document’s signatures and versions.

Document.xml#

<ofd:Document xmlns:ofd="http://www.ofdspec.org/2016">
  <ofd:CommonData>
    <ofd:PageArea><ofd:PhysicalBox>0 0 210 297</ofd:PhysicalBox></ofd:PageArea>
    <ofd:PublicRes>PublicRes.xml</ofd:PublicRes>
    <ofd:MaxUnitID>4</ofd:MaxUnitID>
  </ofd:CommonData>
  <ofd:Pages>
    <ofd:Page ID="1" BaseLoc="Pages/Page_0/Content.xml"/>
  </ofd:Pages>
</ofd:Document>

PhysicalBox is the default page size (A4 here: 210 x 297 mm); a page can override it. Every object in the document has a numeric ID, unique within the document; MaxUnitID is the largest one used. Document.xml also holds the outline (bookmarks), the list of annotations, attachments, custom tags and template pages.

Page content#

A page’s Content.xml has one or more layers (Background, Body, Foreground) with graphic objects:

<ofd:Page xmlns:ofd="http://www.ofdspec.org/2016">
  <ofd:Content>
    <ofd:Layer ID="2">
      <ofd:TextObject ID="4" Boundary="31.7 25.4 40.5 5" Font="3" Size="3.0">
        <ofd:TextCode X="0" Y="3" DeltaX="3 3 3 3 1.5 1.5">你好呀，OFD</ofd:TextCode>
      </ofd:TextObject>
    </ofd:Layer>
  </ofd:Content>
</ofd:Page>

Boundary is x y width height in millimeters relative to the page. Text in TextCode is Unicode, which makes text extraction easy, but some generators place glyphs by glyph index (CGTransform) and the Unicode text is then missing or wrong.

Signatures and seals#

Electronic seals (电子印章) are the most common reason OFD is required. Signature.xml lists the files covered by the signature with their digests and the seal’s position on the page; SignedValue.dat holds the signature. Chinese seals use the SES format (GB/T 38540) with SM2 signatures and SM3 digests. Changing any signed file breaks the signature, so tools that edit or convert OFD remove seals or show them only as images.

Converting OFD#

• OFD to PDF: ofdrw (PDFExporter), the ofd-converter tool from zc310/ofd, or easyofd. Expect differences when fonts aren’t embedded, and seals become plain images.
• PDF to OFD: the same libraries; text stays text when the PDF has real text.
• OFD to images: the libraries above, or the ofdrw-viewer command-line tool (PNG, JPEG, WebP).

Specifications and documentation#

• GB/T 33190-2016: the official standard on the national standards portal (Chinese; free online preview)
• ofdrw: the most complete open-source implementation; its source and docs are a practical reference to the standard
• OFD on Chinese Wikipedia

Software that opens OFD files#

Libraries#

Open-source libraries that read and write OFD. See all OFD libraries for a comparison.

Related formats#

• PDF: the international fixed-layout format OFD is modeled after
• XPS: Microsoft’s fixed-layout format, also a ZIP of XML files
• ZIP: the container OFD uses