# `@doc` annotation

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

## [](#_syntax)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

```typeql
<type label> @doc("<description>");
```

Ownership annotation syntax

```typeql
<type label> owns <attribute type label> @doc("<description>");
```

Function annotation syntax

```typeql
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

```typeql
struct <struct-name> @doc("<description>"):
  <field-name> value <field-type> @doc("<field-description>");
```

## [](#_usage)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.

```typeql
#!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](../../expressions/builtin-functions/index.md#_documentation_fns).

```typeql
#!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

```json
{
  "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)Subtyping

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

### [](#_notes)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)Defaults

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

[@distinct](../distinct/index.md) [@meta](../meta/index.md)

[Edit on GitHub](https://github.com/typedb/typedb-docs/edit/3.x-development/typeql-reference/modules/ROOT/pages/annotations/doc.adoc) Edit this page on GitHub.