Enforcing entity ownership in Apollo Federation

In Federation 2, the notion of "extending" an entity type is strictly conceptual. All definitions of a type in different subgraphs are merged according to the "shareability" of fields. In the following example, neither subgraph really owns or extends the Product entity. Instead, they both contribute fields to it.

type Product @key(fields: "id") {
  id: ID!
  name: String
}

type Product @key(fields: "id") {
  id: ID!
  reviews: [Review]
}

Federation 1 required that one of these definitions used the extend keyword or @extends directive. Federation 2 drops this requirement to improve the flexibility of composition and reduce the possibility of hard composition errors.

However, in some situations you still might want to designate an "owner" of an entity and make "entity extension" a first-class concept in your supergraph.

One example is the ability assert which subgraph is responsible for documenting an entity. If two subgraphs add different descriptions to a type, composition selects one of those descriptions and emits a hint informing you of the inconsistency:

1
HINT: [INCONSISTENT_DESCRIPTION]: Element "Product" has inconsistent
2
descriptions across subgraphs. The supergraph will use description
3
(from subgraph "one"):
4
  """
5
  The Product type lorem ipsum dolar sit amet.
6
  """
7
In subgraph "two", the description is:
8
  """
9
  This is my description of the Product type.
10
  """

A mechanism for deciding the "owner" of the type allows tools such as linters to catch these inconsistencies early in the development process.

Creating an @owner directive

You can add an @owner directive to your supergraph using the @composeDirective functionality introduced in Federation 2.2.

1
extend schema
2
  @link(
3
    url: "https://specs.apollo.dev/federation/v2.3"
4
    import: ["@key", "@composeDirective"]
5
  )
6
  @link(url: "https://graphql.mycompany.dev/owner/v1.0")
7
  @composeDirective(name: "@owner")
8

9
directive @owner(team: String!) on OBJECT
10

11
type Product @key(fields: "id") @owner(team: "subgraph-a") {
12
  id: ID!
13
  name: String
14
}

The @owner directive now appears in the supergraph. Because we did not define the directive as repeatable, subgraphs cannot define it with different arguments.

1
schema
2
  @link(url: "https://specs.apollo.dev/link/v1.0")
3
  @link(url: "https://specs.apollo.dev/join/v0.3", for: EXECUTION)
4
  @link(url: "https://graphql.mycompany.dev/owner/v1.0", import: ["@owner"]) {
5
  query: Query
6
}
7

8
directive @join__enumValue(graph: join__Graph!) repeatable on ENUM_VALUE
9

10
directive @join__field(
11
  graph: join__Graph
12
  requires: join__FieldSet
13
  provides: join__FieldSet
14
  type: String
15
  external: Boolean
16
  override: String
17
  usedOverridden: Boolean
18
) repeatable on FIELD_DEFINITION | INPUT_FIELD_DEFINITION
19

20
directive @join__graph(name: String!, url: String!) on ENUM_VALUE
21

22
directive @join__implements(
23
  graph: join__Graph!
24
  interface: String!
25
) repeatable on OBJECT | INTERFACE
26

27
directive @join__type(
28
  graph: join__Graph!
29
  key: join__FieldSet
30
  extension: Boolean! = false
31
  resolvable: Boolean! = true
32
  isInterfaceObject: Boolean! = false
33
) repeatable on OBJECT | INTERFACE | UNION | ENUM | INPUT_OBJECT | SCALAR
34

35
directive @join__unionMember(
36
  graph: join__Graph!
37
  member: String!
38
) repeatable on UNION
39

40
directive @link(
41
  url: String
42
  as: String
43
  for: link__Purpose
44
  import: [link__Import]
45
) repeatable on SCHEMA
46

47
directive @owner(team: String!) on OBJECT
48

49
scalar join__FieldSet
50

51
enum join__Graph {
52
  ONE @join__graph(name: "one", url: "http://localhost:4001")
53
}
54

55
scalar link__Import
56

57
enum link__Purpose {
58
  """
59
  `SECURITY` features provide metadata necessary to securely resolve fields.
60
  """
61
  SECURITY
62

63
  """
64
  `EXECUTION` features provide metadata necessary for operation execution.
65
  """
66
  EXECUTION
67
}
68

