The Extension Metadata Schema is a way for Symphony extension developers to document extensions in a structured manner, doing away with ad-hoc conventions in readme files and proprietary arrays in
All extensions should include an
extension.meta.xml file in the root, alongside the existing extension driver. This standard is intended to eventually replace the
about() array presently found in every extension's PHP driver file.
The schema aims to:
This is the most basic extension meta file implementing only the required elements. Every meta file must include the these elements as a minimum:
There are two tools to make generating the XML files easier:
extension element must have an
@id attribute with a value of the folder name of the extension. This must match the Github repository name.
The element should specify the version of this schema to which it adheres. If the
@xmlns attribute is missing, it is assumed that the XML is written against the earliest version of this schema (v1.0).
Similarly the element should specify the status of extension. If the
@status attribute is missing a value of
released is assumed. Possible values:
releasedin the wild and I actively support it
experimentalthis is just a prototype, use at your own risk
unmaintainedI once supported this, but now I'm too busy or don't want to maintain it
deprecateddon't use this: it is no longer needed or another extension is preferred
name element must include the full extension name. Do not include the extension type (e.g. “Field: …”) in this element. Use the
type element instead (see later).
description must be included, which briefly describes the extension functionality. It should be limited to about 200 characters and should be in English, lthough additional languages can be included using the
@lang attribute. The attribute is not required for English descriptions.
repo element contains a link to the repository landing page. At this time, the
@type must be
github and the URL must be the repository browser page and not the git clone URL (e.g. git://...).
Additional extension links can be added with the
type attribute should be one of the following:
discussto link to a blog post or forum thread
homepagefor a homepage other than Github, e.g. on the Symphony website or your own website
wikifor wiki-style documentation
issuesfor a publicly available issue/bug tracker
The extension type is indicated by a list of
type elements which contain the full name of the type. The value should be one of the following, although you can specify your own should you wish. Any new types must be singular (e.g. "Dashboard Panel" and not plural "Dashboard Panels").
Eventfor extensions primarily providing frontend events
Fieldfor new field types
Interfaceif you modify Symphony's UI
Membershipfor user roles, Symphony users or frontend profiles
Multilingualallowing multilingual content
Multimediaimages, video, uploads or media management
Text Formattertext formatting and WYSIWYG editors
Third Party Integrationsuch as MailChimp, Basecamp, Google Analytics etc
Translationbackend UI translation ("language packs")
Workflowif the extension provides new or modifies existing Symphony workflows
Othereverything else (or specify your own type e.g. "Dashboard Panel")
Extension developers are listed within the
authors element. At least one
author element must be present, and it must contain a
name element with both
@symphony attributes containing the author’s usernames on these services. If a developer has a Twitter account they are encouraged to add it here also.
If multiple authors are responsible for a project, the first author listed is assumed to be the primary maintainer.
website elements are optional.
If your extension depends on one or many other extensions, you should include a
dependency element. If present, this must include the path (
@id) of the related extension, and should include the required version if it is known.
Each important release of your extension can be documented in the
releases list. Every time you make a milestone release, or need to indicate backwards incompatibility with Symphony you should document the release here. Every extension must include at least one
release element which must have both
release element can be self-closing (no text value), but if you would like to include release notes as a changelog, it should go inside this element. This content must be XML-safe, so wrap with
<![CDATA[...]]> if necessary. It should be formatted with Markdown if possible.
release elements should appear first in the
releases list, thereby making the file as human-readable as possible (latest at the top). However, parsers should sort these elements based on the
@date just in case.
To mark Symphony compatibility, you should use
@max attributes. These specify the minimum and maximum versions of Symphony that this extension will work with. Both are optional.
There is no need to repeat the
@max for every minor or maintenance release for the extension> Just add them when compatibility changes:
releaseshould mark the range of Symphony versions it works with
@maxvalue of the latest known compatible Symphony version
.xwildcard syntax if necessary e.g.
max="2.2.x"marks the extension as compatible with any Symphony version in the 2.2.x chain, but not Symphony 2.3 or later
To collate screenshots and screencasts of your extension, you should use the
media element. Each resource must have a
@url to the file and caption text.