docs(graphql): Update id directive for interfaces (#209) (#382)

Fixes DOC-275

Co-authored-by: Damián Parrino <[email protected]>
Co-authored-by: Abhimanyu Singh Gaur <[email protected]>
Co-authored-by: rderbier <[email protected]>

Author: 4 people

content/graphql/schema/directives/ids.md

@@ -13,7 +13,7 @@ Dgraph provides two types of built-in identifiers: the `ID` scalar type and the
 * The `@id` directive is used for external identifiers, such as email addresses.
 
 
-### The `@id` directive
+## The `@id` directive
 
 For some types, you'll need a unique identifier set from outside Dgraph.  A common example is a username.
 
@@ -63,8 +63,33 @@ query {
 
 This will yield a positive response if both the `name` **and** `isbn` match any data in the database.
 
+### `@id` and interfaces
 
-### Combining `ID` and `@id`
+By default, if used in an interface, the `@id` directive will ensure field uniqueness for each implementing type separately.
+In this case, the `@id` field in the interface won't be unique for the interface but for each of its implementing types.
+This allows two different types implementing the same interface to have the same value for the inherited `@id` field.
+
+There are scenarios where this behavior might not be desired, and you may want to constrain the `@id` field to be unique across all the implementing types. In that case, you can set the `interface` argument of the `@id` directive to `true`, and Dgraph will ensure that the field has unique values across all the implementing types of an interface.
+
+For example:
+
+```graphql
+interface Item {
+  refID: Int! @id(interface: true) # if there is a Book with refID = 1, then there can't be a chair with that refID.
+  itemID: Int! @id # If there is a Book with itemID = 1, there can still be a Chair with the same itemID.
+}
+
+type Book implements Item { ... }
+type Chair implements Item { ... }
+```
+
+In the above example, `itemID` won't be present as an argument to the `getItem` query as it might return more than one `Item`.
+
+{{% notice "note" %}}
+`get` queries generated for an interface will have only the `@id(interface: true)` fields as arguments.
+{{% /notice %}}
+
+## Combining `ID` and `@id`
 
 You can use both the `ID` type and the `@id` directive on another field definition to have both a unique identifier and a generated identifier.
 
@@ -84,7 +109,7 @@ With this schema, Dgraph requires a unique `username` when creating a new user.
 If in a type there are multiple `@id` fields, then in a `get` query these arguments will be optional. If in a type there's only one field defined with either `@id` or `ID`, then that will be a required field in the `get` query's arguments.
 {{% /notice %}}
 
-<!-- 
+<!--
 ### More to come
 
 We are currently considering allowing types other than `String` with `@id`, see [here](https://discuss.dgraph.io/t/id-with-type-int/10402)