Annotations

Introduction

Annotations are useful language constructs that begin with an @. They can be used to enforce constraints on definitions.

Syntax

Annotations are applied to the latest statement before their declaration:

A type’s annotation

<type label> @annotation;

A type value’s annotation

<type label> value <value type> @annotation;

A type plays' annotation

<type label> plays <role type label> @annotation;

Arguments

Some annotations accept arguments of different types:

Annotations with a single scalar argument

@annotation(5)
@annotation("TypeDB!")

Annotations with multiple arguments

@annotation(0, 1, 2, 3, 4, 5)
@annotation("Welcome", "to", "TypeDB", "!")

Annotations with a range argument

@annotation(0..10)
@annotation("a".."z")
@annotation(1..)

Combining with other statements

Annotation definition is a regular statement and can be followed by other statements after a comma:

<type label> @annotation, value <value type> @annotation, plays <role type label> @annotation;

However, it is possible to chain multiple annotations for a single statement:

<type label> @annotation1 @annotation2 @annotation3;

Which is an equivalent of:

<type label> @annotation1;
<type label> @annotation2;
<type label> @annotation3;

Behavior

It is possible to define an unlimited number of annotations of different kinds for a type. However, only one definition of a specific kind of annotation can exist for a type at a time (e.g., @a(X) and @a(Y) cannot co-exist in the schema).

Defining @a while @b is already defined results in both @a and @b being defined (with a couple of exceptions like @key and @unique).
Defining @a when @a is already defined makes no changes.
Defining @a(x) when @a(y) is already defined replaces @a(y) with @a(x).