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 extension.driver.php
files.
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:
The root 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:
released
in the wild and I actively support itexperimental
this is just a prototype, use at your own riskunmaintained
I once supported this, but now I'm too busy or don't want to maintain itdeprecated
don't use this: it is no longer needed or another extension is preferredThe 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).
A short 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.
A mandatory 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 url
element.
The type
attribute should be one of the following:
discuss
to link to a blog post or forum threadhomepage
for a homepage other than Github, e.g. on the Symphony website or your own websitewiki
for wiki-style documentationissues
for a publicly available issue/bug trackerThe 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").
Event
for extensions primarily providing frontend eventsField
for new field typesInterface
if you modify Symphony's UIMembership
for user roles, Symphony users or frontend profilesMultilingual
allowing multilingual contentMultimedia
images, video, uploads or media managementText Formatter
text formatting and WYSIWYG editorsThird Party Integration
such as MailChimp, Basecamp, Google Analytics etcTranslation
backend UI translation ("language packs")Workflow
if the extension provides new or modifies existing Symphony workflowsOther
everything 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 @github
and @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.
The email
and 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 @version
and @date
attributes.
The 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.
Newer 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 @min
and @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 @min
and @max
for every minor or maintenance release for the extension> Just add them when compatibility changes:
release
should mark the range of Symphony versions it works with@max
value of the latest known compatible Symphony version.x
wildcard 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 laterTo collate screenshots and screencasts of your extension, you should use the media
element. Each resource must have a @type
(image
or video
), a @url
to the file and caption text.