Schema awareness

Continuation from the AI agent chatbot guide

This guide continues the AI agent chatbot guide. Read it first.

A Tiptap schema describes the elements the document can (and cannot) contain. Tiptap's schema awareness capabilities allow AI models to understand the document better and generate custom elements.

Why schema awareness?

Without schema awareness, the AI model might generate content that the Tiptap editor does not support. For example, it might generate a table in a document that does not support tables. With schema awareness enabled, the AI model will know that table nodes are not supported and will refuse to generate them.

Guide: give schema awareness to your AI model

Integrate the schema awareness feature to an AI agent like the one built in the AI agent chatbot guide.

Step 1: get the schema awareness data

Get the schema awareness data from the Server AI Toolkit package. This data contains information about the document's schema in a format optimized for the AI model.

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { getSchemaAwarenessData } from '@tiptap-pro/server-ai-toolkit'

const editor = new Editor({
  extensions: [StarterKit],
})

// Retrieve the schema awareness data
const schemaAwarenessData = getSchemaAwarenessData(editor)

The getSchemaAwarenessData function returns schema awareness data that describes the document structure for the Server AI Toolkit API.

Store the schema awareness data

The schema awareness data returned by getSchemaAwarenessData is a JSON-serializable object that you can store in your database. You don't need to generate it every time—only update it when your Editor extensions or schema change.

Step 2: configure custom nodes

If your document contains custom Nodes and Marks, add the addJsonSchemaAwareness option to the extension configuration. This way, the AI model will be able to generate this custom Node or Mark accurately.

For example, if you have a custom node called 'alert', you can allow the AI model to generate it by configuring it like this:

import { Node } from '@tiptap/core'
import { z } from 'zod'

const CustomExtension = Node.create({
  name: 'alert',

  addAttributes() {
    return {
      type: {
        default: 'info',
        parseHTML: (element) => element.getAttribute('data-type'),
        renderHTML: (attributes) => {
          if (!attributes.type) {
            return {}
          }
          return {
            'data-type': attributes.type,
          }
        },
      },
    }
  },

  addJsonSchemaAwareness() {
    return {
      name: 'Alert Box',
      description: `A highlighted box used to display important information, warnings, or tips to the user.
It can contain inline content like text and formatting marks.`,
      attributes: {
        type: z
          .enum(['info', 'warning', 'error', 'success'])
          .describe(
            'The type of alert. Can be one of these 4 values: info, warning, error, or success',
          ),
      },
    }
  },

  parseHTML() {
    return [
      {
        tag: 'div[data-alert]',
      },
    ]
  },

  renderHTML({ HTMLAttributes }) {
    return ['div', { ...HTMLAttributes, 'data-alert': '' }, 0]
  },

  // ... Other extension configuration options
})

The addJsonSchemaAwareness function should return an object with:

name (string): The human-readable name of the element in English
description? (string): Explanation of the element in English for the AI model
attributes? (Record<string, z.ZodTypeAny>): Possible attributes of the element, defined as Zod schemas that will be converted to JSON schemas

What about official Tiptap extensions?

Schema awareness for official Tiptap extensions is automatically supported by the Server AI Toolkit. They do not need to be configured. You can still override the default schema awareness information for official Tiptap extensions by extending the extension and adding the addJsonSchemaAwareness option.

Next steps

PreviouslyAI agent chatbot

Next upComments