XAR Format Specifications

Last modified by Thomas Mortagne on 2017/01/18 12:00

A XAR file is a ZIP file with extension ".xar" containing an (optional) "package.xml" descriptor file and in which each document (including the document's history, xobjects, attachments, xclass, etc.) is in a XML file.

package.xml

<package>
 <infos>
   <name>Package Name</name>
   <description>A description of the package</description>
   <licence>Some License 2.0</licence>
   <author>XWiki.User</author>
   <extensionId>extension-id</extensionId>
   <version>1.0</version>
   <backupPack>false</backupPack>
 </infos>
 <files>
   <file language="" defaultAction="0">Space.NestedSpace.Page</file>
   <file language="" defaultAction="0">Space.TranslatedPage</file>
   <file language="fr" defaultAction="0">Space.TranslatedPage</file>
 </files>
</package>
  • name: name representing what's contained in the XAR
  • description: more detailed description of the content of the XAR
  • license: can be set to specify under which license this XAR content is published
  • author: Wiki author of this XAR. This is important. When the XAR is going to be imported this is the author that it'll be imported with if the "import as backup pack" option is selected at import time
  • extensionId (optional): if set then this marks the XAR as containing an Extension. Thus when you import it, the Extension Manager will be able to match it with its Extension database and perform versioning verifications.
  • preserveVersion (optional): if set to true then the history is preserved (the history for each page is part of its XML)
  • backupPack: if true it means that the XAR is a backup pack. It's up to the import to decide whether to import it as a backup pack or not but this provides the information that it is a backup pack.
  • files
    • language: the language of the page. The default page content should use an empty string.
    • defaultAction: when applied (which is not very often) this is the default action to apply on the document
      • -1: undefined, its exact interpretation depends on what is reading it
      • 0: overwrite, whatever is in the database should be overwritten. This is what Maven XAR plugin set by default when generating the XAR.
      • 1: skip, skip this document
      • 2: merge, try to merge the document with what's in the database
    • The value inside the file element is the reference of the page, relative to the current wiki (i.e. Space.Page)

Document XML file

Usually the documents files are located in a path where each parent space is a folder (as in Space/NestedSpace/Page.xml) but this is not technically mandatory and parsers won't take the path into account (only what is indicated in the actual document file).

You can see the XML of a document by exporting it and opening the XAR or by using the xpage=xml parameter when on wiki page URL.

<xwikidoc version="1.2" reference="Space.NestedSpace.Page" locale="">
 <web>Space.NestedSpace</web>
 <name>Page</name>
 <language/>
 <defaultLanguage>en</defaultLanguage>
 <translation>0</translation>
 <creator>XWiki.creator</creator>
 <creationDate>946684800000</creationDate>
 <versions>jrcsrevisions</versions>
 <parent>parent</parent>
 <author>XWiki.author</author>
 <customClass>customclass</customClass>
 <contentAuthor>XWiki.contentAuthor</contentAuthor>
 <date>946771200000</date>
 <contentUpdateDate>946857600000</contentUpdateDate>
 <version>1.1</version>
 <title>title</title>
 <defaultTemplate>defaultTemplate</defaultTemplate>
 <validationScript>validationScript</validationScript>
 <comment>comment</comment>
 <minorEdit>false</minorEdit>
 <syntaxId>syntax/1.0</syntaxId>
 <hidden>true</hidden>
 <content>content</content>
 <renderedcontent/>
 <attachment>
   <filename>attachment.txt</filename>
   <versions>jrcsrevisions</versions>
   <author>XWiki.author</author>
   <date>947030400000</date>
   <version>1.1</version>
   <comment>comment</comment>
   <content>AAECAwQFBgcICQ==</content>
   <filesize>10</filesize>
 </attachment>
 <class>
   <name>Space.NestedSpace.Page</name>
   <customClass>customClass</customClass>
   <customMapping>customMapping</customMapping>
   <defaultViewSheet>defaultViewSheet</defaultViewSheet>
   <defaultEditSheet>defaultEditSheet</defaultEditSheet>
   <defaultWeb>defaultWeb</defaultWeb>
   <nameField>nameField</nameField>
   <validationScript>validationScript</validationScript>
   <prop1>
     <disabled>0</disabled>
     <name>prop1</name>
     <number>1</number>
     <numberType>long</numberType>
     <prettyName>Prop1</prettyName>
     <size>30</size>
     <unmodifiable>0</unmodifiable>
     <classType>com.xpn.xwiki.objects.classes.NumberClass</classType>
   </prop1>
 </class>
 <object>
   <name>Space.NestedSpace.Page</name>
   <number>0</number>
   <className>Space.NestedSpace.Page</className>
   <guid>e2167721-2a64-430c-9520-bac1c0ee68cb</guid>
   <class>
     <name>Space.NestedSpace.Page</name>
     <customClass>customClass</customClass>
     <customMapping>customMapping</customMapping>
     <defaultViewSheet>defaultViewSheet</defaultViewSheet>
     <defaultEditSheet>defaultEditSheet</defaultEditSheet>
     <defaultWeb>defaultWeb</defaultWeb>
     <nameField>nameField</nameField>
     <validationScript>validationScript</validationScript>
     <prop1>
       <disabled>0</disabled>
       <name>prop1</name>
       <number>1</number>
       <numberType>long</numberType>
       <prettyName>Prop1</prettyName>
       <size>30</size>
       <unmodifiable>0</unmodifiable>
       <classType>com.xpn.xwiki.objects.classes.NumberClass</classType>
     </prop1>
   </class>
   <property>
     <prop1>1</prop1>
   </property>
 </object>
 <object>
   <name>Space.NestedSpace.Page</name>
   <number>0</number>
   <className>otherclass</className>
   <guid>8eaeac52-e2f2-47b2-87e1-bc6909597b39</guid>
   <class>
     <name>otherclass</name>
     <customClass>customClass2</customClass>
     <customMapping>customMapping2</customMapping>
     <defaultViewSheet>defaultViewSheet2</defaultViewSheet>
     <defaultEditSheet>defaultEditSheet2</defaultEditSheet>
     <defaultWeb>defaultWeb2</defaultWeb>
     <nameField>nameField2</nameField>
     <validationScript>validationScript2</validationScript>
     <prop2>
       <disabled>0</disabled>
       <name>prop2</name>
       <number>1</number>
       <numberType>long</numberType>
       <prettyName>Prop2</prettyName>
       <size>30</size>
       <unmodifiable>0</unmodifiable>
       <classType>com.xpn.xwiki.objects.classes.NumberClass</classType>
     </prop2>
   </class>
   <property>
     <prop2>2</prop2>
   </property>
 </object>
</xwikidoc>
  • xwikidoc: the root XML element
    • version: since 1.1 (XWiki 5.2) the version of the XML format, if no specified then it's 1.0 
    • reference: since 1.2 (XWiki 7.2) the reference of the document
    • locale: since 1.2 (XWiki 7.2) the locale (as defined in Java Locale specifications) of the document
    • web: deprecated since 1.2 (XWiki 7.2) property containing the unique space of the document, not taken into account when reference attribute is set in xwikidoc
    • name: deprecated since 1.2 (XWiki 7.2) the name of the document, not taken into account when reference attribute is set in xwikidoc
    • language: deprecated since 1.2 (XWiki 7.2) the locale (as defined in Java Locale specifications) of the document, not taken into account when reference attribute is set in xwikidoc
  • attachment
    • filename: the name of the file
    • versions: JRCS Archive dump containing the history of the attachment
    • author: the author of the attachment
    • date: epoch date and time
    • version: the version of the attachment
    • comment: the comment associated to the version of the attachment
    • content: the binary content serialized in base64
    • filesize: the size of the attachment in bytes
TODO
Put some documentation for other elements

Changelog

1.3

Generate XML 1.1 (used to be 1.0).

1.2

Support for nested spaces.

  • <web>, <name> and <language> are deprecated (but still produced)
  • new reference and locale attributes in <document> element

1.1

No meaningful change. It's just to mark the difference between the first version of the XML produced by Filter module (1.1) and the XML produced by XWikiDocument#toXML().

New  version attribute in <document> element to indicate the XAR format version (i.e. 1.1 here).

The formatting changed are:

  • order of elements changed a bit
  • the XML is indented
Tags:
Created by Thomas Mortagne on 2015/07/13 10:37
    

Get Connected