XAR Format Specifications
Reference
A "XWiki Archive" (XAR) file is a ZIP archive with the ".xar" extension. It holds one XML file per exported Page, whose elements are documented separately, plus a "package.xml" descriptor at the root of the archive that names the package and lists its entries.
The descriptor below is the one produced by exporting content in XAR format, here the two test Pages of the Sandbox, each of which has one translation:
<?xml version='1.0' encoding='UTF-8'?>
<package>
<infos>
<name>Sandbox</name>
<description>Two Pages of the Sandbox</description>
<licence>LGPL 2.1</licence>
<author>XWiki.Admin</author>
<version>1.0</version>
<backupPack>false</backupPack>
<preserveVersion>false</preserveVersion>
</infos>
<files>
<file defaultAction="0" language="">Sandbox.TestPage2</file>
<file defaultAction="0" language="de">Sandbox.TestPage2</file>
<file defaultAction="0" language="">Sandbox.TestPage3</file>
<file defaultAction="0" language="de">Sandbox.TestPage3</file>
</files>
</package>Package Information
The package information is held by an infos element, inside the root package element.
| Element | Description |
|---|---|
| name | The name of the package, taken from the "File name" export setting. A whole-wiki export left unnamed uses backup, a partial one export. |
| description | The package description, displayed when importing the package. |
| licence | The license the packaged content is published under, for example LGPL 2.1. The element uses the British spelling, and so does the export URL parameter. |
| author | The wiki author of the package. When the package is imported as a backup pack, this author is kept as the last author of the imported Pages. |
| version | The version of the package, which is what tracks the changes made to its content. |
| backupPack | true when the export was made as a backup package. The import decides whether to honor it, so the choice can still be changed at import time. |
| preserveVersion | true when the history of each Page is meant to be part of its XML. An export sets it when either "Backup package" or "With history" is selected, so a backup package exported without history carries true while each of its Pages holds a single version. |
| extensionId | Written only when the XAR is an Extension. The Extension Manager then matches the archive against its Extension database and runs the version checks when installing it. |
Files
The files element holds one file entry per exported Page, and one further entry per translation. The value of the element is the Page reference relative to the wiki, as in Sandbox.TestPage2.
| Attribute | Description |
|---|---|
| language | The language of the Page, empty for the default one. A translation is listed under the same reference with its own locale. |
| type | The entry type, which decides whether the Page may be edited or deleted and how it behaves when the Extension shipping it is upgraded. It is written only when the entry has a type, which in practice means the archive is an Extension. Extensions can contribute new types to the four standard ones. |
| defaultAction | Deprecated, and part of an older import mechanism: the action to apply to the Page when the archive is imported. Both the export and the Maven XAR plugin write 0.
|
Descriptor Changes
Unlike a Page file, the descriptor carries no version attribute, so what says which version of the format an archive follows is the format version of its Page files. The descriptor itself has gained one attribute since the format was introduced:
| Element or attribute | Written since | Change |
|---|---|---|
| The type attribute of file | XWiki 10.3 | The entry type, which is how an Extension says what may be done to each of its Pages. |
FAQ
How is the package information filled in?
The name, description, author, license and version come from the settings of the XAR export, and can also be set with URL parameters.
Is the "package.xml" file required?
No. An import reads every XML entry of the archive and takes each Page's reference from the entry itself, so an archive with no descriptor still imports; what it loses is the package information and the per-entry attributes.
Can a XAR file be changed by hand?
Yes, it is an ordinary ZIP archive, so it can be unpacked, edited and repacked. See Customize a XAR File.
More
To find more about the current topic, you can search or use the table below and filter the columns to narrow your choices.
