CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Typedef

SchemaItemDefinition (engine/model)

@ckeditor/ckeditor5-engine/src/model/schema

typedef
Object
See source

A definition of a schema item.

You can define the following rules:

  • allowIn – Defines in which other items this item will be allowed.
  • allowChildren – Defines which other items are allowed inside this item.
  • allowAttributes – Defines allowed attributes of the given item.
  • allowContentOf – Inherits "allowed children" from other items.
  • allowWhere – Inherits "allowed in" from other items.
  • allowAttributesOf – Inherits attributes from other items.
  • inheritTypesFrom – Inherits is* properties of other items.
  • 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. You can define more properties but you will also need to implement support for them in the existing editor features.

  • isBlock – Whether this item is paragraph-like. Generally speaking, content is usually made out of blocks like paragraphs, list items, images, headings, etc.
  • isInline – Whether an item is "text-like" and should be treated as an inline node. Examples of inline elements: $text, softBreak (<br>), etc.
  • 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.
  • 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 isLimit() returns true for object elements automatically.

Read more about the meaning of these types in the 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
} );

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 Schema deep dive guide.

Example definitions

Allow paragraph in roots and block quotes:

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

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

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

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

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

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

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

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' ],
} );

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
} );

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

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

Which translates to:

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

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.

Filtering

Properties

  • allowAttributes : String | Array.<String>

    Defines allowed attributes of the given item.

  • allowAttributesOf : String | Array.<String>

    Inherits attributes from other items.

  • allowChildren : String | Array.<String>

    Defines which other items are allowed inside this item.

  • allowContentOf : String | Array.<String>

    Inherits "allowed children" from other items.

  • allowIn : String | Array.<String>

    Defines in which other items this item will be allowed.

  • allowWhere : String | Array.<String>

    Inherits "allowed in" from other items.

  • inheritAllFrom : String

    A shorthand for allowContentOf, allowWhere, allowAttributesOf, inheritTypesFrom.

  • inheritTypesFrom : String | Array.<String>

    Inherits is* properties of other items.

  • isBlock : Boolean

    Whether this item is paragraph-like. Generally speaking, content is usually made out of blocks like paragraphs, list items, images, headings, etc. All these elements are marked as blocks. A block should not allow another block inside. Note: There is also the $block generic item which has isBlock set to true. Most block type items will inherit from $block (through inheritAllFrom).

    Read more about the block elements in the Block elements section of the Schema deep dive.

  • isContent : Boolean

    An item is a content when it always finds its way to the editor data output regardless of the number and type of its descendants. Examples of content elements: $text, imageBlock, table, etc. (but not paragraph, heading1 or tableCell).

    Note: An object is also a content element, so isContent() returns true for object elements automatically.

    Read more about content elements in the Content elements section of the Schema deep dive guide.

  • isInline : Boolean

    Whether an item is "text-like" and should be treated as an inline node. Examples of inline elements: $text, softBreak (<br>), etc.

    Read more about the inline elements in the Inline elements section of the Schema deep dive guide.

  • isLimit : Boolean

    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.

    Read more about the limit elements in the Limit elements section of the Schema deep dive guide.

  • isObject : Boolean

    Whether an item is "self-contained" and should be treated as a whole. Examples of object elements: imageBlock, table, video, etc.

    Note: An object is also a limit, so isLimit() returns true for object elements automatically.

    Read more about the object elements in the Object elements section of the Schema deep dive guide.

  • isSelectable : Boolean

    true when an element should be selectable as a whole by the user. Examples of selectable elements: imageBlock, table, tableCell, etc.

    Note: An object is also a selectable element, so isSelectable() returns true for object elements automatically.

    Read more about selectable elements in the Selectable elements section of the Schema deep dive guide.