Tiptap Docs

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.

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.

For a step-by-step guide on integrating schema awareness, see the Schema awareness guide.

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
PreviouslyEdit the document