Rename 'interfaces' to 'capabilities' in TypeQL reference

academy/modules/ROOT/pages/3-reading-data/3.2-fetching-polymorphic-data.adoc

@@ -74,6 +74,11 @@ Inheritance polymorphism:: Allows us to define type hierarchies in the schema an
 Interface polymorphism:: Allows us to define interfaces that can be implemented independently in the schema and then query those interfaces declaratively.
 Parametric polymorphism:: Allows us to write declarative queries that are completely independent of the schema.
 
+[NOTE]
+====
+Throughout the Academy we use the formal term *interface* to refer to things that can be 'owned' or 'played' - e.g. role and attribute types *provide* interfaces. In the xref:{page-version}@typeql-reference::index.adoc[TypeQL reference] section, you'll see these same constructs called *capabilities*. Capabilities include all interfaces, as well as 'relates' and generally any capability that can be defined on a type. They do not, however, include annotations.
+====
+
 In this lesson, we'll be focusing on how we can use each type of polymorphism in our queries. We'll see in xref:{page-version}@academy::5-defining-schemas/index.adoc[Lesson 5] how we can define type hierarchies and interfaces in the schema.
 
 == Inheritance polymorphism

typeql-reference/modules/ROOT/pages/annotations/card.adoc

@@ -11,17 +11,17 @@ to specify cardinality ranges for roles and ownerships.
 .Range Argument Syntax
 [,typeql]
 ----
-<type label> <interface> <type label 2> @card(N..M);
-<type label> <interface> <type label 2> @card(N..);
+<type label> <capability> <type label 2> @card(N..M);
+<type label> <capability> <type label 2> @card(N..);
 ----
 
 .Single Scalar Argument Syntax
 [,typeql]
 ----
-<type label> <interface> <type label 2> @card(N);
+<type label> <capability> <type label 2> @card(N);
 ----
 
-The `@card` annotation can be defined for any `<interface>` of: `owns`, `relates`, or `plays`.
+The `@card` annotation can be defined for any `<capability>` of: `owns`, `relates`, or `plays`.
 
 It accepts either a range argument or a single scalar argument.
 Arguments must be integers.
@@ -34,7 +34,7 @@ Arguments must be integers.
 == Usage
 
 // TODO: Update for ordered/unordered when lists are implemented
-Every interface has a default `cardinality` constraint, accessible in <<_default_cardinality>>.
+Every capability has a default `cardinality` constraint, accessible in <<_default_cardinality>>.
 
 // tag::description[]
 When defined, the `@card` annotation overrides the default `cardinality` with the specified arguments.
