Extension:JsonConfig

Lua error: callParserFunction: function "#translation" was not found.Lua error: callParserFunction: function "#translation" was not found.

**MediaWiki extensions manual**
Extension:JsonConfig Release status: stable[[Category:stable extensions{{#translation:}}]]
Implementation	Lua error: callParserFunction: function "#translation" was not found.
Description	<translate> Provides a wiki-based JSON configuration system</translate>
Author(s)	Yuri Astrakhan (yurik^talk)
Latest version	Lua error: callParserFunction: function "#translation" was not found.
MediaWiki	1.29+
PHP	5.5+
Database changes	No
License	Lua error: callParserFunction: function "#translation" was not found.
Download	<translate> Download extension</translate> <translate> Git</translate> ^[?]: <translate> Download Git master</translate> <translate> browse repository</translate> (GitHub) <translate> commit history</translate> <translate> repository contributors (GitHub)</translate> <translate> code review</translate> [[Category:Extensions in Wikimedia version control{{#translation:}}]] RFC
Parameters $wgJsonConfigs $wgJsonConfigModels
Added rights Lua error: callParserFunction: function "#translation" was not found.
Translate the Extension:JsonConfig extension if it is available at translatewiki.net
Check usage and version matrix.

[[Category:All extensions{{#translation:}}]] Lua error: callParserFunction: function "#translation" was not found.

<translate> The <tvar|1>JsonConfig</> extension allows other extensions to store their configuration data as a JSON blob in a wiki page.

Available features and usage patterns

You may use JsonConfig to store data in a number of ways:</translate>

- in a single configuration page, e.g. a number of settings for your extension in <tvar|1>Config</>:MyExtSettings (<tvar|2>Config</> is the default namespace associated with the JsonConfig extension);</translate>

- in a set of pages with similar structure residing in their own namespace, e.g. IP addresses of known proxies or event log schemas named "Proxy:Opera", or schemas named [[<tvar|1>meta:Schema:AccountCreation</>|Schema:AccountCreation]]</translate>

- using it only for pages whose titles match a regex pattern, e.g. Config:Proxy:Opera or Config:Opera.proxy. This avoids filling a wiki with lots of namespaces, one for each content model.</translate>

You may provide a content class to do data validation (beyond valid JSON) and normalization.</translate>

You may provide a view class to customize HTML display.</translate>

You can store data:</translate>

- "one-per-wiki", "one-per-cluster", or even one per some "family" (different structure of the caching key for shared memcached);</translate>

- in a public or private wiki and accessed with credentials;</translate>

- in a separate cluster, and do remote notification when changed.

On-wiki usage

Current

Commons tabular data sets
Commons map data sets
Dashiki dashboard configurations
Others?

Past

</translate>

<translate> <tvar|1>Wikipedia Zero</> operator configurations (see <tvar|2>Extension:ZeroBanner</>)</translate>

Installation

</translate> vagrant>Vagrant </>, install with <tvar

<translate> 1>download-link</> and place the file(s) in a directory called <tvar|name>Extension:JsonConfig</> in your <tvar|ext>extensions/</> folder.</translate>composer>Composer</> to install PHP dependencies, by issuing <tvar
<translate> Add the following code at the bottom of your <tvar|LocalSettings>LocalSettings.php</>:</translate>
```
wfLoadExtension( 'Extension:JsonConfig' );
```
<translate> Configure as required.</translate>
<translate> Done</translate> – <translate> Navigate to <tvar|special>Special:Version</> on your wiki to verify that the extension is successfully installed.</translate>

<translate> To users running MediaWiki <tvar

Configuration

</translate>

`$wgJsonConfigs`

<translate> This variable defines profiles for each type of configuration pages.</translate> <translate> <tvar|1>$wgJsonConfigs</> is an associative array of arrays, with each sub-array having zero or more of the following parameters.</translate> <translate> By default, JsonConfig uses the string key as the model ID that this profile represents, but in case you want to reuse the same model ID in more than one profile, you can override it with the <tvar|1>model</> parameter.</translate>

<translate> parameter</translate>	<translate> type</translate>	<translate> default</translate>	<translate> description</translate>
model	string	<translate> (key in <tvar\|1>`$wgJsonConfigs`</>)</translate>	<translate> Model ID to use when creating a new page.</translate> <translate> If none is given, the array key of this profile becomes the model ID.</translate> <translate> If this value is set to <tvar\|1>`null`</>, the built-in module ID <tvar\|2>`JsonConfig`</> will be used.</translate> <translate> The model ID must also be listed in the <tvar\|1>$wgJsonConfigModels</> except for <tvar\|2>`null`</> or <tvar\|3>`'JsonConfig'`</>.</translate>
namespace	int	NS_CONFIG (482)	<translate> Namespace in which these configs will reside, or '<tvar\|1>Config:</>' by default</translate>
nsName	string/false		<translate> For non-default (not NS_CONFIG 482) namespace, assigns it a canonical (English) name.</translate> <translate> If more than one <tvar\|1>$wgJsonConfigs</> array uses the same namespace, only set the name once.</translate> <translate> If not found, a warning will be given, and the namespace will get automatic "<tvar\|1>ConfigNNN</>" name.</translate> <translate> In case this config is not stored locally, <tvar\|1>nsName</> will be used as remote namespace, without local declaration.</translate> <translate> If you want to share namespace with other, non <tvar\|1>JsonConfig</> content pages, set this value to <tvar\|2>`false`</>.</translate>
nsTalk	string	nsName+`_talk`	<translate> For non-default namespaces, assigns their talk pages a canonical (English) name</translate>
pattern	string	(all)	<translate> Regular expression to match the page title in the given namespace.</translate> <translate> If empty, the configure will apply to all the pages in the namespace.</translate> <translate> To match the legacy "subspace" behavior, for <tvar\|1>`isSubspace=true`</>, use `^/^name:./` pattern, and for <tvar\|2>`isSubspace=false`</>, use `/^name$/` pattern.</translate>
isLocal	bool	true	<translate> If <tvar\|1>`true`</>, this configuration will not be shared across the cluster, but rather each wiki would have a local config.</translate> <translate> If <tvar\|1>`false`</>, this configuration is meant to be shared across multiple wikis, and in order to make this specific wiki store it locally, set the '<tvar\|2>store</>' field.</translate> <translate> This flag affects the caching key, so a config page with the same name would be shared in memcached if this setting is false, but will be unique per wiki if true.</translate>
cacheExp	int	246060	<translate> How long (in seconds) should the value be cached in memcached</translate>
cacheKey	string		<translate> If the value is set, add that string to the caching key.</translate> <translate> Use <tvar\|1>`cacheKey`</> to invalidate previous cached values - e.g. when making an incompatible change that would modify cached values, and you worry that you may need to roll back.</translate> <translate> This key can also be used to allow all language wikies in the same family to share the same cached value, while being stored in the same page but on different wikies.</translate> <translate> For example, Wikipedia could use "<tvar\|1>wp</>" and Wikiquotes could use "<tvar\|2>wq</>".</translate>
flaggedRevs	bool	false	<translate> If <tvar\|1>`true`</>, will attempt to get the latest revision that has been verified via flagged revs extension, if <tvar\|2>`null`</>, flagged revision will be checked, and if available, used.</translate> <translate> If <tvar\|3>`false`</>, will always use the latest revision.</translate>
remote	array		<translate> An object with parameters describing how to access configuration from another wiki.</translate> <translate> Must be present if '<tvar\|1>store</>' is not set, and <tvar\|2>`isLocal`</> is <tvar\|3>`false`</>.</translate>
‑ url	string		<translate> Non-default API endpoint to get config from remote wiki just for this configuration profile.</translate> <translate> If not specified, will use the value of <tvar\|1>`$wgJsonConfigApiUri`</>.</translate>
‑ username	string		<translate> If given, will be used to authenticate to the remote configuration storage.</translate>
‑ password	string		<translate> See <tvar\|1>`username`</>.</translate>
store	array		<translate> Set this value to <tvar\|1>`true`</> or an array to make the current wiki actually host this configuration data.</translate> <translate> This value will automatically populate if missing and <tvar\|1>`isLocal`</> is <tvar\|2>`true`</>.</translate>
‑ cacheNewValue	bool	true	<translate> When config changes, how should the cache change.</translate> <translate> If <tvar\|1>`false`</>, deletes cached value, forcing other wikies to re-request it.</translate> <translate> <tvar\|1>`true`</> sets the new value into cache.</translate> <translate> This is mostly useful if the wiki that stores and wikies that consume this configuration share the same cache.</translate> <translate> Beware that in case of <tvar\|1>`false`</>, if consumer wiki requests the new value too fast, it might get it from a possibly stale slave DB.</translate>
‑ notifyUrl	string		<translate> Optionally specify remote API URL that will be called when configuration changes.</translate>
‑ notifyUsername	string		<translate> Optional username to use with <tvar\|1>`notifyUrl`</></translate>
‑ notifyPassword	string		<translate> Optional password to use with <tvar\|1>`notifyUrl`</></translate>

`$wgJsonConfigModels`

<translate> This variable defines which custom content class will handle which Model ID.</translate> <translate> More than one Model ID may be handled by the same content class.</translate> <translate> All content classes must derive from the <tvar|1>JCContent</> class; if the modelID maps to <tvar|2>null</>, then the default <tvar|1>JCContent</> class handles the model ID.</translate>

<translate> Example: </translate>

$wgJsonConfigModels['Config.MyExtSettings'] = 'MyExt\MyContentClass';

<translate> If you implement a separate class to do HTML rendering, you can specify your config model as an array with an extra <tvar|1>view</> class: </translate>

$wgJsonConfigModels['Config.MyExtSettings'] = [
    'class' => 'MyExt\MyContentClass',
    'view'  => 'MyExt\MyContentViewClass', // easier to extend JCDefaultObjContentView or JCDefaultContentView
];

Examples

</translate>

isSubspace</> values to customize which pages belonged to the given content model.</translate> <translate> Both have been removed in version 1.0.0, and replaced with the <tvar ">1>name</> and <tvar

Hello World

</translate> <translate> The simplest case is a single configuration page without any validation, stored locally on each wiki.</translate> <translate> Just add these settings to <tvar|1>LocalSettings.php</></translate>

// Content model is 'JsonConfig.MySettings'
// Model class is set to NULL to allow non-validated data
$wgJsonConfigModels['JsonConfig.MySettings'] = null;

$wgJsonConfigs['JsonConfig.MySettings'] = array(
  'pattern' => '/^MySettings$/', // Page name in Config namespace
);

<translate> The above enables namespace "Config" on the local wiki, but only allows the "Config:MySettings" page to be created, not any other page in that namespace.</translate> <translate> You can store well-formed JSON data in the page.</translate>

<translate> To read the MySettings data in PHP, use a <tvar|1>TitleValue</> object to access the page, then request its content:</translate>

use JsonConfig\JCSingleton;
$tv = new TitleValue( NS_CONFIG, 'MySettings' ); // DB Key
$content = JCSingleton::GetContent( $tv );
if ( $content->isValid() ) {
    $data = $content->getData();
    ...
}

Multiple configs shared in a cluster

</translate> <translate> Lets say we decide to store the trusted proxies' IPs as "Config:Proxy:SomeName" pages on Meta-Wiki and share this data with the cluster.</translate>

// All wikis must have this configuration:
$wgJsonConfigs['JsonConfig.Proxy'] = [
  'pattern' => '/^Proxy\:./', // require at least one letter after the ':'
  'isLocal' => false,
];

// The LocalSettings.php for all wikis except Meta-Wiki will set this URL to Meta-Wiki's API endpoint:
$wgJsonConfigs['JsonConfig.Proxy']['remote'] = 'http://meta.wikimedia.org/w/api.php';

// LocalSettings.php for Meta-Wiki will indicate that the data should be stored there
$wgJsonConfigs['JsonConfig.Proxy']['store'] = true;

<translate> If instead you want to dedicate a separate namespace to proxies, the parameters would change to:</translate>

$wgJsonConfigs['JsonConfig.Proxy'] = [
  'namespace' => NNN, // NNN is the number you would reserve for Proxy namespace
  'nsName' => 'Proxy', // Canonical namespace name
];

Validation

</translate> <translate> Most of the time one would also want a custom content class with its own validation.</translate> <translate> JSON pages are handled by the content classes which derive from <tvar|1>JCContent</>.</translate> <translate> The content class is responsible for parsing and validating raw text.</translate> <translate> <tvar|1>JCContent</> does not do any validation beyond JSON parsing, but you may choose to derive from it and override <tvar|2>JCContent::validate()</>.</translate> <translate> Better yet, you may derive from the <tvar|1>JCObjContent</> class which provides a number of validation primitives, and only override <tvar|2>JCObjContent::validateContent()</>.</translate>

// This should be done on all wikis, including Meta-Wiki
$wgJsonConfigModels['JsonConfig.Proxy'] = 'ProxyExt\ProxyContent';

<translate> For the sake of this documentation, let's presume that the proxy config page describing Opera Mini servers has this format:</translate>

{
    "enabled": true,
    "comment": "See http://... for updates",
    "ips": [
        '37.228.104.0/21',
        ...
    ]
}

<translate> Here is the content class to validate that data.</translate>

use JsonConfig\JCObjContent;
use JsonConfig\JCValidators;

class ProxyContent extends JCObjContent {

    /**
     * Derived classes must implement this method to perform custom validation
     * using the check(...) calls
     */
    public function validateContent() {
        // 'enabled' must be a boolean, true by default.
        // JCValidators::* already handle localized error messages
        $this->testOptional( 'enabled', true, JCValidators::isBool() );
        // an optional field 'comment' of type string
        $this->testOptional( 'comment', '', JCValidators::isString() );
        // 'ips' must be a list of valid CIDR ranges
        // field is not optional when default value would not pass validation
        $this->test( 'ips', self::getIpValidator() );
    }

    private static function getIpValidator() {
        // JCValue $value is a value of the field being checked wrapped with the status information.
        //              $v->getValue() actual value being examined
        //              $v->isMissing() if the value is not present in the data
        //              $v->defaultUsed() if the value did not exist and a default was supplied
        // array $path the location of this field in the hierarchy - each value is either string or an int
        // JCObjContent $self - this object, useful to get access to other fields via $self->getField()
        // You may modify the value stored inside, set additional flags, or report an error
        // using the $v->error( $key, $path, ... ) function
        return function ( JCValue $value, array $path, JCObjContent $self ) {
            $isErr = false;
            $v = $value->getValue();
            if ( is_string( $v ) ) {
                // user supplied a single string, treat as an non-assoc array
                $v = array( $v );
            } else {
                // ensure that $v is an non-assoc array, and all of its values are strings
                $isErr = !JCUtils::isList( $v ) || !JCUtils::allValuesAreStrings( $v );
            }
            if ( !$isErr ) {
                // @todo: do the rest of the IP validation and set $isErr to true on failure
            }
            // Error message might be in this form:
            // "Parameter \"$1\" must be an array of valid non-restricted (no private networks) CIDR IP blocks"
            if ( $isErr ) {
                $value->error( 'my-proxyconfig-err-ips', $path );
            } else {
                $value->setValue( $v );
            }
        };
    }
}

Customizing behavior on the storage wiki

</translate> <translate> You may also want to customize viewing and page creation on the storage wiki (Meta-Wiki in the above example).</translate> <translate> There are two ways to do this: inside your <tvar|1>JCContent</>-derived class, or via a separate "view" class that derives from <tvar|2>JCContentView</>.</translate> <translate> The second approach is preferable as it cleanly separates the architecture and the view class need only exist in the storage wiki (e.g. Meta-Wiki), not on all the wikis that use the data.</translate>

<translate> To override default value in <tvar|1>JCContent</>-derived class, override the constructor and set the <tvar|2>$text</> value to the new default if it came in as NULL before passing it to the parent constructor.</translate> <translate> To override the HTML generation, override <tvar|1>JCContent::getHtml()</>.</translate>

<translate> With the recommended way, create a view class that derives from <tvar|1>JCContentView</> or a more feature-rich <tvar|2>JCDefaultContentView</>.</translate> <translate> For <tvar|1>JCContentView</>, you will need to implement <tvar|2>valueToHtml()</> and <tvar|3>getDefault()</>.</translate> <translate> By default, the view is implemented by the <tvar|1>JCDefaultContentView</> class, which can also be used as a customizable base if you just need minor adjustments to the way it looks.</translate>

// <translate nowrap><!--T:30--> Changing model definition from the above - should be done on all wikis, including META</translate>
$wgJsonConfigModels['JsonConfig.Proxy'] = [ 'class' => 'ProxyExt\ProxyContent' ];

// <translate nowrap><!--T:31--> Add the view class - should only be done on the storage wiki (e.g. META)</translate>
$wgJsonConfigModels['JsonConfig.Proxy']['view'] = 'ProxyExt\ProxyView';

class ProxyView extends JsonConfig\JCDefaultObjContentView {
    public function getDefault( $modelId ) {
        return <<<JSON
{
    "comment": "See http://... for updates",
    "ips": [
        "N.N.N.N/NN",...
    ]
}
JSON;
    }
}

Best practices

</translate>

<translate> Extensions that use JsonConfig should add their configurations to the <tvar|1>$wgJsonConfigs</> and <tvar|2>$wgJsonConfigModels</> in the main extension file.</translate>
<translate> If you share config data among multiple wikis, document the key name used in <tvar|1>$wgJsonConfigs[]</>, and initialize the 'store' / 'remote' section in <tvar|2>LocalSettings.php</>.</translate> <translate> This is better than introducing a number of global variables that duplicate the config functionality.</translate> <translate> See for example Wikimedia's configuration of the [[<tvar|1>Special:MyLanguage/Extension:Graph</>|Graph extension]] across multiple wikis (although that uses complex multi-wiki setup rather than simple config variables).</translate>

Status

Implemented features

</translate>

<translate> JSON parsing converts JSON text into either an array or an object</translate>
<translate> Visualization shows JSON as an easy to view table rather than code, with some extra highlighting.</translate> <translate> For example if the value is not provided and a default is used, it is shown in gray, or when the value is the same as default, it shows as purple.</translate> <translate> For example, see this and this.</translate>
<translate> [[<tvar|1>Special:MyLanguage/Extension:CodeEditor</>|Code Editor]] simplifies JSON editing</translate>
<translate> Custom Validation performs complex checks such as checking that the value is in the proper format or that a user ID exists.</translate>
<translate> MemCached caching stores json blobs in memcached under custom keys and expiration policies, and resets them on save.</translate>
<translate> Flagged Revisions support allows configurations to be marked as "reviewed" before going into production</translate>
<translate> Localization of most basic interface elements has been done in many languages, and it would reduce translation work if most common messages would be done just once in one place.</translate>

Unimplemented nice-to-haves

</translate> <translate> These features would be desirable to more than one type of configs:</translate>

<translate> Schema validator - Validate against JSON Schema, as most extensions might not need complex validation rules, or might want to combine schema plus extra validation.</translate>
<translate> Custom editor - Zero team has been thinking about implementing a more complex editor, possibly based on JSON Schema.</translate>
<translate> API query support - Allow config pages to be returned as regular API results in all formats - json/xml/... instead of text blobs:</translate>
api.php ? action=query & titles=Config:Proxy:Opera & prop=jsonconfig
<translate> Localization - it would be good to be able to show localized descriptions for each configuration key</translate>

External access

</translate> <translate> The stored configuration data may frequently be needed by some external agent such as JavaScript, bot, or other programs.</translate> <translate> JavaScript could use either JSONP to access needed data by calling standard <tvar|1>action=query&rvprop=content</> API, or we could develop a forwarding service if CORS is unavailable.</translate> <translate> Extension authors may choose to add their own API modules to provide domain-specific information.</translate> <translate> Lastly, the <tvar|1>rvprop=jcddata</> Query API parameter would return JSON data as part of the API result, not as a text blob that <tvar|2>rvprop=content</> would return.</translate>

// <translate nowrap><!--T:54--> NOT IMPLEMENTED! Use regular action=query API until we decide how to do it right</translate>
var req = {
    format: 'json', action: 'query',
    titles: 'Proxy:Opera',
    prop: 'revisions', rvprop: 'jcdcontent', indexpageids: '',
};
$.ajax({
    url: '//meta.wikipedia.org/w/api.php',
    data: req, cache: true, dataType: 'jsonp',
    success: function(result) { /* <translate nowrap><!--T:55--> handle errors and warnings, process content</translate> */ }
});

Anonymous

Search

Extension:JsonConfig

Namespaces

More

Page actions

Contents

Available features and usage patterns

On-wiki usage

Current

Past

Installation

Configuration

`$wgJsonConfigs`

`$wgJsonConfigModels`

Examples

Hello World

Multiple configs shared in a cluster

Validation

Customizing behavior on the storage wiki

Best practices

Status

Implemented features

Unimplemented nice-to-haves

External access

See also

Navigation

Navigation

DAS Categories

Wiki tools

Wiki tools

Anonymous

Search

Extension:JsonConfig

Available features and usage patterns

On-wiki usage

Current

Past

Installation

Configuration

$wgJsonConfigs

$wgJsonConfigModels

Examples

Hello World

Multiple configs shared in a cluster

Validation

Customizing behavior on the storage wiki

Best practices

Status

Implemented features

Unimplemented nice-to-haves

External access

See also

Navigation

Wiki tools

Page tools

Categories

`$wgJsonConfigs`

`$wgJsonConfigModels`