TypeDB 3.12 enhances schema documentation by introducing new schema annotations, allowing applications built with TypeDB to retrieve human-readable descriptions and custom properties directly from the database schema.

This integration simplifies the development of self-documenting interfaces, as developers can now rely on standardized queries to fetch documentation or configuration data associated with specific schema items.

New annotations

TypeDB 3.12 introduces two new annotations, @doc and @meta, which can be attached to most items in the schema: types, ownerships, playing a role, subtyping, and functions. They allow for rich descriptions of the intent behind what the type or the connection is meant to represent.

define
entity person
    @doc("an individual customer")
    @meta("icon", "silhouette.png"),
  owns name @doc("full name including title");
entity company
    @doc("a business customer")
    @meta("icon", "office-building.png"),
  owns name @doc("registered company name");
attribute name @doc("a customer's name"), value string;

To access these annotations in your queries, we provide retrieval functions like get_doc and get_meta:

match
  $x isa! $t, has name "Dr Pepper";
  let $x_icon = get_meta("icon", $t);

These annotations can also be attached to function definitions. They go at the end of the signature, before the colon introducing the body of the function:

define
fun get_random_number() -> integer
    @doc("chosen by a fair dice roll")
    @meta("details-url", "https://xkcd.com/221/"):
match
  let $rand = 4;
return first $rand;

Common use cases

These annotations are more than simple documentation. The schema can now be used to store and retrieve information beyond just types.

By embedding descriptive metadata and custom properties directly within the data model, developers can build more intelligent, self-describing applications that reduce the need for hardcoded UI logic and provide richer context for downstream integrations.

UI integration

In a well-documented schema, everything can now come with a human readable description. These can now be used to power UI elements corresponding to a schema types, ownerships, or role playing:

# get all possible types along with their tooltips:
match
  $type plays order:customer;
  let $tooltip = get_doc($type);

# get placeholder text for an input field:
match
  $type plays order:customer,
    owns name;
  let $name-field-placeholder = get_owns_doc($type, name);

In addition, @meta annotations can be used to define properties with arbitrary names. Attaching an icon to an entity is now as easy as this:

define
entity person @meta("icon", "silhouette.png");
# or:
entity company @meta("icon", "base64:aGVsbG8gdGhlcmUK...");

Additional context for AI agents

By embedding @doc and @meta annotations directly into the schema, developers can also provide LLMs with explicit, plain-text explanations of the intent and usage of specific types and relationships.

This eliminates the need for the model to rely solely on type names, sample queries, or external documentation systems to infer the intended meaning behind schema concepts, resulting in more grounded output.

Crucially, these instructions are built into the schema, which means there’s no need to adjust system prompts for agents when switching between databases: as long as they can refer to the schema, the information is already there:

define
entity person
    @doc("an individual customer")
    @meta("typical insert", "insert $p isa person, has name '<name>';")
    @meta("see also", "company,order"),
  owns name
    @doc("full name including title")
    @meta("example", "Mr. John Doe");

What’s next

Documentation and metadata is now closer to being a first-class citizen in the TypeDB data model. This, along with the existing strong type system, allows for clear expression of intent behind the design of the database, and communication of that intent to AI agents.

This new feature is a part of a larger effort to make TypeDB more AI-friendly, following our plugin for LangGraph, MCP server, agentic skills, and ongoing exploration of vector embedding storage and indexing. 

Stay tuned!