@@ -79,7 +79,7 @@ include::{page-version}@typeql-reference::example$tql/schema_annotations.tql[tag
 === Subtyping
 
 // TODO: Put somewhere in a common place and reference it
-Similarly to inherited type constraints, interface constraints also affect subtypes from both sides.
+Similarly to inherited type constraints, capability constraints also affect subtypes from both sides.
 For example, the following query defines that:
 
 - A `page` instance must have between 1 and 3 names.
@@ -107,14 +107,14 @@ Cannot be used with the xref:{page-version}@typeql-reference::annotations/key.ad
 == References
 
 [#_default_cardinality]
-=== Default interface cardinalities
+=== Default capability cardinalities
 
-The following `cardinality` constraints are set for interfaces by default if no `@card` annotations are declared:
+The following `cardinality` constraints are set for capabilities by default if no `@card` annotations are declared:
 
-.Default interface Cardinalities
+.Default capability cardinalities
 [cols=".^1,^.^1"]
 |===
-^| interface ^| Cardinality
+^| capability ^| Cardinality
 | `owns`
 | `card(0..1)`
 

typeql-reference/modules/ROOT/pages/annotations/distinct.adoc

@@ -23,12 +23,12 @@ The `@distinct` annotation does not accept any arguments.
 
 == Usage
 
-The `@distinct` annotation enforces the `distinct` constraint for an ordered type interface.
+The `@distinct` annotation enforces the `distinct` constraint for an ordered type capability.
 This constraint ensures that lists contain only distinct values.
 // TODO: Add a reference to lists and their behavior
 
 [NOTE]
 ====
-Ordered interfaces, lists, and related annotations like `@distinct` are not yet available in TypeDB.
+Ordered capabilities, lists, and related annotations like `@distinct` are not yet available in TypeDB.
 Coming soon!
 ====

typeql-reference/modules/ROOT/pages/data-model.adoc

@@ -32,7 +32,7 @@ Instances of entity types, simply called entities, can be created _indepdently_,
 2. *Relation types*, specified using the keyword `relation`, and are required to have at least one *associated role type* specified with the keyword `relates`.
 +
 --
-Instances of relation types may reference (or "link") zero or more data instances for each associated role type, called their *players* of that role (these data instance must have types with corresponding *player interface*).
+Instances of relation types may reference (or "link") zero or more data instances for each associated role type, called their *players* of that role (these data instance must have types with corresponding *player capability*).
 
 For example, a friendship relations may link two friends (implemented by, say, two user entities).
 
@@ -41,7 +41,7 @@ Relations without role players will be removed (no "`dangling relations`").
 3. *Attribute types*, specified using the keyword `attribute`, and required to have an *associated value type* (either structured or primitive) specified with the keyword `value`.
 +
 --
-Instances of attribute types carry an *associated value* of the associated value type. They may also reference other data instances, called their *owners* (these data instances must have direct types with the corresponding *owner interface*). Two attributes are considered equal if they have the same associate value and have the same (origin) type.
+Instances of attribute types carry an *associated value* of the associated value type. They may also reference other data instances, called their *owners* (these data instances must have direct types with the corresponding *owner capability*). Two attributes are considered equal if they have the same associate value and have the same (origin) type.
 
 Attributes without owners will be removed (no "`dangling attributes`", unless the attribute type is marked as independent).
 --
@@ -65,15 +65,15 @@ Two instances of a value type are equal exactly when their literal values are eq
 Coming soon.
 ====
 
-=== Type interfaces and "`objects vs attributes`"
+=== Type capabilities and "`objects vs attributes`"
 
-Entity types can have interfaces, i.e. play roles or own attribute types. This allows us to create connections of entities with other data.
+Entity types can have capabilities, i.e. play roles or own attribute types. This allows us to create connections of entities with other data.
 
-Relation types can also have interfaces, i.e. play roles or own attribute types. This, for example, allows the creation of nested relations (i.e., relations playing roles in other relations).
+Relation types can also have capabilities, i.e. play roles or own attribute types. This, for example, allows the creation of nested relations (i.e., relations playing roles in other relations).
 
-Since entity and relation types together make up "`first-class`" types in TypeDB's type system (when it comes to type interfaces) they are, together, also referred to as *object types*, whose instances are data *objects*.
+Since entity and relation types together make up "`first-class`" types in TypeDB's type system (when it comes to type capabilities) they are, together, also referred to as *object types*, whose instances are data *objects*.
 
-Attributes cannot have interfaces; they are merely typed associations of values to objects.
+Attributes cannot have capabilities; they are merely typed associations of values to objects.
 
 === Subtyping
 
@@ -88,7 +88,7 @@ Data instances (i.e., entities, relation, are attributes) are stored using datab
 
 == Definitions
 
-User-defined types, their interfaces, and their subtyping structure, are created and modified through xref:{page-version}@typeql-reference::index.adoc#statements[definition statements] in xref:{page-version}@typeql-reference::index.adoc#queries[schema queries].
+User-defined types, their capabilities, and their subtyping structure, are created and modified through xref:{page-version}@typeql-reference::index.adoc#statements[definition statements] in xref:{page-version}@typeql-reference::index.adoc#queries[schema queries].
 
 == Data pipelines
 

typeql-reference/modules/ROOT/pages/index.adoc

@@ -109,14 +109,14 @@ The former query introduces types, while the latter will query for types. The ge
 Definitions in schema queries concern:
 
 * *type* definitions, introducing new types via the appropriate keyword (`entity`, `relation` + `relates`, `attribute` + `value`). Types are referred to by a unique type *labels*; multiple aliases of the latter can be introduced (coming soon).
-* *interface* definitions, introducing player or owner interfaces (via `plays` and `owns` keywords). Player interfaces allow type instances to be referred to as players in roles of relations. Owner interfaces allow type instances to be referred to as
-* *subtyping* definitions, declare types to be subtypes of other types (via the keyword `sub`). interfaces of supertypes are inherited by subtypes.
+* *capability* definitions, introducing player or owner capabilities (via `plays` and `owns` keywords). Player capabilities allow type instances to be referred to as players in roles of relations. Owner capabilities allow type instances to be referred to as
+* *subtyping* definitions, declare types to be subtypes of other types (via the keyword `sub`). Capabilities of supertypes are inherited by subtypes.
 
 === Pattern statements
 
 In contrast, in patterns we support a wide variety of syntax, including for:
 
-* *Retrieving types* based on label, interfaces, and inheritance.
+* *Retrieving types* based on label, capabilities, and inheritance.
 * *Retrieving data* in types, e.g. based on references between data instance such as attribute ownerships and relation linkages (via keywords such as `has`, `links`, and anonymous versions thereof)
 * Function calls (`let $a, $b in <FUN-CALL>`)
 * Computation with values (`let $x = <EXPR>`)

typeql-reference/modules/ROOT/pages/keywords.adoc

@@ -376,7 +376,7 @@ Denotes the return signature of a function. See xref:{page-version}@typeql-refer
 Used to remove ownership of attributes and players of roles in xref:{page-version}@typeql-reference::pipelines/delete.adoc[Delete stages] of data pipelines.
 
 `from`::
-Used to remove interfaces, role specialisation, and annotations in xref:{page-version}@typeql-reference::schema/undefine.adoc[Undefine queries].
+Used to remove capabilities, role specialisation, and annotations in xref:{page-version}@typeql-reference::schema/undefine.adoc[Undefine queries].
 
 `in`::
 Used to access stream or list elements. See xref:{page-version}@typeql-reference::statements/let-in.adoc[] for more information.

typeql-reference/modules/ROOT/pages/schema/define.adoc

@@ -4,7 +4,7 @@
 
 Define queries are used
 // tag::overview[]
-to add new types, constraints, or functions to the schema.
+to add new types, capabilities, annotations, or functions to the schema.
 // end::overview[]
 
 == Syntax
@@ -22,7 +22,7 @@ Schema statements in a define query cannot use variables or values, except for f
 
 == Behavior
 
-A define query adds schema statements to an existing schema. These statements can add new types and functions, or they can add new interfaces and annotations to existing types. Define queries cannot change schema statements already existing in a schema.
+A define query adds schema statements to an existing schema. These statements can add new types and functions, or they can add new capabilities and annotations to existing types. Define queries cannot change schema statements already existing in a schema.
 
 Define queries are idempotent, meaning they can be applied multiple times without changing the result of the initial application.
 
@@ -44,7 +44,7 @@ An error is returned (on execution or on commit), and no changes are preserved,
 * xref:{page-version}@typeql-reference::statements/sub.adoc[`sub` statements] define new subtyping between two types. Those types should be of the same kind: entity, relation, or attribute. If another `sub` is already defined for the subject type, an error is returned.
 * xref:{page-version}@typeql-reference::annotations/index.adoc[@annotations] define new annotations. If another annotation of the same type but with different arguments is already defined, an error is returned. Can be applied to:
 - Type labels for entities, relations, attributes.
-- interfaces: `relates`, `plays`, `owns`.
+- capabilities: `relates`, `plays`, `owns`.
 - Attribute value types: `value`.
 * xref:{page-version}@typeql-reference::statements/fun.adoc[`fun` statements] define new functions.
 
@@ -73,7 +73,7 @@ define relation parentship;
 define attribute email;
 ----
 
-=== Defining interfaces
+=== Defining capabilities
 
 .Defining relation type's relates
 [,typeql]

typeql-reference/modules/ROOT/pages/schema/redefine.adoc

@@ -3,7 +3,7 @@
 
 Redefine queries are used
 // tag::overview[]
-to modify existing types, type interfaces, or functions in the schema.
+to modify existing types, capabilities, annotations, or functions in the schema.
 // end::overview[]
 
 == Syntax
@@ -18,7 +18,7 @@ redefine
 
 == Behavior
 
-Redefine queries can be used to modify types and type interfaces or to override functions.
+Redefine queries can be used to modify types and type capabilities or to override functions.
 
 For clarity and precision, only one redefinition is allowed per query.
 
@@ -36,7 +36,7 @@ An error is returned (on execution or on commit), and no changes are preserved,
 * xref:{page-version}@typeql-reference::statements/value.adoc[`value` statements] redefine value types of attribute types.
 * xref:{page-version}@typeql-reference::statements/sub.adoc[`sub` statements] redefine supertypes of types.
 * xref:{page-version}@typeql-reference::annotations/index.adoc[@annotations] redefine annotations with arguments, replacing their values.
-* xref:{page-version}@typeql-reference::statements/fun.adoc[`fun` statements] redefine functions, replacing their interfaces and bodies.
+* xref:{page-version}@typeql-reference::statements/fun.adoc[`fun` statements] redefine functions, replacing their capabilities and bodies.
 
 == Examples
 
@@ -54,7 +54,7 @@ relation fathership sub parentship, relates father as child;
 ----
 ====
 
-=== Redefining types' interfaces and annotations
+=== Redefining types' capabilities and annotations
 
 .Redefining type's sub
 [,typeql]
@@ -77,7 +77,7 @@ redefine karma value integer;
 redefine email value string @regex("^.*@typedb\.com$");
 ----
 
-.Redefining type interface's annotation with arguments
+.Redefining type capability's annotation with arguments
 [,typeql]
 ----
 #!test[schema]

typeql-reference/modules/ROOT/pages/schema/undefine.adoc

@@ -4,7 +4,7 @@
 
 Undefine queries are used
 // tag::overview[]
-to remove existing types, constraints, or functions from the schema.
+to remove existing types, capabilities, annotations, or functions from the schema.
 // end::overview[]
 
 == Syntax
@@ -25,7 +25,7 @@ Undefinition statements are similar to definition statements, but they have a di
 <label>;
 ----
 
-.interface undefinition statement
+.capability undefinition statement
 [,typeql]
 ----
 <interface_definition> from <type_label>;
@@ -48,9 +48,8 @@ Schema statements in an undefine query cannot use variables or values.
 
 == Behavior
 
-An undefine query removes the parts of the schema specified in its undefine clause, including types, interfaces, annotations, and functions.
-Undefining a type also undefines all its interfaces and annotations.
-Undefining a interface also undefines all its interfaces and annotations.
+An undefine query removes the parts of the schema specified in its undefine clause, including types, capabilities, annotations, and functions.
+Undefining a type also undefines all its capabilities and annotations.
 
 An error is returned (on execution or on commit), and no changes are preserved, if:
 
@@ -104,7 +103,7 @@ undefine user;
 undefine fathership; email;
 ----
 
-=== Undefining interfaces
+=== Undefining capabilities
 
 .Undefining relation type's relates
 [,typeql]

typeql-reference/modules/ROOT/pages/statements/index.adoc

@@ -107,7 +107,7 @@ Coming soon
 ****
 --
 
-=== interface definitions
+=== Capability definitions
 
 [cols-2]
 --