Schema

Every Slate editor has a "schema" associated with it, which contains information about the structure of its content. For the most basic cases, you'll just rely on Slate's default core schema. But for advanced use cases, you can enforce rules about what the content of a Slate document can contain.

Properties

{
  document: Object,
  blocks: Object,
  inlines: Object,
}

The top-level properties of a schema give you a way to define validation "rules" that the schema enforces.

document

Object

{
  document: {
    nodes: [
      {
        match: { type: 'paragraph' },
      },
    ]
  }
}

A set of validation rules that apply to the top-level document.

blocks

Object

{
  blocks: {
    list: {
      nodes: [{
        match: { type: 'item' }
      }]
    },
    item: {
      parent: { type: 'list' }
    },
  }
}

A dictionary of blocks by type, each with its own set of validation rules.

inlines

Object

{
  inlines: {
    emoji: {
      isVoid: true,
      nodes: [{
        match: { object: 'text' }
      }]
    },
  }
}

A dictionary of inlines by type, each with its own set of validation rules.

Rule Properties

{
  data: Object,
  first: Object|Array,
  isVoid: Boolean,
  last: Object|Array,
  marks: Array,
  match: Object|Array,
  nodes: Array,
  normalize: Function,
  parent: Object|Array,
  text: RegExp,
}

Slate schemas are built using a set of validation rules. Each of the properties will validate certain pieces of the document based on the properties it defines.

data

Object

{
  data: {
    level: 2,
    href: v => isUrl(v),
  }
}

A dictionary of data attributes and their corresponding values or validation functions. The functions should return a boolean indicating whether the data value is valid or not.

first

Object|Array

{
  first: { type: 'quote' },
}
{
  first: [{ type: 'quote' }, { type: 'paragraph' }],
}

Will validate the first child node against a match.

isVoid

Boolean

{
  isVoid: true,
}

Will determine whether the node is treated as a "void" node or not, making its content a black box that Slate doesn't control editing for.

last

Object|Array

{
  last: { type: 'quote' },
}
{
  last: [{ type: 'quote' }, { type: 'paragraph' }],
}

Will validate the last child node against a match.

next

Object|Array

{
  next: { type: 'quote' },
}
{
  next: [{ type: 'quote' }, { type: 'paragraph' }],
}

Will validate the next sibling node against a match.

nodes

Array

{
  nodes: [
    {
      match: [{ type: 'image' }, { type: 'video' }],
      min: 1,
      max: 3,
    },
    {
      match: { type: 'paragraph' },
      min: 0,
    },
  ],
}

Will validate a node's children. The nodes definitions can declare a match as well as min and max properties.

🤖 The nodes array is order-sensitive! The example above will require that the first node be either an image or video, and that it be followed by one or more paragraph nodes.

marks

Array

{
  marks: [{ type: 'bold' }, { type: 'italic' }]
}

Will validate a node's marks. The marks definitions can declare the type property, providing a list of mark types to be allowed. If declared, any marks that are not in the list will be removed.

normalize

normalize(change: Change, error: SlateError) => Void

{
  normalize: (change, error) => {
    switch (error.code) {
      case 'child_object_invalid':
        change.wrapBlockByKey(error.child.key, 'paragraph')
        return
      case 'child_type_invalid':
        change.setNodeByKey(error.child.key, 'paragraph')
        return
    }
  }
}

A function that can be provided to override the default behavior in the case of a rule being invalid. By default, Slate will do what it can, but since it doesn't know much about your schema, it will often remove invalid nodes. If you want to override this behavior and "fix" the node instead of removing it, pass a custom normalize function.

For more information on the arguments passed to normalize, see the Errors section.

parent

Object|Array

{
  parent: { type: 'list' },
}
{
  parent: [{ type: 'ordered_list' }, { type: 'unordered_list' }],
}

Will validate a node's parent against a match.

previous

Object|Array

