@doc annotation

The @doc annotation is used to add a description to a schema concept.

Syntax

The @doc annotation can be defined for:

  • any type;

  • an owns, plays, relates, or a sub declaration;

  • a function;

  • a struct and struct fields.

Type annotation syntax
<type label> @doc("<description>");
Ownership annotation syntax
<type label> owns <attribute type label> @doc("<description>");
Function annotation syntax
fun <function-name>( <optional-arguments> ) -> <return-types>
    @doc("<description>"):
<function-body>

Structs are a planned feature and not yet available in TypeDB. Coming soon!
Struct annotation syntax
struct <struct-name> @doc("<description>"):
  <field-name> value <field-type> @doc("<field-description>");

Usage

The @doc annotation is used to add a description to a schema concept.

The annotation enables users to attach human-readable descriptions to types, capabilities, functions, and structs in the schema.

#!test[schema]
define
  entity student @doc("Someone currently or previously enrolled in the institution."),
    plays enrolment:student,
    plays enrolment:teacher @doc("Students may assist faculty members in teaching a course."),
    owns id @doc("This is an internal ID to be used on student documentation.");
  relation enrolment @doc("Relates a course with enrolled students and teaching staff."),
    relates course @doc("The specific course being taught: owns code and academic year."),
    relates student @card(0..),
    relates teacher @card(1..) @doc("All teaching staff attached to this enrolment."),
    owns id @doc("This is not the course code!");
  attribute id @doc("Internal IDs, created by the system."), value string;

These descriptions can then be retrieved using the documentation retrieval built-in functions.

#!test[write, count=1]
#{{
insert $s isa student, has id "Billy"; $_ isa enrolment, links(teacher: $s), has id "CS101-2026";
#}}
#!test[read, count=1]
match
  $rel isa! $relation-type, has id $rel-id, links ($role: $player);
  $player isa! $player-type, has id $player-id;
fetch {
  "relation": {
    "id": $rel-id,
    "type": label($relation-type),
    "doc": get_doc($relation-type),
  },
  "player": {
    "id": $player-id,
    "type": label($player-type),
    "doc": get_doc($player-type),
  },
  "role": {
    "type": label($role),
    "relates_doc": get_relates_doc($relation-type, $role),
    "plays_doc": get_plays_doc($player-type, $role),
  }
};
Example output
{
  "player": {
    "doc": "Someone currently or previously enrolled in the institution.",
    "id": "billybob",
    "type": "student"
  },
  "relation": {
    "doc": "Relates a course with enrolled students and teaching staff.",
    "id": "CS101-2026",
    "type": "enrolment"
  },
  "role": {
    "plays_doc": "Students may assist faculty members in teaching a course.",
    "relates_doc": "All teaching staff attached to this enrolment.",
    "type": "enrolment:teacher"
  }
}

Subtyping

The @doc annotation is never inherited. Documentation is only available on the exact items it was originally defined for.

Notes

my-relation relates my-role declares both the role my-relation:my-role and the relates capability. Because of that, any @doc annotation declared on a relates is also automatically available on the role introduced in that relates.

Defaults

For items without defined @doc annotation, the documentation is an empty string.