Extension Metadata Schema v1.0

Background

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:

  • reduce the maintenance burden for developers when updating an extension, by retaining metadata in a single file
  • be human-readable by developers as well as machine-readable by any future parsers
  • be simple enough that new developers can get started quickly, but full-featured enough to cater for more complex dependency, versioning and documentation requirements

Minimal example

This is the most basic extension meta file implementing only the required elements. Every meta file must include the these elements as a minimum:

Authoring and validation

There are two tools to make generating the XML files easier:

  • The generator tool will create a basic XML file based on information found on the extension's page on the main Symphony website. Use this as a starting point, but please double check the data is correct before pushing to your repository.
  • The lint tool validates your XML against the formal XSD schema. This will return any errors such as basic XML validation, as well as missing required fields or bad values.

Element Specification

Root element

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 it
  • experimental this is just a prototype, use at your own risk
  • unmaintained I once supported this, but now I'm too busy or don't want to maintain it
  • deprecated don't use this: it is no longer needed or another extension is preferred

Name

The 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

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 thread
  • homepage for a homepage other than Github, e.g. on the Symphony website or your own website
  • wiki for wiki-style documentation
  • issues for a publicly available issue/bug tracker

Types

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").

  • Event for extensions primarily providing frontend events
  • Field for new field types
  • Interface if you modify Symphony's UI
  • Membership for user roles, Symphony users or frontend profiles
  • Multilingual allowing multilingual content
  • Multimedia images, video, uploads or media management
  • Text Formatter text formatting and WYSIWYG editors
  • Third Party Integration such as MailChimp, Basecamp, Google Analytics etc
  • Translation backend UI translation ("language packs")
  • Workflow if the extension provides new or modifies existing Symphony workflows
  • Other everything else (or specify your own type e.g. "Dashboard Panel")

Authors

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.

Dependencies

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.

Changelogs and Compatibility

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:

  • The first release should mark the range of Symphony versions it works with
  • If your extension does not work with a new major Symphony version, then the latest extension release should be given a @max value of the latest known compatible Symphony version
  • Use the .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 later

Media

To 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.