Manual:Extension.json/Schema: Difference between revisions
Completed schema outline, will add details tomorrow |
|||
Line 186: | Line 186: | ||
== CentralIdLookupProviders == |
== CentralIdLookupProviders == |
||
{{see global|CentralIdLookupProviders|desc=Central ID lookup providers.}} |
{{see global|CentralIdLookupProviders|desc=Central ID lookup providers.}} |
||
== ChangeCredentialsBlacklist == |
|||
== RemoveCredentialsBlacklist == |
|||
== namespaces == |
|||
== TrackingCategories == |
|||
== DefaultUserOption == |
|||
== HiddenPrefs == |
|||
== GroupPermissions == |
|||
== RevokePermissions == |
|||
== GrantPermissions == |
|||
== GrantPermissionsGroups == |
|||
== ImplicitGroups == |
|||
== GroupsAddToSelf == |
|||
== GroupsRemoveFromSelf == |
|||
== AddGroups == |
|||
== RemoveGroups == |
|||
== AvailableRights == |
|||
== ContentHandlers == |
|||
== RateLimits == |
|||
== RecentChangesFlags == |
|||
== MediaHandlers == |
|||
== ExtensionFunctions == |
|||
== ExtensionMessagesFiles == |
|||
== MessageDirs == |
|||
== ExtensionEntryPointListFiles == |
|||
== SpecialPages == |
|||
== AutoloadClasses == |
|||
== Hooks == |
|||
== JobClasses == |
|||
== LogTypes == |
|||
== LogRestrictions == |
|||
== FilterLogTypes == |
|||
== ActionFilteredLogs == |
|||
== LogNames == |
|||
== LogHeaders == |
|||
== LogActions == |
|||
== LogActionsHandlers == |
|||
== Actions == |
|||
== APIModules == |
|||
== APIFormatModules == |
|||
== APIMetaModules == |
|||
== APIPropModules == |
|||
== APIListModules == |
|||
== ValidSkinNames == |
|||
== FeedClasses == |
|||
== SkinOOUIThemes == |
|||
== PasswordPolicy == |
|||
== FileExtensions == |
|||
== callback == |
|||
== config_prefix == |
|||
== ParserTestFiles == |
|||
== ServiceWiringFiles == |
|||
== load_composer_autoloader == |
Revision as of 11:16, 12 January 2017
This page documents the schema used by extension.json. All fields are optional unless otherwise specified. It is currently incomplete.
name
MediaWiki version: | ≥ 1.25 |
This field is required.
This is the extension's canonical name. It should not be changed once set, as it is used as an API for other extensions to detect what is installed.
{
"name": "FooBar"
}
manifest_version
MediaWiki version: | ≥ 1.25 |
This field is required.
This specifies the version of the extension.json file format that is being used. In the future if breaking changes are made to the file format, this number will be incremented to continue supporting extensions using the older format.
1
: 1.25+2
: 1.29+
{
"manifest_version": 1
}
Note: This field is typically placed at the bottom of extension.json files.
namemsg
MediaWiki version: | ≥ 1.25 |
A localized version of the extension's name. Typically the message key is named in the format <name>-extensionname or <name>-skinname.
{
"namemsg": "foobar-extensionname"
}
type
MediaWiki version: | ≥ 1.25 |
The type of extension it is, for sorting on Special:Version. The following types are supported:
api
— API extensionsantispam
— antispam extensionsmedia
— media handlersparserhook
— extensions that modify, add or replace functionality in the MediaWiki parserskin
— extensions that modify skinsspecialpage
— extensions that add special pagesvariable
— make a new variableother
— does something else
Note: custom types can be added by using the ExtensionTypes hook. If not set, the extension will default to the "other" section.
{
"type": "specialpage"
}
author
MediaWiki version: | ≥ 1.25 |
The authors of the extension, may contain wikitext. This can either be a single string, or a list of strings. Additionally, the special string ...
may be used to add a generic "and others" suffix using the version-poweredby-others
message.
version
MediaWiki version: | ≥ 1.25 |
The current version of the extension. Should be in a format supported by composer.
url
MediaWiki version: | ≥ 1.25 |
URL to the extension's "homepage" or documentation. Typically points to https://www.mediawiki.org/wiki/Extension:<extensionname>
.
description
MediaWiki version: | ≥ 1.25 |
Description of the extension, may contain wikitext. Note: it is recommended to use descriptionmsg instead.
descriptionmsg
MediaWiki version: | ≥ 1.25 |
Localization message key for the extension's description, typically in the format <extensionname>-desc. This will override description.
license-name
MediaWiki version: | ≥ 1.25 |
The SPDX license identifier for the license the source code is licensed as. If you create a file named "COPYING" in the extension root directory with the contents of the license, it will also be linked and visible from Special:Version.
requires
MediaWiki version: | ≥ 1.29 |
The requires section allows you to document dependencies on versions of MediaWiki core and other extensions.
{
"requires": {
"MediaWiki": ">= 1.27.0",
"extensions": {
"FooBar": "*",
"Baz": ">= 1.2.3"
}
}
}
You can use any version specifier that composer supports. For MediaWiki, it is best practice to specify a >= for the minimum supported version, unless you know a future version is explicitly broken. For extensions, if they don't have a version specifier set, or don't use a versioning system, use a plain * to indicate any version is acceptable.
config
MediaWiki version: | ≥ 1.25 |
The config section is where you can define configuration settings that sysadmins can change to configure the extension. This section should only be used for things that are configured in LocalSettings.php - if it is supposed to be modified by other extensions, you should use attributes, or if it is just class metadata, use a private static variable or something like that. The format of config changed in manifest_version 2, this documentation covers its usage in manifest_version 1.
A simple example:
{
"config": {
"FooBarUseExtraFeature": false
}
}
This is equivalent to writing $wgFooBarUseExtraFeature = false;
in PHP. Note that the typical "wg" prefix is not included, as that will be added by default. If your settings start with a different prefix like $eg
, you can use the magic _prefix
key:
{
"config": {
"_prefix": "eg",
"FooBarUseExtraFeature": false
}
}
This is now equivalent to writing $egFooBarUseExtraFeature = false;
in PHP.
A more complex example:
{
"config": {
"FooBarEnabledNamespaces": {
"0": true,
"2": true,
"4": true,
"_merge_strategy": "array_plus"
},
"FooBarCoolStuff": {
"sysop": {
"foo": true,
"bar": false
},
"_merge_strategy": "array_plus_2d"
}
}
}
The first setting, $wgFooBarEnabledNamespaces
, has keys that are numbers, so PHP will turn them into integers, even though they are strings in JSON. Because of how PHP treats integer keys when merging arrays, we need to use a different type of merge here, so we set a different "merge strategy" using the magic key. In the second example, we have a nested array, which requires a different type of merging, since we want to allow people to continue writing $wgFooBarCoolStuff['user']['foo'] = true;
in their LocalSettings.php.
Merge strategies
The following merge strategies are available:
array_merge
: Default, does not need to be explicitly set. Any keys that are integers will be re-numbered when merging.array_plus
: Handles keys with integers properly.array_plus_2d
: Handles nested arrays to a depth of 2 properly (e.g.$wgGroupPermissions
).array_plus_recursive
: Handles arrays even deeper than 2, though realistically, a configuration setting that is nested more than 2 arrays suggests too many things are being configured in one setting, and splitting it into multiple might be a good idea.array_replace_recursive
: TODO why should this be used?
ResourceModules
ResourceLoader modules to register.
This option corresponds directly with the global variable $wgResourceModules
.
Please refer to the documentation there on how to configure it.
ResourceFileModulePaths
Specifies the default paths to use for all ResourceLoader file modules.
The allowed properties are:
localBasePath
remoteExtPath
remoteSkinPath
These correspond to the same options in each module definition in ResourceModules
. If a value is not specified in the module definition, the default value specified here will be used.
{
"ResourceFileModulePaths": {
"localBasePath": "resources",
"remoteExtPath": "FooBar/resources"
}
}
ResourceModuleSkinStyles
ResourceLoader modules for custom skin styles.
This option corresponds directly with the global variable $wgResourceModuleSkinStyles
.
Please refer to the documentation there on how to configure it.
ResourceLoaderSources
ResourceLoader sources to register.
This option corresponds directly with the global variable $wgResourceLoaderSources
.
Please refer to the documentation there on how to configure it.
ResourceLoaderLESSVars
ResourceLoader LESS variables.
This option corresponds directly with the global variable $wgResourceLoaderLESSVars
.
Please refer to the documentation there on how to configure it.
ConfigRegistry
Registry of factory functions to create Config objects.
This option corresponds directly with the global variable $wgConfigRegistry
.
Please refer to the documentation there on how to configure it.
SessionProviders
Session providers
This option corresponds directly with the global variable $wgSessionProviders
.
Please refer to the documentation there on how to configure it.
AuthManagerAutoConfig
AuthManager auto-configuration.
This option corresponds directly with the global variable $wgAuthManagerAutoConfig
.
Please refer to the documentation there on how to configure it.
CentralIdLookupProviders
Central ID lookup providers.
This option corresponds directly with the global variable $wgCentralIdLookupProviders
.
Please refer to the documentation there on how to configure it.