Report an issue
Typedef

SchemaItemDefinition (engine/model)

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

typedef
Object

A definition of a schema item.

You can define the following rules:

  • allowIn – a string or an array of strings. Defines in which other items this item will be allowed.
  • allowAttributes – a string or an array of strings. Defines allowed attributes of the given item.
  • allowContentOf – a string or an array of strings. Inherit "allowed children" from other items.
  • allowWhere – a string or an array of strings. Inherit "allowed in" from other items.
  • allowAttributesOf – a string or an array of strings. Inherit attributes from other items.
  • inheritTypesFrom – a string or an array of strings. Inherit is* properties of other items.
  • inheritAllFrom – a string. A shorthand for allowContentOf, allowWhere, allowAttributesOf, inheritTypesFrom.
  • additionall, you can define the following is* properties: isBlock, isLimit, isObject. Read about them below.

The is* properties

There are 3 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, a 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's also the $block generic item which has isBlock set to true. Most block type items will inherit from $block (through inheritAllFrom).
  • isLimit – 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 which happen inside a limit element are limitted to its content.
  • isObject – whether item is "self-contained" and should be treated as a whole. Examples of object elements – image, table, video, etc.

Generic items

There are three basic generic items: $root, $block and $text. They are defined as follows:

this.schema.register( '$root', {
    isLimit: true
} );
this.schema.register( '$block', {
    allowIn: '$root',
    isBlock: true
} );
this.schema.register( '$text', {
    allowIn: '$block'
} );

They reflect a typical editor content which 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 {@linkTODO Defining schema} 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
} );

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

schema.register( 'image', {
    allowWhere: '$block',
    allowAttributes: [ 'src', 'alt' ],
    isBlock: true,
    isObject: true
} );

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

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

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

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

Which translates to:

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

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 an normalized way.
  • Remember about definining the is* properties. They don't affect the allowed structures, but they can affect how editor features treat your elements.

Filtering