Parsoid/Internals/Module Configuration Schema

Translate this page

Parsoid file: moduleconfig.schema.json
Location:	src/Ext/
Source code:	master • 1.45.3 • 1.44.5 • 1.43.8
Classes:	Find code • Find documentation

This page documents the schema used by Parsoid for extension module registration. This structure can either be used as an element in the ParsoidModules clause of an extension's extension.json (preferred), or as the return value for ExtensionModule::getConfig() (not recommended except for internal Parsoid modules). All fields are optional unless otherwise specified.

name

MediaWiki version:

≥ 1.44

Gerrit change 1133203

This field is required.

This is the extension modules's canonical name, and should be unique. Note that a MediaWiki extension can define multiple Parsoid extension modules. This is the unique name of one particular Parsoid extension module, not necessarily the MediaWiki extension's name. The name field does not have to match an extension's directory name nor the name of its page in the Extension namespace on MediaWiki.org. However, if you are only defining a single Parsoid extension module, you might consider making this the same as the top-level name field in extension.json .

{
	"name": "FooBar"
}

PFragmentTypes

MediaWiki version:

≥ 1.44

Gerrit change 1134250

A list of string class names. Each class name should be a subclass of PFragment, and Parsoid will invoke PFragment::registerFragmentClass() on each to ensure objects of this fragment type can be serialized/deserialized.

annotations

MediaWiki version:

≥ 1.44

Gerrit change 1133203

An annotation handler, which is an object with the following properties:

Name	Type	Description	Required?
`tagNames`	list of strings	List of case-insensitive extension tag names that are to be handled	Required
`annotationStripper`	ObjectFactory or string	An ObjectFactory specification of a object implementing AnnotationStripper. A class name string can be used as a shortcut.	Optional
`options`	map	Additional annotation handler options (currently unused)	Optional

Example from src/PageTranslation/TranslateExt.php in Extension:Translate :

{
	"name": "Translate",
	"annotations": {
		"tagNames": [ "translate", "tvar" ],
		"annotationStripper": {
			"class": "MediaWiki\\Extension\\Translate\\PageTranslation\\TranslationAnnotationStripper",
			"services": [
				"Translate:TranslatablePageParser"
			]
		}
	}
}

contentModels

MediaWiki version:

≥ 1.44

Gerrit change 1133203

Map from content type name to an ObjectFactory specification of an object extending ContentModelHandler. A class name string can be used as a shortcut.

Example from src/Ext/JSON/JSON.php in Parsoid :

{
	"name": "JSON content",
	"contentModels": {
		"json": "Wikimedia\\Parsoid\\Ext\\JSON\\JSON"
	}
}

domProcessors

MediaWiki version:

≥ 1.44

Gerrit change 1133203

A list of ObjectFactory specifications of objects implementing DOMProcessor. Class name strings can be used as shortcuts for object factory specifications.

Example from extension.json in Extension:Cite :

{
	"name": "Cite",
	"domProcessors": [
		{
			"class": "Cite\\Parsoid\\RefProcessor",
			"services": [
				"MainConfig"
			]
		}
	],
	"tags": [
		...
	]
}

pFragmentHandlers

MediaWiki version:

≥ 1.44

Gerrit change 1087277

Array of PFragment handlers. Each handler is an object with the following properties:

Name	Type	Description	Required?
`key`	A magic word identifier	The magic word ID used for this fragment	Required
`handler`	ObjectFactory or string	An ObjectFactory specification of a object extending PFragmentHandler. A class name string can be used as a shortcut.	Required
`options`	map	Additional PFragment handler options, described below.	Optional

The following options keys can be supplied:

parserFunction (boolean) - whether parser function syntax can be used to invoke this PFragment handler
nohash (boolean) - if false (the default) a # character is prepended to the start of the localized text for the magic word corresponding to key when using parser function syntax. If the parser function is intended to be invoked without a leading hash, for example {{uc:...}} or the localization for the magic word already contains the hash character, as for {{#bcp47}} this should be set to true. (Parser function syntax only.)
extensionTag (boolean) - whether extension tag syntax can be used to invoke this PFragment handler (MW >= 1.45)
hasAsyncContent (boolean) - This must be set to true if the PFragmentHandler can ever return an AsyncResult indicating asynchronously-available content.

Note that the case-sensitivity of the parser function or extension tag syntax is determined by the case-sensitivity of the magic word identified by key, although it is strongly recommended to make new fragment handlers case-sensitive; see phab:T389029 for more details. Similarly, setting nohash is not recommended for new parser functions.

