Skip to the content
Documentation
Help Start
Reading in:
  • German: 9,090 of 9,090 pages
About the help in other languages
All help pages

Classic and JSON packages

The two storage formats of an Exponential package - classic package.xml and JSON package.json - what differs, how the kernel tells them apart, what this means for site packages and the package server, and how to convert…

Download as PDF

Address: https://doc.exponential.earth/exphelp/viewer/help/site-packages/basics/classic-and-json-packages.md

On this page

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

  1. Two serializations of one package
  2. What differs
  3. How the kernel tells them apart
  4. Site packages and the package server
  5. Converting and validating
  6. Which one to choose
  7. 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.xml and XML documents (ezcontentclass/class-article.xml, ezcontentobject/contentobjects.xml ...). The default, and the format of every package on the package server.
  • JSON: package.json and a .json file 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

ClassicJSON
Definitionpackage.xmlpackage.json
Documents<name>.xmlthe same name with .json
Images, templates, extension files, install scriptsas they areas they are, byte for byte
ChecksumsMD5 of files in <files> onlySHA-256 of every file, in package.json
Rich text (ezxmltext)XML in the documentkept as an XML string, ["#xml", "..."] ([PackageFormatSettings] RawXMLDatatypes[])
Archive name on export<name>-<version>-<release>.ezpkg<name>-<version>-<release>.json.ezpkg
Archive formatgzip compressed tarthe same
Schemathe kernel's readershare/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() takes package.xml when there is one, else package.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 .xml file, or from the .json file of the same name when there is no XML file.
  • The package keeps the format it was stored in ($package->attribute( 'format' ), xml or json); 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>.ezpkg and none is a .json.ezpkg. The source repositories (se7enxweb/sevenx-ezpackage, se7enxweb/cjw_multisite-ezpackage) keep package.xml files.
  • The setup wizard, the kickstarter and exp:install import through eZPackage::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.ezpkg

validate 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

SituationFormat
A site package for the shared package serverclassic, like every package there
Reviewing content packages in pull requestsJSON reads and diffs better for many people and tools
Content written by scripts or AI tools, to be reviewed as draftsJSON, installed with ezpm install --as-drafts
A package for an installation older than the JSON formatclassic

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.

Something wrong on this page? Report an error

Documentation license

This documentation is free documentation, licensed under the GNU Free Documentation License 1.3 or later.

Exponential Copyright © 1998-2026 Exponential Foundation and 7x