Extension:CommunityConfiguration/Technical documentation

Getting started

Registering a new provider

Community configuration providers are a formal description of how a set of configuration options should handled by the extension. They consist of three main component declarations: store, validator and an optional form. See more in "docs/tbd". The following example shows the minimal definitions to get a provider up and working.

There are two mechanisms of registering a new configuration provider, through MW Configuration setting $wgCommunityConfigurationProviders or using the attributes property in extension.json

Using wgCommunityConfigurationProviders

$wgCommunityConfigurationProviders['MyProvider'] = [
	'store' => [
		'type' => 'wikipage',
		'args' => [
			'MediaWiki:ExampleConfig.json'
		]
	],
	'validator' => [
		'type' => 'jsonschema',
		'args' => [
			\CommunityConfigurationExample\Schemas\ExampleSchema::class
		]
	],
	'type' => 'mw-config'
];

Using extension.json attributes

"attributes": {
		"CommunityConfiguration": {
			"Providers": {
				"MyProvider": {
					"store": {
						"type": "wikipage",
						"args": [
							"MediaWiki:ExampleConfig.json"
						]
					},
					"validator": {
						"type": "jsonschema",
						"args": [
							"CommunityConfigurationExample\\Schemas\\ExampleSchema"
						]
					},
					"type": "mw-config"
				}
			}
		}
	},

Creating a JSON schema with PHP

The extensions provides a JsonSchema interface to facilitate creating JSON schema document representations with a PHP class. This also restricts the JSON schema features available to those Community Configuration can handle. Below a minimal example of an schema class:

<?php

namespace CommunityConfigurationExample\Schemas;

use MediaWiki\Extension\CommunityConfiguration\Schema\JsonSchema;

class ExampleSchema implements JsonSchema {
	public const ExampleConfigOption = [
		self::TYPE => self::TYPE_STRING
	];
}

Public class properties are collected as top level keys of an object. At this stage, Community Configuration can only work with type object for the top level data structure. Hence there's no support for top level type array. The ExampleSchema class would be expanded to the following JSON schema in json format:

{
	"$schema": "https://json-schema.org/draft-04/schema#"
	"$id": "CommunityConfigurationExample/Schemas/ExampleSchema/1.0.0",
	"type": "object",
	"properties": {
		"ExampleConfigOption": {
			"type": "string"
		}
	},
	"additionalProperties": false
}

Creating a new config page

The configuration data for a given set of options under a provider is stored as wiki json pages in the MediaWiki namespace. Whenever you create a new provider using the "type": "wikipage" for its store, you'll need to create the page on your target wiki and add a valid configuration for the first time. This action requires some privileged rights, currently, any of 'administrator', 'interface administrator' (see more in docs/CC-user-rights-tbd).

This process is tedious and not ideal, further improvements are being discussed in task T351517

PHP schemas

CommunityConfiguration is designed to work with PHP files as the source for defining json-schema compliant documents. This approach is also used in other MediaWiki software components such as MainConfigSchema. The support for PHP schemas is built ad-hoc in the extension and has limitations compared to the full json-schema specification.

Limitations

• Limited support for json-schema version draft-04
• root schema must be of "type": "object"
• additionalProperties is set to false for root properties

JSON-schema vocabulary

The following json-schema keywords are supported:

• additionalProperties
• default
• properties
• type
• items
• enum
• $ref

Extended vocabulary

• control

Glossary

• schema: polysemic, it can refer to a full configuration specification in a PHP file, eg: MySchema.php or to the specification of a property at any level in the schema, eg: { "type": "string" }

• subschema: used to disambiguate schema, refers to the specification of a property at any level in the schema as opposed to the full schema.

• root schema: used to disambiguate schema, refers to the top level specification of a full schema. In CommunityConfiguration this is restricted to be "type": "object", see [Extension:CommunityConfiguration/Technical_documentation#tbd].

• property: refers to the schema defined under the key "properties" in any schema.

• root property: refers to the schema defined under the key "properties" in the root schema.