An ESEF report package is a ZIP archive containing your iXBRL document and supporting files in a specific structure. Getting this structure wrong causes immediate validation failures. This guide explains every component of a valid report package.
Key Takeaways
- Report packages must follow the XBRL Report Package specification
- META-INF folder structure is strictly enforced
- File naming conventions affect validation
- UTF-8 encoding without BOM is required
- Embedded taxonomies have specific location rules
Package Structure Overview
A valid ESEF report package contains:
report-2025.zip
├── META-INF/
│ ├── catalog.xml
│ ├── reports.json
│ └── taxonomyPackage.xml
├── reports/
│ └── ifrs-report-2025.xhtml
└── taxonomy/ (optional)
└── extension.xsd
The top-level ZIP must contain META-INF and reports folders. Taxonomy embedding is optional but recommended for extension elements.
META-INF Folder
The META-INF folder contains package metadata:
• catalog.xml - XML catalog for URI resolution
• reports.json - Report metadata (required)
• taxonomyPackage.xml - Taxonomy package descriptor
The reports.json file must list all reports in the package with their entry points and document types.
Reports Folder
The reports folder contains your iXBRL documents:
• Primary XHTML file with iXBRL markup
• Linked CSS stylesheets (if any, must be in same folder)
• Image files referenced by the report
All files must use UTF-8 encoding. External file references must be relative paths within the package.
Taxonomy Embedding
When embedding extension taxonomy: Place XSD and linkbase files in a taxonomy subfolder. Update catalog.xml with rewrite rules. Ensure all schemaLocation references resolve correctly within the package.
Common Mistakes
Avoid these frequent packaging errors:
• Missing or empty META-INF folder
• Incorrect reports.json format
• Absolute paths in file references
• BOM characters in UTF-8 files
• Wrong ZIP compression method
• Extra top-level folders
Use a dedicated packaging tool or pre-validated template to avoid structural issues.
Checklist
- META-INF folder exists at ZIP root
- reports.json is valid JSON
- All file paths are relative
- Files are UTF-8 without BOM
- ZIP uses DEFLATE compression
- No unexpected top-level folders
- Package validates with ESEF conformance suite