Schema awareness

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.

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 string

Get the schema awareness string from the AI Toolkit. This string contains a message describing the document's schema, that is optimized for the AI model.

const toolkit = getAiToolkit(editor)
// Retrieve the schema awareness string
const schemaAwareness = toolkit.getHtmlSchemaAwareness()

Step 2 (optional): configure custom nodes

If your document contains custom Nodes and Marks, add the addHtmlSchemaAwareness 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'

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

  addHtmlSchemaAwareness() {
    return {
      tag: 'div',
      name: 'Alert Box',
      description: `A highlighted box used to display important information, warnings, or tips to the user.
It can have inline content inside like text and formatting tags.`,
      attributes: [
        {
          attr: 'data-alert',
          value: '',
          description: 'Indicates that this is an alert box',
        },
        {
          attr: 'data-type',
          description:
            'The type of alert. Can be one of these 4 values: info, warning, error, or success',
        },
      ],
    }
  },

  // ... Other extension configuration options
})

Alternatively, you can configure the customNodes option of the getHtmlSchemaAwareness method. Learn more about the configuration options in the API Reference.

Step 3: add the schema awareness string to the system prompt

When you call the AI model, send the schema awareness string as a parameter to the API endpoint that returns the AI model response.

The code below shows an API endpoint built with Next.js and the Vercel AI SDK, like the one in the AI agent chatbot guide.

// app/page.tsx
import { useEditor } from '@tiptap/react'
import { getAiToolkit } from '@tiptap-pro/ai-toolkit'
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport } from 'ai'

// Inside the React component

const editor = useEditor()
const toolkit = getAiToolkit(editor)

// Get the schema awareness string
const schemaAwareness = toolkit.getHtmlSchemaAwareness()

const { messages } = useChat({
  transport: new DefaultChatTransport({
    api: '/api/chat',
    // Send the schema awareness string as a parameter to the API endpoint
    body: { schemaAwareness },
  }),
  // ...
})

Then, inside the API endpoint handler, add the schema awareness string to the end of the system prompt.

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai'
import { toolDefinitions } from '@tiptap-pro/ai-toolkit-ai-sdk'
import { convertToModelMessages, streamText, UIMessage } from 'ai'

export async function POST(req: Request) {
  // Get the schema awareness string from the request body
  const { messages, schemaAwareness }: { messages: UIMessage[]; schemaAwareness: string } =
    await req.json()

  const result = streamText({
    model: openai('gpt-5'),
    // Add the schema awareness string to end of the system prompt
    system: `You are an assistant that can edit rich text documents.
${schemaAwareness}`,
    messages: convertToModelMessages(messages),
    tools: toolDefinitions(),
  })

  return result.toUIMessageStreamResponse()
}

You've now set up schema awareness for your AI model.

End result

The app below is a variant of the AI agent chatbot demo with schema awareness configured. Try asking the AI to create an alert box: the AI will recognize the custom element and insert it into the document.

See the source code on GitHub.

API Reference

getHtmlSchemaAwareness

Returns a string describing the document's schema. This string should be added to the end of the system prompt that is sent to the AI model.

Currently, the getHtmlSchemaAwareness method only supports AI models that generate HTML content. We plan to add support for other formats in the future.

Parameters (GetHtmlSchemaAwarenessOptions)

• customNodes? (HtmlItem[]): Custom schema awareness items to include in addition to the default ones. The values defined in this option will override the schema awareness data defined in the addHtmlSchemaAwareness configuration option of custom extensions. They will also override the schema awareness data of official Tiptap extensions. Default: [].

Every HtmlItem object contains these properties:

• extensionName (string): The name of the extension that provides this element
• tag (string): The HTML tag name for this element
• name (string): The human-readable name of the element in English
• description? (string | null): Explanation of what the element is and how it is displayed
• attributes? (HtmlAttribute[]): Possible attributes of the HTML tag. If undefined, there are no attributes. Each HtmlAttribute object contains these properties:
  • attr (string): The name of the attribute in the HTML code
  • value? (string): If value is not undefined, the attribute always has that value for this element. This is used for attributes that have fixed values
  • description? (string | null): Explanation of the attribute in English for AI model understanding

Returns

string: Human-readable schema awareness text suitable for system prompts

Example

// Retrieve the schema awareness string
const schemaAwareness = toolkit.getHtmlSchemaAwareness()

addHtmlSchemaAwareness (extension configuration option)

Add schema awareness information about a custom Node or Mark. This option is used to configure custom nodes and marks for the AI model to know about them.

This configuration option is available for custom Node and Mark extensions.

Parameters (HtmlItem)

• tag (string): The HTML tag name for this element
• name (string): The human-readable name of the element in English
• description? (string | null): Explanation of what the element is and how it is displayed
• attributes? (HtmlAttribute[]): Possible attributes of the HTML tag. If undefined, there are no attributes. Each HtmlAttribute object contains these properties:
  • attr (string): The name of the attribute in the HTML code
  • value? (string): If value is not undefined, the attribute always has that value for this element. This is used for attributes that have fixed values
  • description? (string | null): Explanation of the attribute in English for AI model understanding