VisualEditor/Node types

This documents the current state of support for various node types and annotations.

Legend

Type: symbolic name in the data model;
attribute=value: used if different values for a certain attribute map to different HTML tags
HTML tag: HTML tag this node type is converted from/to
Valid parents: Node types that this type can have as its parent. * means any, - means none
Valid children: Node types that this type can have as its children. * means any, - means none
Other attributes: Attributes that have a special meaning for this node type, if any
Properties (annotations only): Properties in annotation.data
Rendering: Whether the editor renders nodes of this type correctly
Editing: Whether the user can edit the contents of this node type. For annotations, this means the user can edit text with this annotation and change the annotation's properties if any
Creating: Whether the user can create new nodes of this type. For annotations, this means the user can apply this annotation to existing text
Saving: Whether a node of this type will be converted back to wikitext correctly. This can be true even for non-editable nodes if they round-trip correctly. A "no" in this column means even untouched nodes of this type don't round-trip correctly

Structural nodes

These nodes can contain child nodes as long as those nodes aren't content nodes. They do not have their own content.

Type	Data model properties					Editor support
Type	attribute=value	HTML tag	Valid parents	Valid children	Other attributes	Rendering	Editing	Creating	Saving
document^[1]		N/A	-	*		N/A	N/A	N/A	N/A
table		table	*	tableSection		Yes	No	No	No
tableSection	style=header	thead	table	tableRow		Yes	No	No	No
	style=body	tbody
	style=footer	tfoot
tableRow		tr	tableSection	tableCell		Yes	No	No	No
tableCell	style=data	td	tableRow	*		Yes	Yes	No	No
tableCell	style=header	th	tableRow	*		Yes	Yes	No	No
list	style=bullet	ul	*	listItem		Yes	Yes	Yes ^[2]	Yes
list	style=number	ol	*	listItem		Yes	Yes	Yes ^[2]	Yes
listItem		li	list	*		Yes	Yes	Yes	Yes
definitionList		dl	*	definitionListItem		Yes	Yes	No	Yes
definitionListItem	style=term	dt	definitionList	*		Yes	Yes	No	Yes
definitionListItem	style=definition	dd	definitionList	*		Yes	Yes	No	Yes
alienBlock		*^[3]	*	-	html^[4]	Yes	No^[5]	No^[5]	Yes

Nodes that can contain content (TODO terminology?)

These nodes can only contain child nodes that are content. They do not have their own content.

Type	Data model properties					Editor support
Type	attribute=value	HTML tag	Valid parents	Valid children	Other attributes	Rendering	Editing	Creating	Saving
paragraph		p	*	*		Yes	Yes	Yes	Yes
heading	level=1	h1	*	*		Yes	Yes	Yes	Yes
	level=2	h2
	level=3	h3
	level=4	h4
	level=5	h5
	level=6	h6
preformatted		pre	*	*		Yes	Yes	Yes	Yes

Nodes that are content (content nodes?)

These are the only nodes that have content. Text nodes contain text, other nodes in this category cannot contain anything but represent content.

Type	Data model properties					Editor support
Type	attribute=value	HTML tag	Valid parents	Valid children	Other attributes	Rendering	Editing	Creating	Saving
text		N/A^[6]	*	-		Yes	Yes	Yes	Yes
image		img^[7]	*	-	html/src^[8]	Mostly^[9]	No	No	No^[10]
alienInline		*^[3]	*	-	html^[4]	Yes	No^[5]	No^[5]	Yes

Annotations

These aren't nodes, they're JSON objects, but they do correspond to HTML tags. Annotations can be applied to individual characters in a text node and to other content nodes, but not to non-content nodes. Attribute types are denoted as type/subtype.

Type	Data model properties		Editor support
Type	HTML tag	Properties	Rendering	Editing	Creating	Saving
textStyle/italic	i		Yes	Yes	Yes	Yes
textStyle/bold	b		Yes	Yes	Yes	Yes
textStyle/underline	u		Yes	Yes	No	Yes
textStyle/strike	s		Yes	Yes	No	Yes
textStyle/small	small		Yes	Yes	No	Yes
textStyle/big	big		Yes	Yes	No	Yes
textStyle/span	span		Yes	Yes	No	Yes
link/mwInternal	a rel="mw:WikiLink"	href^[11], title^[12]	Yes	Yes	Yes	Yes
link/mwExternal	a rel="mw:ExtLink"	href^[13], title^[14]	Yes	Yes	Yes	Yes
link/unknown^[15]	a	href, title	??	??	??	??

Footnotes

↑ This is the root node that all other nodes descend from, it has no HTML equivalent. Each document has exactly one document node.
↑ Creating and editing nested lists is not supported yet
↑ ^3.0 ^3.1 Represents unrecognized tags or tags with the data-gc attribute (generated content)
↑ ^4.0 ^4.1 Stores the raw HTML found in the Parsoid output
↑ ^5.0 ^5.1 ^5.2 ^5.3 By design
↑ Text nodes represent HTML TextNodes, kind of
↑ Only in the context of an inline image, not in the context of a framed, floating image (thumbnail)
↑ URL of image. Ideally we'd have another attribute for the image title if the image is internal
↑ The width and height attributes aren't taken into account
↑ But this is not the editor's fault, images are converted back to HTML correctly, Parsoid's HTML->wikitext serializer just doesn't support images at all.
↑ Corresponds to href in HTML. Ideally this would only be used for external links
↑ Title of the target page, corresponds to data-mw.sHref[0]
↑ Link target, corresponds to href in HTML
↑ Same as href. Ideally this would only be used for internal links
↑ Unused, deprecated, should be an alien instead

[1] This is the root node that all other nodes descend from, it has no HTML equivalent. Each document has exactly one document node.

[2] Creating and editing nested lists is not supported yet

[alien-htmltag-3] 3.0 ^3.1 Represents unrecognized tags or tags with the data-gc attribute (generated content)

[alien-attr-4] 4.0 ^4.1 Stores the raw HTML found in the Parsoid output

[alien-bydesign-5] 5.0 ^5.1 ^5.2 ^5.3 By design

[6] Text nodes represent HTML TextNodes, kind of

[7] Only in the context of an inline image, not in the context of a framed, floating image (thumbnail)

[8] URL of image. Ideally we'd have another attribute for the image title if the image is internal

[9] The width and height attributes aren't taken into account

[10] But this is not the editor's fault, images are converted back to HTML correctly, Parsoid's HTML->wikitext serializer just doesn't support images at all.

[11] Corresponds to href in HTML. Ideally this would only be used for external links

[12] Title of the target page, corresponds to data-mw.sHref[0]

[13] Link target, corresponds to href in HTML

[14] Same as href. Ideally this would only be used for internal links

[15] Unused, deprecated, should be an alien instead

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]

[9]

[10]

[11]

[12]

[13]

[14]

[15]