# Schema

The editor’s schema is available in the [`editor.model.schema`](../../api/module_engine_model_model-Model.md#member-schema) property. It defines allowed model structures (how model elements can be nested), allowed attributes (of both elements and text nodes), and other characteristics (inline vs. block, atomicity in regards of external actions). This information is later used by editing features and the editing engine to decide how to process the model, where to enable features, etc.

Schema rules can be defined by using the [`Schema#register()`](../../api/module_engine_model_schema-ModelSchema.md#function-register) or the [`Schema#extend()`](../../api/module_engine_model_schema-ModelSchema.md#function-extend) methods. The former can be used only once for a given item name which ensures that only a single editing feature can introduce this item. Similarly, `extend()` can only be used for defined items.

Elements and attributes are checked by features separately by using the [`Schema#checkChild()`](../../api/module_engine_model_schema-ModelSchema.md#function-checkChild) and the [`Schema#checkAttribute()`](../../api/module_engine_model_schema-ModelSchema.md#function-checkAttribute) methods.

This article assumes that you have already read the [“Schema”](../architecture/editing-engine.md#schema) section of the [introduction to the editing engine architecture](../architecture/editing-engine.md).

<a id="defining-allowed-structures">

## Defining allowed structures

When a feature introduces a model element, it should register it in the schema. Besides defining that such an element may exist in the model, the feature also needs to define where this element can be placed. This information is provided by the [`allowIn`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-allowIn) property of the [`ModelSchemaItemDefinition`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md):

```js
schema.register( 'myElement', {
	allowIn: '$root'
} );
```

This lets the schema know that `<myElement>` can be a child of `<$root>`. The `$root` element is one of the generic nodes defined by the editing framework. By default, the editor names the main root element a `<$root>`, so the above definition allows `<myElement>` in the main editor element.

In other words, this would be correct:

```xml
<$root>
	<myElement></myElement>
</$root>
```

While this would be incorrect:

```xml
<$root>
	<foo>
		<myElement></myElement>
	</foo>
</$root>
```

To declare which nodes are allowed inside the registered element, the [`allowChildren`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-allowChildren) property could be used:

```js
schema.register( 'myElement', {
	allowIn: '$root',
	allowChildren: '$text'
} );
```

To allow the following structure:

```xml
<$root>
	<myElement>
		foobar
	</myElement>
</$root>
```

Both the `allowIn` and `allowChildren` properties can also be inherited from other `SchemaItemDefinition` items.

> **Note**
>
> You can read more about the format of the item definition in the [`ModelSchemaItemDefinition`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md) API guide.

<a id="disallowing-structures">

## Disallowing structures

The schema, in addition to allowing certain structures, can also be used to ensure some structures are explicitly disallowed. This can be achieved with the use of disallow rules.

Typically, you will use [`disallowChildren`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-disallowChildren) property for that. It can be used to define which nodes are disallowed inside given element:

```js
schema.register( 'myElement', {
	inheritAllFrom: '$block',
	disallowChildren: 'imageInline'
} );
```

In the example above, a new custom element should behave like any block element (paragraph, heading, etc.) but it should not be possible to insert inline images inside it.

<a id="precedence-over-allow-rules">

### Precedence over allow rules

In general, all `disallow` rules have higher priority than their `allow` counterparts. When we also take inheritance into the picture, the hierarchy of rules looks like this (from the highest priority):

1. `disallowChildren` / `disallowIn` from the element’s own definition.
2. `allowChildren` / `allowIn` from the element’s own definition.
3. `disallowChildren` / `disallowIn` from the inherited element’s definition.
4. `allowChildren` / `allowIn` from the inherited element’s definition.

<a id="disallow-rules-examples">

### Disallow rules examples

While disallowing is easy to understand for simple cases, things might start to get unclear when more complex rules are involved. Below are some examples explaining how disallowing works when rules inheriting is involved.

```js
schema.register( 'baseChild' );
schema.register( 'baseParent', { allowChildren: [ 'baseChild' ] } );

schema.register( 'extendedChild', { inheritAllFrom: 'baseChild' } );
schema.register( 'extendedParent', { inheritAllFrom: 'baseParent', disallowChildren: [ 'baseChild' ] } );
```

In this case, `extendedChild` will be allowed in `baseParent` (thanks to inheriting from `baseChild`) and in `extendedParent` (as it inherits `baseParent`).

However, `baseChild` will be allowed only in `baseParent`. Although `extendedParent` inherits all rules from `baseParent`, it specifically disallows `baseChild` as part of its definition.

Below is a different example, where instead `baseChild` is extended with `disallowIn` rule:

```js
schema.register( 'baseParent' );
schema.register( 'baseChild', { allowIn: 'baseParent' } );

schema.register( 'extendedParent', { inheritAllFrom: 'baseParent' } );
schema.register( 'extendedChild', { inheritAllFrom: 'baseChild' } );
schema.extend( 'baseChild', { disallowIn: 'extendedParent' } );
```

This changes how schema rules are resolved. `baseChild` will still be disallowed in `extendedParent` as before. But now, `extendedChild` will be disallowed in `extendedParent` as well. That is because it will inherit this rule from `baseChild`, and there is no other rule that would allow `extendedChild` in `extendedParent`.

Of course, you can mix `allowIn` with `disallowChildren` as well as `allowChildren` with `disallowIn`.

Finally, a situation may come up, when you want to inherit from an item which is already disallowed, but the new element should be re-allowed again. In this case, the definitions should look like this:

```js
schema.register( 'baseParent', { inheritAllFrom: 'paragraph', disallowChildren: [ 'imageInline' ] } );
schema.register( 'extendedParent', { inheritAllFrom: 'baseParent', allowChildren: [ 'imageInline' ] } );
```

Here, `imageInline` is allowed in paragraph, but will not be allowed in `baseParent`. However, `extendedParent` will again re-allow it, as own definitions are more important than inherited definitions.

<a id="defining-additional-semantics">

## Defining additional semantics

In addition to setting allowed structures, the schema can also define additional traits of model elements. By using the `is*` properties, a feature author may declare how a certain element should be treated by other features and by the engine.

Here is a table listing various model elements and their properties registered in the schema:

| Schema entry        | Properties in the [definition](#defining-allowed-structures) |                              |                                |                                |                                        |                                  |
| ------------------- | ------------------------------------------------------------ | ---------------------------- | ------------------------------ | ------------------------------ | -------------------------------------- | -------------------------------- |
|                     | [`isBlock`](#block-elements)                                 | [`isLimit`](#limit-elements) | [`isObject`](#object-elements) | [`isInline`](#inline-elements) | [`isSelectable`](#selectable-elements) | [`isContent`](#content-elements) |
| `$block`            | ✅                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `$container`        | ❌                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `$blockObject`      | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `$inlineObject`     | ❌                                                            | ✅                            | ✅                              | ✅                              | ✅                                      | ✅                                |
| `$clipboardHolder`  | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `$documentFragment` | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `$marker`           | ❌                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `$root`             | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `$inlineRoot`       | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `$text`             | ❌                                                            | ❌                            | ❌                              | ✅                              | ❌                                      | ✅                                |
| `blockQuote`        | ❌                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `bookmark`          | ❌                                                            | ✅                            | ✅                              | ✅                              | ✅                                      | ✅                                |
| `caption`           | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `codeBlock`         | ✅                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `heading1`          | ✅                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `heading2`          | ✅                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `heading3`          | ✅                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `horizontalLine`    | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `imageBlock`        | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `imageInline`       | ❌                                                            | ✅                            | ✅                              | ✅                              | ✅                                      | ✅                                |
| `listItem`          | ✅                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `media`             | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `mergeField`        | ❌                                                            | ✅                            | ✅                              | ✅                              | ✅                                      | ✅                                |
| `mergeFieldBlock`   | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `pageBreak`         | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `paragraph`         | ✅                                                            | ❌                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `rawHtml`           | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `softBreak`         | ❌                                                            | ❌                            | ❌                              | ✅                              | ❌                                      | ❌                                |
| `table`             | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |
| `tableRow`          | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `tableCell`         | ❌                                                            | ✅                            | ❌                              | ❌                              | ✅                                      | ❌                                |
| `tableColumn`       | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `tableColumnGroup`  | ❌                                                            | ✅                            | ❌                              | ❌                              | ❌                                      | ❌                                |
| `tableOfContents`   | ✅                                                            | ✅                            | ✅                              | ❌                              | ✅                                      | ✅                                |

> **Note**
>
> Object elements, including `$blockObject`, `$inlineObject`, `bookmark`, `horizontalLine`, `imageBlock`, `imageInline`, `media`, `mergeField`, `mergeFieldBlock`, `pageBreak`, `rawHtml`, `table`, `tableOfContents`, inherit the following properties:
>
> * The value of `isLimit` is `true` for those elements because all [objects](#object-elements) are automatically [limit elements](#limit-elements).
> * The value of `isSelectable` is `true` for those elements because all [objects](#object-elements) are automatically [selectable elements](#selectable-elements).
> * The value of `isContent` is `true` for those elements because all [objects](#object-elements) are automatically [content elements](#content-elements).

<a id="limit-elements">

### Limit elements

Consider a feature like an image caption. The caption text area should construct a boundary to some internal actions:

* A selection that starts inside should not end outside.
* Pressing `Backspace` or `Delete` should not delete the area. Pressing `Enter` should not split the area.

It should also act as a boundary for external actions. This is mostly enforced by a selection post-fixer that ensures that a selection that starts outside, should not end inside. It means that most actions will either apply to the “outside” of such an element or to the content inside it.

Taken these characteristics, the image caption should be defined as a limit element by using the [`isLimit`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-isLimit) property.

```js
schema.register( 'myCaption', {
	isLimit: true
} );
```

The engine and various features then check it via [`Schema#isLimit()`](../../api/module_engine_model_schema-ModelSchema.md#function-isLimit) and can act accordingly.

> **Note**
>
> “Limit element” does not mean “editable element.” The concept of “editable element” is reserved for the view and expressed by the [`ViewEditableElement` class](../../api/module_engine_view_editableelement-ViewEditableElement.md).

<a id="object-elements">

### Object elements

For an image caption like in the example above it does not make much sense to select the caption box, then copy or drag it somewhere else.

A caption without the image it describes makes little sense. The image, however, is more self-sufficient. Most likely users should be able to select the entire image (with all its internals), then copy or move it around. The [`isObject`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-isObject) property should be used to mark such behavior.

```js
schema.register( 'myImage', {
	isObject: true
} );
```

The [`Schema#isObject()`](../../api/module_engine_model_schema-ModelSchema.md#function-isObject) can later be used to check this property.

> **Note**
>
> There are also the `$blockObject` and the `$inlineObject` generic items which have the `isObject` property set to `true`. Most object-type items will inherit from `$blockObject` or `$inlineObject` (through `inheritAllFrom`).

> **Note**
>
> Every object is automatically also:
>
> * A [limit element](#limit-elements) – For every element with `isObject` set to `true`, [`Schema#isLimit( element )`](../../api/module_engine_model_schema-ModelSchema.md#function-isLimit) will always return `true`.
> * A [selectable element](#selectable-elements) – For every element with `isObject` set to `true`, [`Schema#isSelectable( element )`](../../api/module_engine_model_schema-ModelSchema.md#function-isSelectable) will always return `true`.
> * A [content element](#content-elements) – For every element with `isObject` set to `true`, [`Schema#isContent( element )`](../../api/module_engine_model_schema-ModelSchema.md#function-isContent) will always return `true`.

<a id="block-elements">

### Block elements

Generally speaking, content is usually made out of blocks like paragraphs, list items, images, headings, etc. All these elements should be marked as blocks by using [`isBlock`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-isBlock).

Schema items with the `isBlock` property set are (among others) affecting the [`Selection#getSelectedBlocks()`](../../api/module_engine_model_documentselection-ModelDocumentSelection.md#function-getSelectedBlocks) behavior and by that allow setting block level attributes like `alignment` to appropriate elements.

It is important to remember that a block should not allow another block inside. Container elements like `<blockQuote>`, which can contain other block elements, should not be marked as blocks.

> **Note**
>
> There are also the `$block` and the `$blockObject` generic items which have the `isBlock` property set to `true`. Most block-type items will inherit from `$block` or `$blockObject` (through `inheritAllFrom`).
>
> Note that every item that inherits from `$block` has `isBlock` set, but not every item with `isBlock` set has to be a `$block`.

<a id="inline-elements">

### Inline elements

In the editor, all HTML formatting elements such as `<strong>` or `<code>` are represented by text attributes. Therefore, inline model elements are not supposed to be used for these scenarios. To learn more about how text attributes work and how they are converted to inline elements in the view, see the [Attributes and inline formatting](conversion/attributes.md) guide.

Currently, the [`isInline`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-isInline) property is used for the `$text` token (so, text nodes) and elements such as `<softBreak>`, `<imageInline>` or placeholder elements such as described in the [Implementing an inline widget](../tutorials/widgets/implementing-an-inline-widget.md) tutorial.

The support for inline elements in CKEditor 5 is so far limited to self-contained elements. Because of this, all elements marked with `isInline` should also be marked with `isObject`.

> **Note**
>
> There is also the `$inlineObject` generic item which has the `isInline` property set to `true`. Most inline object type items will inherit from `$inlineObject` (through `inheritAllFrom`).

<a id="selectable-elements">

### Selectable elements

Elements that users can select as a whole (with all their internals) and then, for instance, copy them or apply formatting, are marked with the [`isSelectable`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-isSelectable) property in the schema:

```js
schema.register( 'mySelectable', {
	isSelectable: true
} );
```

The [`Schema#isSelectable()`](../../api/module_engine_model_schema-ModelSchema.md#function-isSelectable) method can later be used to check this property.

> **Note**
>
> All [object elements](#object-elements) are selectable by default. There are other selectable elements registered in the editor, though. For instance, there is also the `tableCell` model element (rendered as a `<td>` in the editing view) that is selectable while **not** registered as an object. The [table selection](../../features/tables/tables.md#table-selection) plugin takes advantage of this fact and allows users to create rectangular selections made of multiple table cells.

<a id="content-elements">

### Content elements

You can tell content model elements from other elements by looking at their representation in the editor data (you can use [`editor.getData()`](../../api/module_editor-classic_classiceditor-ClassicEditor.md#function-getData) or [`Model#hasContent()`](../../api/module_engine_model_model-Model.md#function-hasContent) to check this out).

Elements such as images or media will **always** find their way into the editor data and this is what makes them content elements. They are marked with the [`isContent`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md#member-isContent) property in the schema:

```js
schema.register( 'myImage', {
	isContent: true
} );
```

The [`Schema#isContent()`](../../api/module_engine_model_schema-ModelSchema.md#function-isContent) method can later be used to check this property.

At the same time, elements like paragraphs, list items, or headings **are not** content elements because they are skipped in the editor output when they are empty. From the data perspective, they are transparent unless they contain other content elements (an empty paragraph is as good as no paragraph).

> **Note**
>
> [Object elements](#object-elements) and [`$text`](#generic-items) are content by default.

<a id="generic-items">

## Generic items

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

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

schema.register( '$inlineRoot', {
	allowContentOf: '$block',
	allowAttributesOf: '$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
} );
```

These definitions can then be reused by features to create their own definitions in a more extensible way.

The `$inlineRoot` element is an alternative to `$root` for roots that should only contain inline content (text and inline objects) rather than block content. It inherits attributes from `$root` so that features that set attributes on the root (for example, to track document-level metadata) work the same way regardless of root type. You can use it via the [`config.root.modelElement`](../../api/module_core_editor_editorconfig-RootConfig.md#member-modelElement) option.

For example, the [`Paragraph`](../../api/module_paragraph_paragraph-Paragraph.md) feature will define its item as:

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

Which translates to:

```js
schema.register( 'paragraph', {
	allowWhere: '$block',
	allowContentOf: '$block',
	allowAttributesOf: '$block',
	inheritTypesFrom: '$block'
} );
```

And this can be read as:

* The `<paragraph>` element will be allowed in elements in which `<$block>` is allowed (like in `<$root>`).
* The `<paragraph>` element will allow all nodes that are allowed in `<$block>` (like `$text`).
* The `<paragraph>` element will allow all attributes allowed in `<$block>`.
* The `<paragraph>` element will inherit all `is*` properties of `<$block>` (like `isBlock`).

Thanks to the fact that the `<paragraph>` definition is inherited from `<$block>` other features can use the `<$block>` type to indirectly extend the `<paragraph>` definition. For example, the [`BlockQuote`](../../api/module_block-quote_blockquote-BlockQuote.md) feature does this:

```js
schema.register( 'blockQuote', {
	inheritAllFrom: '$container'
} );
```

Because `<$block>` is allowed in `<$container>` (see `schema.register( '$block' ...)`), despite the fact that the block quote and paragraph features know nothing about each other, paragraphs will be allowed in block quotes: the schema rules allow chaining.

Taking this even further, if anyone registers a `<section>` element (with the `allowContentOf: '$root'` rule), because `<$container>` is also allowed in `<$root>` (see `schema.register( '$container' ...)`) the `<section>` elements will allow block quotes out–of–the–box.

> **Note**
>
> You can read more about the format of the item definition in [`ModelSchemaItemDefinition`](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md).

<a id="relations-between-generic-items">

### Relations between generic items

Relations between generic items (which one can be used where) can be visualized by the following abstract structure:

```xml
<$root>
	<$block>				<!-- example: <paragraph>, <heading1> -->
		<$text/>
		<$inlineObject/>	<!-- example: <imageInline> -->
	</$block>
	<$blockObject/>			<!-- example: <imageBlock>, <table> -->
	<$container>			<!-- example: <blockQuote> -->
		<$container/>
		<$block/>
		<$blockObject/>
	</$container>
</$root>

<$inlineRoot>				<!-- like $root but for inline content only -->
	<$text/>
	<$inlineObject/>
</$inlineRoot>
```

The above rules will be met for instance by such a model content:

```xml
<$root>
	<heading1>				<!-- inheritAllFrom: $block -->
		<$text/>			<!-- allowIn: $block -->
	</heading1>
	<paragraph>				<!-- inheritAllFrom: $block -->
		<$text/>			<!-- allowIn: $block -->
		<softBreak/>		<!-- allowWhere: $text -->
		<$text/>			<!-- allowIn: $block -->
		<imageInline/>		<!-- inheritAllFrom: $inlineObject -->
	</paragraph>
	<imageBlock>			<!-- inheritAllFrom: $blockObject -->
		<caption>			<!-- allowIn: imageBlock, allowContentOf: $block -->
			<$text/>		<!-- allowIn: $block -->
		</caption>
	</imageBlock>
	<blockQuote>					<!-- inheritAllFrom: $container -->
		<paragraph/>				<!-- inheritAllFrom: $block -->
		<table>						<!-- inheritAllFrom: $blockObject -->
			<tableRow>				<!-- allowIn: table -->
				<tableCell>			<!-- allowIn: tableRow, allowContentOf: $container -->
					<paragraph>		<!-- inheritAllFrom: $block -->
						<$text/>	<!-- allowIn: $block -->
					</paragraph>
				</tableCell>
			</tableRow>
		</table>
	</blockQuote>
</$root>
```

Which, in turn, has these [semantics](#defining-additional-semantics):

```xml
<$root>						<!-- isLimit: true -->
	<heading1>				<!-- isBlock: true -->
		<$text/>			<!-- isInline: true, isContent: true -->
	</heading1>
	<paragraph>				<!-- isBlock: true -->
		<$text/>			<!-- isInline: true, isContent: true -->
		<softBreak/>		<!-- isInline: true -->
		<$text/>			<!-- isInline: true, isContent: true -->
		<imageInline/>		<!-- isInline: true, isObject: true -->
	</paragraph>
	<imageBlock>			<!-- isBlock: true, isObject: true -->
		<caption>			<!-- isLimit: true -->
			<$text/>		<!-- isInline: true, isContent: true -->
		</caption>
	</imageBlock>
	<blockQuote>
		<paragraph/>				<!-- isBlock: true -->
		<table>						<!-- isBlock: true, isObject: true -->
			<tableRow>				<!-- isLimit: true -->
				<tableCell>			<!-- isLimit: true -->
					<paragraph>		<!-- isBlock: true -->
						<$text/>	<!-- isInline: true, isContent: true -->
					</paragraph>
				</tableCell>
			</tableRow>
		</table>
	</blockQuote>
</$root>
```

<a id="custom-root-elements">

### Custom root elements

The generic `$root` / `$container` / `$block` chain described above is keyed on the element name `$root`. By default, a root is created as `<$root>`, so every rule of the form `allowIn: '$root'` or `allowAttributesOf: '$root'` applies to it automatically.

You can change the element name used for a root via the [`config.root.modelElement`](../../api/module_core_editor_editorconfig-RootConfig.md#member-modelElement) (or `config.roots.<rootName>.modelElement` for the [multi-root editor](../../api/module_editor-multi-root_multirooteditor-MultiRootEditor.md)) option. When you do, the created root is `<myRoot>` instead of `<$root>`, and **it does not automatically inherit the `$root` chain**. Features that define their elements as `allowIn: '$root'`, `allowContentOf: '$root'`, or `allowAttributesOf: '$root'` will not apply to the custom root unless you opt in.

Declare the custom root in the schema and pick which parts of the `$root` chain you want:

```js
// Inherit everything $root provides - allowed children, attributes, and is* flags.
schema.register( 'myRoot', {
	inheritAllFrom: '$root',
	allowChildren: [ '$container', '$block' ]
} );

// Or opt in selectively - e.g. only inherit attributes (the `$inlineRoot` pattern).
schema.register( 'myInlineRoot', {
	allowContentOf: '$block',
	allowAttributesOf: '$root',
	isLimit: true
} );
```

Key rules to remember for custom roots:

* **Block / container content.** If the root should accept the generic block chain, declare `allowChildren: [ '$container', '$block' ]` (or `inheritAllFrom: '$root'`). Otherwise `$block`-based elements like `<paragraph>` and `$container`-based elements like `<blockQuote>` will not be allowed inside it.
* **Root attributes.** Attributes registered via [`editor.registerRootAttribute()`](../../api/module_core_editor_editor-Editor.md#function-registerRootAttribute) are attached only to the `$root` schema element. Custom roots must opt into this chain via `allowAttributesOf: '$root'` to receive them.
* **Data conversion context.** When calling [`editor.data.parse()`](../../api/module_engine_controller_datacontroller-DataController.md#function-parse) or [`editor.data.toModel()`](../../api/module_engine_controller_datacontroller-DataController.md#function-toModel) against a custom root, pass the target root element (or its configured model element name) as the `context` argument. The default `'$root'` only matches the generic root and can produce wrong conversion results.

The engine ships with one ready-made custom root definition - `$inlineRoot` - for roots that should only contain inline content. You can use it out of the box via `config.root.modelElement: '$inlineRoot'` without adding your own schema registration.

<a id="defining-advanced-rules-using-callbacks">

## Defining advanced rules using callbacks

The base [declarative `SchemaItemDefinition` API](../../api/module_engine_model_schema-ModelSchemaItemDefinition.md) is by its nature limited, and some custom rules might not be possible to be implemented this way.

For this reason, it is also possible to define schema checks by providing callbacks. This gives you flexibility to implement any logic that you need.

These callbacks can be set both for child checks (model structure checks) and attribute checks.

Note that the callbacks take precedence over the rules defined through the declarative API and can overwrite these rules.

<a id="child-checks-structure-checks">

### Child checks (structure checks)

Using [`Schema#addChildCheck()`](../../api/module_engine_model_schema-ModelSchema.md#function-addChildCheck) you can provide function callbacks to implement specific advanced rules for checking the model structure.

You can provide callbacks that are fired only when a specific child is checked, or generic callbacks fired for all checks performed by the schema.

Below is an example of a specific callback, that disallows inline images inside code blocks:

```js
schema.addChildCheck( context => {
	if ( context.endsWith( 'codeBlock' ) ) {
		return false;
	}
}, 'imageInline' );
```

The second parameter (`'imageInline'`) specifies that the callback will be used only if `imageInline` is being checked.

You can also use a callback to force given item to be allowed. For example, allow special `$marker` item to be allowed everywhere:

```js
schema.addChildCheck( () => true, '$marker' );
```

Note that a callback may return `true`, `false`, or no value (`undefined`). If `true` or `false` is returned, the decision was made and further callbacks or declarative rules will not be checked. The item will be allowed or disallowed. If no value is returned, further checks will decide whether the item is allowed or not.

In some cases, you may need to define a generic listener that will be fired on every schema check.

For instance, to disallow all block objects (for example tables) inside a block quotes, you can define following callback:

```js
schema.addChildCheck( ( context, childDefinition ) => {
	if ( context.endsWith( 'blockQuote' ) && childDefinition.isBlock && childDefinition.isObject ) {
		return false;
	}
} );
```

The above will trigger on every `checkChild()` call giving you more flexibility. However, please keep in mind that using multiple generic callbacks might negatively impact the editor performance.

<a id="attribute-checks">

### Attribute checks

Similarly, you can define callbacks to check whether given attribute is or is not allowed on given item.

This time, you will use [`Schema#addAttributeCheck()`](../../api/module_engine_model_schema-ModelSchema.md#function-addAttributeCheck) to provide the callback.

For example, allow custom attribute `headingMarker` on all headings:

```js
schema.addAttributeCheck( ( context, attributeName ) => {
	const isHeading = context.last.name.startsWith( 'heading' );

	if ( isHeading ) {
		return true;
	}
}, 'headingMarker' );
```

Generic callbacks are available too. For example, disallow formatting attributes (like bold or italic) on text inside all headings:

```js
schema.addAttributeCheck( ( context, attributeName ) => {
	const parent = context.getItem( context.length - 2 );
	const insideHeading = parent && parent.name.startsWith( 'heading' );

	if ( insideHeading && context.endsWith( '$text' ) && schema.getAttributeProperties( attributeName ).isFormatting ) {
		return false;
	}
} );
```

All notes related to child check callbacks apply to attribute callbacks as well.

<a id="implementing-additional-constraints">

## Implementing additional constraints

Schema’s capabilities are limited to simple (and atomic) [`Schema#checkChild()`](../../api/module_engine_model_schema-ModelSchema.md#function-checkChild) and [`Schema#checkAttribute()`](../../api/module_engine_model_schema-ModelSchema.md#function-checkAttribute) checks on purpose. One may imagine that the schema should support defining more complex rules such as “element `<x>` must be always followed by `<y>`.” While it is feasible to create an API that would enable feeding the schema with such definitions, it is unfortunately unrealistic to then expect that every editing feature will consider these rules when processing the model. It is also unrealistic to expect that it will be done automatically by the schema and the editing engine themselves.

For instance, let’s get back to the “element `<x>` must be always followed by `<y>`” rule and this initial content:

```xml
<$root>
	<x>foo</x>
	<y>bar[bom</y>
	<z>bom]bar</z>
</$root>
```

Now imagine that the user presses the “Block quote” button. Normally it would wrap the two selected blocks (`<y>` and `<z>`) with a `<blockQuote>` element:

```xml
<$root>
	<x>foo</x>
	<blockQuote>
		<y>bar[bom</y>
		<z>bom]bar</z>
	</blockQuote>
</$root>
```

However, it turns out that this creates an incorrect structure – `<x>` is not followed by `<y>` anymore.

What should happen instead? There are at least 4 possible solutions: the block quote feature should not be applicable in such a context, someone should create a new `<y>` right after `<x>`, `<x>` should be moved inside `<blockQuote>` together with `<y>` or vice versa.

While this is a relatively simple scenario (unlike most real-time collaborative editing scenarios), it turns out that it is already hard to say what should happen and who should react to fix this content.

Therefore, if your editor needs to implement such rules, you should do that through [model’s post-fixers](../../api/module_engine_model_document-ModelDocument.md#function-registerPostFixer) fixing incorrect content or actively prevent such situations (for example, by disabling certain features). It means that these constraints will be defined specifically for your scenario by your code which makes their implementation much easier.

To sum up, the answer to who and how should implement additional constraints is: your features or your editor through the CKEditor 5 API.

<a id="who-checks-the-schema">

## Who checks the schema?

The CKEditor 5 API exposes many ways to work on (change) the model. It can be done [through the writer](../architecture/editing-engine.md#changing-the-model), via methods like [`Model#insertContent()`](../../api/module_engine_model_model-Model.md#function-insertContent), via commands, and so on.

<a id="low-level-apis">

### Low-level APIs

The lowest-level API is the writer (to be precise, there are also raw operations below, but they are used for special cases only). It allows applying atomic changes to the content like inserting, removing, moving or splitting nodes, setting and removing an attribute, etc. It is important to know that the **writer does not prevent from applying changes that violate rules defined in the schema**.

The reason for this is that when you implement a command or any other feature you may need to perform multiple operations to do all the necessary changes. The state in the meantime (between these atomic operations) may be incorrect. The writer must allow that.

For instance, you need to move `<foo>` from `<$root>` to `<bar>` and (at the same time) rename it to `<oof>`. But the schema defines that `<oof>` is not allowed in `<$root>` and `<foo>` is disallowed in `<bar>`. If the writer checked the schema, it would complain regardless of the order of `rename` and `move` operations.

You can argue that the engine could handle this by checking the schema at the end of a [`Model#change()` block](../../api/module_engine_model_model-Model.md#function-change) (it works like a transaction – the state needs to be correct at the end of it). This approach, however, was not adopted, as there are the following problems:

* How to fix the content after a transaction is committed? It is impossible to implement a reasonable heuristic that would not break the content from the user’s perspective.
* The model can become invalid during real-time collaborative changes. Operational Transformation, while implemented by us in a rich form (with 11 types of operations instead of the base 3), ensures conflict resolution and eventual consistency, but not the model’s validity.

Therefore, we chose to handle such situations on a case-by-case basis, using more expressive and flexible [model’s post-fixers](../../api/module_engine_model_document-ModelDocument.md#function-registerPostFixer). Additionally, we moved the responsibility of checking the schema to features. They can make a lot better decisions before making changes. You can read more about this in the [“Implementing additional constraints”](#implementing-additional-constraints) section above.

<a id="high-level-apis">

### High-level APIs

What about other, higher-level methods? **We recommend that all APIs built on top of the writer should check the schema.**

For instance, the [`Model#insertContent()`](../../api/module_engine_model_model-Model.md#function-insertContent) method will make sure that inserted nodes are allowed in the place of their insertion. It may also attempt to split the insertion container (if allowed by the schema) if that will make the element to insert allowed, and so on.

Similarly, commands – if implemented correctly – [get disabled](../../api/module_core_command-Command.md#member-isEnabled) if they should not be executed in the current place.

Finally, the schema plays a crucial role during the conversion from the view to the model (also called “upcasting”). During this process converters decide whether they can convert specific view elements or attributes to the given positions in the model. Thanks to that if you tried to load incorrect data to the editor or when you paste content copied from another website, the structure and attributes of the data get adjusted to the current schema rules.

> **Note**
>
> Some features may miss schema checks. If you happen to find such a scenario, do not hesitate to [report it to us](https://github.com/ckeditor/ckeditor5/issues).

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../llms.txt)