Specification Reference Policy

This document defines the specification reference policy for xlsxrb.

Canonical Specification (Normative)

The primary reference for this library is ECMA-376 (Office Open XML File Formats). Specifically, xlsxrb targets the Transitional version of the specification (Part 4) to ensure maximum compatibility with existing applications such as Microsoft Excel, LibreOffice, and Google Sheets.

Local copies of the ECMA-376 specifications are located in the vendor/docs/ directory: - Part 1: Fundamentals And Markup Language Reference - Part 2: Open Packaging Conventions - Part 3: Markup Compatibility and Extensibility - Part 4: Transitional Migration Features

Supplementary Specifications (Excel Real-world Behavior)

To address gaps between the official ECMA standard and actual implementations in Microsoft Excel, the following Microsoft Open Specifications are used. Note that these files are not bundled in the repository to avoid licensing/redistribution issues; instead, they are referenced via online links and versioned here:

1. [MS-XLSX]: Excel Extensions to OOXML SpreadsheetML Structure

2. Role: Explains Excel-specific extensions, default attributes, and schema extensions.

3. Referenced Version: July 2024 / Version 12.0 (or current release).

4. [MS-OI29500]: Office Implementation Information for ISO/IEC 29500

5. Role: Identifies how Excel actually reads/writes files, including deviations and compatibility behaviors.

6. Referenced Version: July 2024 / Version 12.0 (or current release).

7. [MS-OFFCRYPTO]: Office Document Cryptography Structure

8. Role: Provides details on encryption, passwords, and hashing algorithms used for document/sheet protection (Agile Encryption and Standard Encryption).

9. Referenced Version: July 2024 / Version 12.0 (or current release).

10. [MS-CFB]: Compound File Binary File Format

11. Role: Container format (OLE structured storage) wrapping encrypted Office documents (EncryptionInfo and EncryptedPackage streams).

12. Referenced Version: July 2024 / Version 14.0 (or current release).

ISO/IEC 29500 Note

ISO/IEC 29500 is contents-wise equivalent to ECMA-376. However, ISO/IEC 29500 requires paid purchase in general, whereas ECMA-376 is freely available. Therefore, we primarily cite ECMA-376 sections.

Source Attribution Policy

When implementing features or fixing bugs that depend on specific behaviors defined in these specifications, developers should: 1. Reference the specific part, section, or page number in code comments (e.g., # Reference: ECMA-376 Part 1, Section 18.3.1.73). 2. Update the mapping table below to maintain a central registry of implemented standard behaviors.

Implementation Specification Mapping Table