Adds overview of type extension support

[michaeldgraham]

Type Extensions

The GraphQL specification describes using the extend keyword to represent a type which has been extended from another type. The following subsections describe the available behaviors, such as extending an object type to represent additional fields. When using schema augmentation, type extensions are applied when building the fields and types used for the generated Query and Mutation API.

Schema

The schema type can be extended with operation types.

schema {
  query: Query
}
extend schema {
  mutation: Mutation
}

Scalars

Scalar types can be extended with additional directives.

scalar myScalar
extend scalar myScalar @myDirective

Objects & Interfaces

Object and interface types can be extended with additional fields and directives. Objects can also be extended to implement interfaces.

Fields

type Movie {
  movieId: ID!
  title: String
  year: Int
  imdbRating: Float
}
extend type Movie {
    genres: [Genre] @relation(name: "IN_GENRE", direction: "OUT")
    similar: [Movie] @cypher(
        statement: """MATCH (this)<-[:RATED]-(:User)-[:RATED]->(s:Movie) 
                      WITH s, COUNT(*) AS score 
                      RETURN s ORDER BY score DESC LIMIT {first}""")
}

Directives

type Movie {
  movieId: ID!
}
extend type Movie @additionalLabels(
  labels: ["newMovieLabel"]
)

Operation types

type Query {
  Movie: [Movie]
}
extend type Query {
  customMovie: Movie
}

Implementing interfaces

interface Person {
  userId: ID!
  name: String
}
type Actor {
  userId: ID!
  name: String
}
extend type Actor implements Person

Unions

A union type can be extended with additional member types or directives.

union MovieSearch = Movie | Genre | Book
extend union MovieSearch = Actor | OldCamera

Enums

Enum types can be extended with additional values or directives.

enum BookGenre {
  Mystery
  Science
}
extend enum BookGenre {
  Math
}

Input Objects

Input object types can be extended with additional input fields or directives.

input CustomMutationInput {
  title: String
}
extend input CustomMutationInput {
  year: Int
  imdbRating: Float
}