Required package.xml fields #

This page is for developers who write or edit the package.xml of a site package by hand. It lists what the code refuses a package without, and why, so a package does not fail on the first install that uses it. The meaning of every element is in The package.xml reference; this page is only about what must be there and in what form.

Contents #

1. What every import checks
2. The name
3. Version, release and type
4. The vendor
5. The ezpublish and packaging elements
6. What is not checked
7. A minimal definition that passes
8. Related pages

What every import checks #

Every way of importing a package goes through eZPackage::import() in kernel/classes/ezpackage.php: the setup wizard's download and upload, php ezpm.php import, and package/upload in the administration. It reads the definition and stops when:

The upload page in the administration checks more, before anything is extracted (eZPackageUploadInspector::definition()); see The ezpublish and packaging elements.

The name #

Enforced. eZPackage::isValidName() accepts a name that:

• has only letters of either case (a to z, A to Z), digits 0 to 9, _ and -;
• does not start with -, and is at most 200 characters long;
• so has no space, dot, /, back slash or control character: nothing that could form a path.

The name is the package's directory and is kept as it is, so infoProf and infoprof are two packages on a case-sensitive file system. Packages that eZ Publish 4.x exported with the case of their content class (RSSFeed_content_class, infoProf) import as they are. The package creation wizards still offer a name in lower case letters, digits and _ (the identifier transformation of settings/transform.ini).

The administration upload also applies eZPackageRequestGuard::isSafeName(), which limits the name to 200 characters. The package creation wizard refuses an invalid name with "it can only contain characters in the range a-z, 0-9 and underscore" (kernel/classes/ezpackagecreationhandler.php).

Version, release and type #

Enforced. Since the review of 15 October 2026, eZPackage::parseDOMTree() refuses a definition whose <version><number>, <version><release> or <type value="..."> is not a plain token (eZPackage::isValidDefinitionToken()): empty, or 1 to 64 characters from 0-9 A-Z a-z . _ + -. White space around the value is trimmed first.

What the version should look like is on Version numbers. For a site package the type must also be exactly site, or the setup wizard does not list it (Package types).

The vendor #

Enforced. <vendor> becomes the repository directory under var/storage/packages/, after the urlalias transformation; without a vendor the package goes to local. A vendor that leaves no usable directory name (for example ..) is refused. The shipped packages all say <vendor>7x</vendor>, the value of [RepositorySettings] Vendor in settings/package.ini, and so land in var/storage/packages/7x/.

The ezpublish and packaging elements #

Enforced on package/upload. The upload inspector refuses a definition that has no <ezpublish> element or no <packaging> element with the message "The package.xml of the archive lacks its version or packaging information" (definition_incomplete). It also refuses a root element other than <package> and any DOCTYPE. The setup wizard's own download does not run this check, so a package without them can install through the wizard and still be refused by the upload page.

<ezpublish>
  <version>6.0.15-stable</version>
  <named-version>6.0</named-version>
</ezpublish>
<packaging>
  <timestamp>1705211779</timestamp>
  <host>packages.example.com</host>
</packaging>

<ezpublish> is the name the format has always used for the product version; Exponential keeps it as it is.

What is not checked #

These are read and shown, but nothing refuses a package for lacking them. All of them are conventions of the shipped packages:

The version and is_active attributes on <package> (the shipped packages write version="6.0.15-0" or version="3.5.2") are not read by parseDOMTree(). When the kernel writes a package it puts the format version 3.5.2 (eZPackage::VERSION) there.

A minimal definition that passes #

This passes every check above, including the upload page. It is the floor, not the recommendation: the shipped packages carry everything listed under What is not checked as well.

<?xml version="1.0" encoding="UTF-8"?>
<package version="3.5.2" development="false" install_type="import">
  <name>example_site</name>
  <summary>Example site</summary>
  <vendor>example</vendor>
  <type value="site" />
  <ezpublish>
    <version>6.0.15-stable</version>
    <named-version>6.0</named-version>
  </ezpublish>
  <packaging>
    <timestamp>1791331200</timestamp>
    <host>packages.example.com</host>
  </packaging>
  <version>
    <number>1.0.0</number>
    <release>1</release>
  </version>
</package>

Related pages #

• Documentation requirements for site packages
• The requirements checklist
• The package.xml reference
• Validating a package before publishing
• Contribute your site package
• Site packages: start here
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.