Schema awareness

Before using the Server AI Toolkit API, you need to get schema awareness data from your Tiptap editor.

The getSchemaAwarenessData function retrieves schema information from your Tiptap editor and converts it to a format suitable for the Server AI Toolkit API. This data describes the document structure and helps the AI understand what content is valid.

`getSchemaAwarenessData`

Returns schema awareness data that describes the document structure for the Server AI Toolkit API.

This function collects schema information from extensions and converts it to a format suitable for AI model consumption. The returned data is used by the Server AI Toolkit API to understand what content is valid in your document.

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.

See an example of how to use it in the schema awareness guide.

Parameters

`editor` (`Editor`)

The Tiptap editor instance from which to extract schema awareness data.

`options?` (`GetSchemaAwarenessDataOptions`)

Configuration options for schema awareness:

customNodes? (JsonItem[]): Custom schema awareness items to include in addition to the default ones. This allows extending the schema information with custom node types or modifications to existing node definitions for AI model consumption. Default: [].

Every JsonItem object contains these properties:

extensionName (string): The name of the extension that provides this element
name (string): The human-readable name of the element in English
description? (string): Explanation of what the element is and how it is displayed
isMark? (boolean): Whether this item is a mark (as opposed to a node)
attributes? (Record<string, unknown>): Possible attributes of the element, defined as Zod schemas that will be converted to JSON schemas

Returns

SchemaAwarenessData: Schema awareness data that describes the document structure. This data is passed to the Server AI Toolkit API endpoints.

Example

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],
})

// Get schema awareness data
const schemaAwarenessData = getSchemaAwarenessData(editor)

// Use with Server AI Toolkit API
const response = await fetch('https://api.tiptap.dev/v3/ai/toolkit/tools', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${API_TOKEN}`,
  },
  body: JSON.stringify({
    schemaAwarenessData,
  }),
})

PreviouslyAPI reference

Next upREST API

getSchemaAwarenessData