Example from src/ParserTests/ParserTestPFragmentHandlers.php in Parsoid:

{
	"name": "ParserHook",
	"pFragmentHandlers": [
		{
			"key": "f1_wt_nohash",
			"handler": {
				"factory": "Wikimedia\\Parsoid\\ParserTests\\ParserTestsPFragmentHandlers::getHandler",
				"args": [ "f1_wt_nohash" ],
			},
			"options": {
				"parserFunction": true,
				"nohash": true
			}
		}
	]
}

richAttributes

MediaWiki version:

≥ 1.46

Gerrit change 1236842

A list of rich attribute hints. Each item should be an object with a name field naming an attribute name, and a hint field which is either a class-string or an object factory which will create a Hint. The object class should extend RichCodecable.

Using some built-in attribute types as an example:

{
	"name": "ParsoidBuiltInAttributes",
	"richAttributes": [
		{
			"name": "data-mw",
			"hint": {
				"factory": "Wikimedia\\Parsoid\\NodeData\\DataMw::hint",
				"args": []
			}
		},
		{
			"name": "data-parsoid-diff",
			"hint": "Wikimedia\\Parsoid\\NodeData\\DataParsoidDiff"
		}
	]
}

tags

MediaWiki version:

≥ 1.44

Gerrit change 1133203

Array of extension tag handlers. Each handler is an object with the following properties:

Name	Type	Description	Required?
`name`	list of strings	The case-insensitive extension tag names that are to be handled.	Required
`handler`	ObjectFactory or string	An ObjectFactory specification of a object extending ExtensionTagHandler. A class name string can be used as a shortcut.	Required
`options`	map	Additional tag handler options, described below.	Optional

The following options keys can be supplied:

outputHasCoreMwDomSpecMarkup (boolean) - whether the output contents of this extension tag consist of markup parsed by Parsoid. Setting this flag allows Parsoid to perform postprocessing tasks (localization, redlink marking, etc) on the contents of the tag. (T331655 proposes adding a future mixed value for this option.)
hasWikitextInput (boolean) - whether the input contents of this extension tag consists of wikitext markup. Setting this flag allows annotation tags to be stripped from the input.
stripNowiki (boolean) - temporary compatibility flag; see phab:T299103 for details.
wt2html (map) - additional options for conversion from wikitext to html, described below.
html2wt (map) - additional options for conversion from html to wikitext, described below.

The following wt2html keys can be supplied, which affect how the DOM fragment returned by the ExtensionTagHandler::sourceToDom() method should be handled.

embedsDomInAttributes (boolean) - as an optimization, ExtensionTagHandler::processAttributeEmbeddedDom() will only be invoked if this property is true.
embedsHTMLInAttributes (boolean) - as an optimization, ExtensionTagHandler::processAttributeEmbeddedHTML() will only be invoked if this property is true. (deprecated: in new code prefer embedsDomInAttributes/ExtensionTagHandler::processAttributeEmbeddedDom().)
attributeWSNormalizationPref (string) - default format for tag attribute space normalization. The can be set to trim (trim whitespace around the attribute), normalize (trim and also normalize inner spaces such as double space to a single space), keepspaces (do not trim or modify inner spaces). The default value is normalize to match usual HTML attribute behavior.
customizesDataMw (boolean) - set to true if the extension's first node data-mw attribute is set by the extension to avoid clobbering it by mistake. Default value is false.
setDSR (boolean)
wrapperName (string)
unpackOutput (boolean) - deprecated (used only for "sealed" fragments in Cite extension). By default, Parsoid takes the DOM fragment returned by the ExtensionTagHandler::sourceToDom() method, unpacks and splices it into the parent document in the appropriate place. However, if unpackOutput is false, Parsoid will leave a marker instead and store the fragment in a map. It is expected that the extension's wt2htmlPostProcessor DOM processor will appropriately deal with these DOM fragments and manipulate them. For example, the Cite extension relies on this to migrate the ref's fragments to the references section and leave behind a citation that is appropriately globally numbered.

The following html2wt keys can be supplied, which affect how the wikitext generated by ExtensionTagHandler::domToWikitext() interacts with its context:

format (string) - can be set to block or inline. By default, the wikitext from converting the HTML is rendered inline. However, if extensions specify a block value for this property, the wikitext output is rendered on its own separate line.

Example from src/Ext/Pre/Pre.php in Parsoid:

{
	"name": "<pre>",
	"tags": [
		{
			"name": "pre",
			"handler": "Wikimedia\\Parsoid\\Ext\\Pre\\Pre",
			"options": {
				"stripNowiki": true
			}
		}
	]
}