A definition of a module:engine/model/schema~ModelSchema schema item.

You can define the following rules:

• ~ModelSchemaItemDefinition#allowIn allowIn – Defines in which other items this item will be allowed.
• ~ModelSchemaItemDefinition#allowChildren allowChildren – Defines which other items are allowed inside this item.
• ~ModelSchemaItemDefinition#allowAttributes allowAttributes – Defines allowed attributes of the given item.
• ~ModelSchemaItemDefinition#disallowIn disallowIn – Defines in which other items this item will be disallowed.
• ~ModelSchemaItemDefinition#disallowChildren disallowChildren – Defines which other items are disallowed inside this item.
• ~ModelSchemaItemDefinition#disallowAttributes disallowAttributes – Defines disallowed attributes of the given item.
• ~ModelSchemaItemDefinition#allowContentOf allowContentOf – Makes this item allow children that are also allowed in the specified items. This acknowledges disallow rules.
• ~ModelSchemaItemDefinition#allowWhere allowWhere – Makes this item allowed where the specified items are allowed. This acknowledges disallow rules.
• ~ModelSchemaItemDefinition#allowAttributesOf allowAttributesOf – Inherits attributes from other items. This acknowledges disallow rules.
• ~ModelSchemaItemDefinition#inheritTypesFrom inheritTypesFrom – Inherits is* properties of other items.
• ~ModelSchemaItemDefinition#inheritAllFrom inheritAllFrom – A shorthand for allowContentOf, allowWhere, allowAttributesOf, inheritTypesFrom.

The is* properties

There are a couple commonly used is* properties. Their role is to assign additional semantics to schema items.

• ~ModelSchemaItemDefinition#isBlock isBlock – Whether this item is paragraph-like. Generally speaking, content is usually made out of blocks like paragraphs, list items, images, headings, etc.
• ~ModelSchemaItemDefinition#isInline isInline – Whether an item is "text-like" and should be treated as an inline node. Examples of inline elements: $text, softBreak (<br>), etc.
• ~ModelSchemaItemDefinition#isLimit isLimit – It can be understood as whether this element should not be split by Enter. Examples of limit elements: $root, table cell, image caption, etc. In other words, all actions that happen inside a limit element are limited to its content. All objects are treated as limit elements, too.
• ~ModelSchemaItemDefinition#isObject isObject – Whether an item is "self-contained" and should be treated as a whole. Examples of object elements: imageBlock, table, video, etc. An object is also a limit, so module:engine/model/schema~ModelSchema#isLimit isLimit() returns true for object elements automatically.

Read more about the meaning of these types in the {@glink framework/deep-dive/schema#defining-additional-semantics dedicated section of the Schema deep-dive} guide.

Generic items

There are several generic items (classes of elements) available: $root, $container, $block, $blockObject, $inlineObject, and $text. They are defined as follows:

schema.register( '$root', {
	isLimit: true
} );

schema.register( '$container', {
	allowIn: [ '$root', '$container' ]
} );

schema.register( '$block', {
	allowIn: [ '$root', '$container' ],
	isBlock: true
} );

schema.register( '$blockObject', {
	allowWhere: '$block',
	isBlock: true,
	isObject: true
} );

schema.register( '$inlineObject', {
	allowWhere: '$text',
	allowAttributesOf: '$text',
	isInline: true,
	isObject: true
} );

schema.register( '$text', {
	allowIn: '$block',
	isInline: true,
	isContent: true
} );
Copy

They reflect typical editor content that is contained within one root, consists of several blocks (paragraphs, lists items, headings, images) which, in turn, may contain text inside.

By inheriting from the generic items you can define new items which will get extended by other editor features. Read more about generic types in the {@glink framework/deep-dive/schema Schema deep-dive} guide.

Example definitions

Allow paragraph in roots and block quotes:

schema.register( 'paragraph', {
	allowIn: [ '$root', 'blockQuote' ],
	isBlock: true
} );
Copy

Allow paragraph everywhere where $block is allowed (i.e. in $root):

schema.register( 'paragraph', {
	allowWhere: '$block',
	isBlock: true
} );
Copy

Allow paragraph inside a $root and allow $text as a paragraph child:

schema.register( 'paragraph', {
	allowIn: '$root',
	allowChildren: '$text',
	isBlock: true
} );
Copy

The previous rule can be written in a shorter form using inheritance:

schema.register( 'paragraph', {
	inheritAllFrom: '$block'
} );
Copy

Make imageBlock a block object, which is allowed everywhere where $block is. Also, allow src and alt attributes in it:

schema.register( 'imageBlock', {
	inheritAllFrom: '$blockObject',
	allowAttributes: [ 'src', 'alt' ],
} );
Copy

Make caption allowed in imageBlock and make it allow all the content of $blocks (usually, $text). Also, mark it as a limit element so it cannot be split:

schema.register( 'caption', {
	allowIn: 'imageBlock',
	allowContentOf: '$block',
	isLimit: true
} );
Copy

Register inlineImage as a kind of an inline object but disallow it inside captions:

schema.register( 'imageInline', {
	inheritAllFrom: '$inlineObject',
	disallowIn: [ 'caption' ]
} );
Copy

Make listItem inherit all from $block but also allow additional attributes:

schema.register( 'listItem', {
	inheritAllFrom: '$block',
	allowAttributes: [ 'listType', 'listIndent' ]
} );
Copy

Which translates to:

schema.register( 'listItem', {
	allowWhere: '$block',
	allowContentOf: '$block',
	allowAttributesOf: '$block',
	inheritTypesFrom: '$block',
	allowAttributes: [ 'listType', 'listIndent' ]
} );
Copy

Tips

• Check schema definitions of existing features to see how they are defined.
• If you want to publish your feature so other developers can use it, try to use generic items as much as possible.
• Keep your model clean. Limit it to the actual data and store information in a normalized way.
• Remember about defining the is* properties. They do not affect the allowed structures, but they can affect how the editor features treat your elements.