{
  previous: { type: 'quote' },
}
{
  previous: [{ type: 'quote' }, { type: 'paragraph' }],
}

Will validate the previous sibling node against a match.

text

RegExp|Function

{
  text: /^\w+$/
}
{
  text: string => string === 'valid'
}

Will validate a node's text with a regex or function.

Static Methods

Schema.create

Schema.create(properties: Object) => Schema

Create a new Schema instance with properties.

Schema.fromJSON

Schema.fromJSON(object: Object) => Schema

Create a schema from a JSON object.

Schema.isSchema

Schema.isSchema(maybeSchema: Any) => Boolean

Returns a boolean if the passed in argument is a Schema.

Instance Methods

toJSON

toJSON() => Object

Returns a JSON representation of the schema.

Errors

When supplying your own normalize property for a schema rule, it will be called with (change, error). The error code will be one of a set of potential code strings, and it will contain additional helpful properties depending on the type of error.

'child_object_invalid'

{
  child: Node,
  index: Number,
  node: Node,
  rule: Object,
}

Raised when the object property of a child node is invalid.

'child_required'

{
  index: Number,
  node: Node,
  rule: Object,
}

Raised when a child node was required but none was found.

'child_type_invalid'

{
  child: Node,
  index: Number,
  node: Node,
  rule: Object,
}

Raised when the type property of a child node is invalid.

'child_unknown'

{
  child: Node,
  index: Number,
  node: Node,
  rule: Object,
}

Raised when a child was not expected but one was found.

'first_child_object_invalid'

{
  child: Node,
  node: Node,
  rule: Object,
}

Raised when the object property of the first child node is invalid, when a specific first rule was defined in a schema.

'first_child_type_invalid'

{
  child: Node,
  node: Node,
  rule: Object,
}

Raised when the type property of the first child node is invalid, when a specific first rule was defined in a schema.

'last_child_object_invalid'

{
  child: Node,
  node: Node,
  rule: Object,
}

Raised when the object property of the last child node is invalid, when a specific last rule was defined in a schema.

'last_child_type_invalid'

{
  child: Node,
  node: Node,
  rule: Object,
}

Raised when the type property of the last child node is invalid, when a specific last rule was defined in a schema.

'next_sibling_object_invalid'

{
  next: Node,
  node: Node,
  rule: Object,
}

Raised when the object property of the next sibling node is invalid, when a specific next rule was defined in a schema.

'next_sibling_type_invalid'

{
  next: Node,
  node: Node,
  rule: Object,
}

Raised when the type property of the next sibling node is invalid, when a specific next rule was defined in a schema.

'node_data_invalid'

{
  key: String,
  node: Node,
  rule: Object,
  value: Mixed,
}

Raised when the data property of a node contains an invalid entry.

'node_is_void_invalid'

{
  node: Node,
  rule: Object,
}

Raised when the isVoid property of a node is invalid.

'node_mark_invalid'

{
  mark: Mark,
  node: Node,
  rule: Object,
}

Raised when one of the marks in a node is invalid.

'node_text_invalid'

{
  text: String,
  node: Node,
  rule: Object,
}

Raised when the text content of a node is invalid.

'parent_object_invalid'

{
  node: Node,
  parent: Node,
  rule: Object,
}

Raised when the object property of the parent of a node is invalid, when a specific parent rule was defined in a schema.

'parent_type_invalid'

{
  node: Node,
  parent: Node,
  rule: Object,
}

Raised when the type property of the parent of a node is invalid, when a specific parent rule was defined in a schema.

'previous_sibling_object_invalid'

{
  previous: Node,
  node: Node,
  rule: Object,
}

Raised when the object property of the previous sibling node is invalid, when a specific previous rule was defined in a schema.

'previous_sibling_type_invalid'

{
  previous: Node,
  node: Node,
  rule: Object,
}

Raised when the type property of the previous sibling node is invalid, when a specific previous rule was defined in a schema.

PreviousRangeNextSelection

Last updated