Classic and JSON packages
This page is for developers and administrators who meet a package in the JSON format, or wonder whether a site package should use it. It answers: what the two formats are, what changes and what does not, and what the package server and the installers expect. The complete specification is The JSON package format; this page only places it in the site package picture.
Contents
- Two serializations of one package
- What differs
- How the kernel tells them apart
- Site packages and the package server
- Converting and validating
- Which one to choose
- Related pages
Two serializations of one package
A package has one model: name, type, version, dependencies, install items, files. That model can be stored in two ways:
- Classic:
package.xmland XML documents (ezcontentclass/class-article.xml,ezcontentobject/contentobjects.xml...). The default, and the format of every package on the package server. - JSON:
package.jsonand a.jsonfile for every document, each one a JSON envelope around the XML element in JsonML, the lossless mapping of XML to JSON arrays.
Because the JSON mirrors the XML element for element, the kernel turns a JSON document back into the same DOM the
XML would give (eZPackage::fetchDOMFromFile()), and every package handler runs unchanged. Everything on
package.xml reference applies to both.
What differs
| Classic | JSON | |
|---|---|---|
| Definition | package.xml | package.json |
| Documents | <name>.xml | the same name with .json |
| Images, templates, extension files, install scripts | as they are | as they are, byte for byte |
| Checksums | MD5 of files in <files> only | SHA-256 of every file, in package.json |
Rich text (ezxmltext) | XML in the document | kept as an XML string, ["#xml", "..."] ([PackageFormatSettings] RawXMLDatatypes[]) |
| Archive name on export | <name>-<version>-<release>.ezpkg | <name>-<version>-<release>.json.ezpkg |
| Archive format | gzip compressed tar | the same |
| Schema | the kernel's reader | share/package/schema/package-v1.json |
| Largest document read | [PackageFormatSettings] MaxDocumentBytes, 64 MB |
How the kernel tells them apart
By content, never by file name:
eZPackage::definitionFilePath()takespackage.xmlwhen there is one, elsepackage.json.- On import, both names are extracted from the top of the archive, so either format imports
(
eZPackage::importUnaudited()). - A document named in the definition by its XML name (
filename="class-article") is read from the.xmlfile, or from the.jsonfile of the same name when there is no XML file. - The package keeps the format it was stored in (
$package->attribute( 'format' ),xmlorjson); an export without a format writes that format.
Site packages and the package server
- Every package in the 6.0.15 folder of the package server is classic: its 44 archives are named
<name>.ezpkgand none is a.json.ezpkg. The source repositories (se7enxweb/sevenx-ezpackage,se7enxweb/cjw_multisite-ezpackage) keeppackage.xmlfiles. - The setup wizard, the kickstarter and
exp:installimport througheZPackage::import(), so they would take a JSON archive as well; the index entry (url) only has to point at it. - A site package's install scripts (
settings/*.php) are payload files and stay PHP in both formats.
Note
ezpm convert converts the documents as they are (expPackageJson::convertDirectory()). An export of a
repository package (ezpm export, Download in the administration) first writes the definition again through
the kernel's writer (exportToArchive()). Before 6.0.15 that writer left out <settings> and the min-version
of <require> items, and the export dropped files at the top of the package (the cjw-*.json side files);
from 6.0.15 on all three are kept (see
package.xml reference). Building site
package archives from their source folder is still the reliable way to publish them.
Converting and validating
From the installation root (./console ezpm ... runs the same commands):
# convert an archive; --to defaults to the other format
php ezpm.php convert mypackage-1.0.0-1.ezpkg mypackage-1.0.0-1.json.ezpkg --to=json
convert into a new directory
php ezpm.php convert mypackage-1.0.0-1.json.ezpkg /path/to/new-directory --to=xml
export a repository package in a chosen format
php ezpm.php export mypackage -d /path/to/dir --format=json
check an archive, a directory or a repository package without importing it
php ezpm.php validate mypackage-1.0.0-1.json.ezpkgvalidate checks the schema, every document as XML, the definition, the documents the items name and the checksums,
and prints PASS or FAIL. In the administration, Download as JSON and Validate are on a package's page, and
the package wizard asks which format a new package is kept in.
Which one to choose
| Situation | Format |
|---|---|
| A site package for the shared package server | classic, like every package there |
| Reviewing content packages in pull requests | JSON reads and diffs better for many people and tools |
| Content written by scripts or AI tools, to be reviewed as drafts | JSON, installed with ezpm install --as-drafts |
| A package for an installation older than the JSON format | classic |
Related pages
- Site package basics
- Site packages: start here
- The JSON package format
- Classic XML and JSON packages: the designer's view
- The .ezpkg file
- Validating a package before publishing
- Contribute your site package
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.