---
title: "Schema awareness"
description: "Provide schema awareness to AI models so they understand nodes, marks, and attributes."
canonical_url: "https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/api-reference/schema-awareness"
---

# Schema awareness

Provide schema awareness to AI models so they understand nodes, marks, and attributes.

A Tiptap [schema](https://tiptap.dev/docs/editor/core-concepts/schema.md) 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](https://tiptap.dev/docs/content-ai/capabilities/ai-toolkit/advanced-guides/schema-awareness.md).

## 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](https://tiptap.dev/docs/editor/extensions/custom-extensions/create-new/extension.md#name) 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

```ts
// 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](https://tiptap.dev/docs/editor/extensions/custom-extensions/create-new/node.md).

### 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