69
type Product @join__type(graph: ONE, key: "id") @owner(team: "subgraph-a") {
70
  id: ID!
71
  name: String
72
}
73

74
type Query @join__type(graph: ONE) {
75
  products: [Product]
76
}

Writing a lint rule using the @owner directive

Here's an example of a @graphql-eslint rule for subgraph schemas that uses the @owner directive to determine if a description is required:

1
const {getDirective} = require('@graphql-tools/utils');
2
const {buildSchema} = require('graphql');
3

4
module.exports = {
5
  rules: {
6
    /** @type {import("@graphql-eslint/eslint-plugin").GraphQLESLintRule} */
7
    'subgraph-owned-type-has-description': {
8
      create(context) {
9
        const schema = buildSchema(context.getSourceCode().text, {
10
          assumeValidSDL: true // subgraph schemas may not be valid on their own
11
        });
12

13
        return {
14
          /**
15
           * For each object type defintion, look for an `@owner` directive.
16
           * If it exist, require a description.
17
           * If it doesn't, disallow a description.
18
           */
19
          ObjectTypeDefinition(node) {
20
            const type = schema.getType(node.name.value);
21
            const owner = getDirective(schema, type, 'owner');
22

23
            if (owner && !node.description) {
24
              context.report({
25
                node,
26
                message: 'Description is required on owned types'
27
              });
28
            }
29

30
            if (!owner && node.description) {
31
              context.report({
32
                node,
33
                message: 'Description not allowed on unowned types'
34
              });
35
            }
36
          }
37
        };
38
      }
39
    }
40
  }
41
};

Using @owner to determine required approvers

Another use case for the @owner directive is to determine required reviewers when a schema change affects a type owned by another team.

The exact process depends on your source control and continuous integration systems. The following example steps assume you're using GitHub for both.

1. Add a pull_request workflow:

   YAML

   .github/workflows/add-reviewers.yaml

   1
   name: Add required reviewers for owned GraphQL types
   2
   on: [pull_request]

   Copy

2. Determine the affected types in the schema change:

   JavaScript

   1
   import {diff} from '@graphql-inspector/core';
   2
   import {buildSchema} from 'graphql';
   3
   
   4
   const differences = diff(
   5
     buildSchema(schemaFromBaseRef, {assumeValidSDL: false}),
   6
     buildSchema(schemaFromCurrentRef, {assumeValidSDL: false})
   7
   );
   8
   
   9
   /* Derive a list of affected types from the result:
   10
   [
   11
     {
   12
       "criticality": {
   13
         "level": "NON_BREAKING"
   14
       },
   15
       "type": "FIELD_ADDED",
   16
       "message": "Field 'newField' was added to object type 'Product'",
   17
       "path": "Product.newField"
   18
     }
   19
   ]
   20
   */

   Copy

3. Obtain the supergraph schema.

   You can use rover supergraph fetch or retreive it using the Apollo Platform API.

4. Extract the owners for the affected types:

   JavaScript

   1
   import {getDirective} from '@graphql-tools/utils';
   2
   
   3
   const supergraphSchema = buildSchema(supergraphSdl);
   4
   const affectedTeams = [];
   5
   
   6
   for (const typeName of affectedTypes) {
   7
     const type = supergraphSchema.getType(typeName);
   8
   
   9
     const owner = getDirective(schema, type, 'owner')?.[0];
   10
   
   11
     if (owner) {
   12
       affectedTeams.push(owner.team);
   13
     }
   14
   }

   Copy

5. Add the team as reviewers on the pull request:

   JavaScript

   1
   import {Octokit} from '@octokit/action';
   2
   
   3
   const octokit = new Octokit();
   4
   
   5
   const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/');
   6
   
   7
   await octokit.pulls.requestReviewers({
   8
     owner,
   9
     repo,
   10
     pull_number: pullNumber, // ${{ github.event.number }}
   11
     team_reviewers: affectedTeams
   12
   });

   Copy