OpenDocument (ODF 1.3; 1.2 and the 1.4 drafts read)

OpenDocument files have a native layer in the core package (RecursiveAI.OneDocument.Odf) that the text, spreadsheet and presentation units share, and a conversion into and out of the word-processing hub in .Documents. This note covers both; spreadsheets and presentations add their own conversions on the same package layer.

The package layer (core)

using var pkg = OdfPackage.Open(ByteSource.FromFile("a.odt"));
MarkupNode body = pkg.Body;                         // lossless markup tree of content.xml
OdfStyle? s = pkg.Styles.Find("paragraph", "Heading_20_1");
string? size = pkg.Styles.Resolve(s!, "text-properties", OdfNamespaces.Fo, "font-size");
pkg.SetEntry("Pictures/a.png", bytes, "image/png"); // added to the manifest
pkg.WriteTo(stream);                                // zip; pkg.WriteFlatTo(stream) for a flat file

Round trip. A package written without edits copies each entry raw (the stored bytes, CRC, method and time, never recompressed). A part whose markup tree was edited is written from the tree, which keeps unknown elements, attributes, prefixes, comments and order. The manifest is written again only when an entry was added, removed or retyped. A written package starts with an uncompressed mimetype entry with no extra field, as Part 3 asks, then the other entries in their order. A flat file writes its own tree. WriteFlatTo on a zip package merges the four parts under one office:document (namespace declarations united, font faces and automatic styles de-duplicated) and inlines packaged pictures as base64 office:binary-data. Flat → zip at the package level is not implemented; the hub converts through the model.

Tolerant reading. Missing or misplaced mimetype, a missing or damaged manifest, manifest entries without a file and damaged zip directories are repaired and reported (defects.md). A part that is not well-formed XML, or whose root is wrong, raises its typed error when first used. Entry names that are empty, absolute or contain .. are dropped. Encrypted packages (any manifest:encryption-data) raise OfficeUnsupportedException; ODF encryption and signatures are not implemented. The limits object passes through: part count, part size, expansion ratio, XML depth, no DTDs.

Presentations (Presentation)

ODP, OTP and FODP convert into the presentation hub and out of it the same way as text: see odp.md.

Text documents (Document)

Document.Open accepts ODT, OTT and FODT by content (the mimetype entry or office:mimetype), never the extension. The file is converted to an in-memory DOCX package, and the hub wraps it like any DOCX; Document.Format stays Odt, Ott or Fodt, and Document.ImportLoss lists what did not map. SaveAs("x.odt" | "x.ott" | "x.fodt") (or with an explicit OfficeFormat) writes OpenDocument from the hub, and Document.ExportLoss lists what it could not carry. Office.Open, Office.ExtractText and Office.Convert reach the formats through the registry. Direct entry points: OpenDocumentText.ToPackage for the DOCX package.

Untouched files. An ODT/OTT/FODT read and saved in its own format without an edit writes the bytes it was read from. Any edit reaches the exporter, which writes a valid package of its own from the hub; a save to another OpenDocument format goes through the exporter too.

Reading (ODF → hub)

Reported as losses (loss.*): unmapped-markup.<element>, shapes (lines, rectangles, custom shapes, groups), embedded-objects (formulas, charts and OLE objects keep only a preview picture), forms, linked-images (never fetched), pictures (missing or undecodable data), picture-cropping, ruby (the text above the base), formatting-revisions, column-breaks, page-break-after, table-page-break, section-columns (text sections with columns), index-fields (indexes other than contents and alphabetical), page-background, formulas (the MathML symbols are kept as text), content-controls. The text of a rectangle, custom shape or group is kept in a text box; the geometry is dropped (shapes).

Writing (hub → ODF)

The exporter reads the hub's markup tree and writes content.xml, styles.xml and meta.xml (settings.xml is not written). Styles map back by the same names; direct formatting becomes automatic styles (de-duplicated); lists become list styles (WWNum<n>, one per w:num; a list that resumes after other content sets text:continue-numbering); tables keep spans, vertical merges, header rows, widths, borders (from the cell, the table and its table style), shading, margins and heights; each w:sectPr becomes a page layout and a master page with its headers and footers, and the first block of a later section names its master page; notes, comments with ranges, bookmarks, hyperlinks, fields (page number, page count, date, time, document properties, references, sequences, TOC), tracked insertions and deletions, pictures and text boxes (inline and anchored) are written. A page or column break inside a paragraph splits it, because ODF has no inline page break.

Reported as losses: content-controls (read through), equations (written as linear text), fields (other fields keep their last result), charts, smartart, shapes, pictures (linked or missing data), ole-objects, ruby, continuous-section-page-change.

Checks

• Written ODT, OTT and FODT validate against the OASIS ODF 1.3 RelaxNG schema with Jing (tools/validate/validate_odf.py; ID/IDREF checking is switched off because Jing rejects the schema's own ID typing) and open in LibreOffice headless, which converts them to PDF and DOCX.
• Text of the DOCX → ODT → hub round trip equals the source's; files LibreOffice writes from the same DOCX read into the hub with the same text (testdata/odf).
• Converted DOCX validates against the ECMA-376 Transitional schemas.
• Fuzz targets odfpkg (the package layer) and odt (the conversion in both directions).