Skip to main content
Version: 5.x.x

Unions

GraphQL Kotlin allows for two ways of defining unions in the schema

Marker Interfaces#

Marker interfaces (i.e. interfaces without any common fields or methods) are exposed as GraphQL union types. All the types that implement the marker interface, and are available on the classpath, will be automatically exposed as objects in the schema.

note

The GraphQL spec does not allow unions to be used as input. This means that while it is valid Kotlin code to have a marker inteface as an argument, upon schema generation, an exception will be thrown.

interface BodyPart
class LeftHand(val field: String): BodyPart
class RightHand(val property: Int): BodyPart
class PolymorphicQuery {    fun whichHand(whichHand: String): BodyPart = when (whichHand) {        "right" -> RightHand(12)        else -> LeftHand("hello world")    }}

The above will generate following GraphQL schema

union BodyPart = LeftHand | RightHand
type LeftHand {  field: String!}
type RightHand {  property: Int!}
type Query {  whichHand(whichHand: String!): BodyPart!}

@GraphQLUnion#

The downside to marker interface unions is that you can not edit classes included in dependencies to implement new schema unions. For example in an SDL-First world you could have this Kotlin class defined in some library.

class SharedModel(val foo: String)

And then write your schema as the following

# From librarytype SharedModel {  foo: String!}
# Defined in our schematype ServiceModel {  bar: String!}
# Defined in our schemaunion CustomUnion = SharedModel | ServiceModel
type Query {    getModel: CustomUnion}

But this is not currently possible in the full code-generation approach. Instead, you will need to use the @GraphQLUnion annotation on your functions or properties.

Example Usage#

// Defined in some other libraryclass SharedModel(val foo: String)
// Our codeclass ServiceModel(val bar: String)
class Query {    @GraphQLUnion(        name = "CustomUnion",        possibleTypes = [SharedModel::class, ServiceModel::class],        description = "Return one or the other model"    )    fun getModel(): Any = ServiceModel("abc")}

The annotation requires the name of the new union to create and the possibleTypes that this union can return. However since we can not enforce the type checks anymore, you must use Any as the return type.

Limitations#

Since this union is defined with an added annotation it is not currently possible to add directives directly to this union definition. You will have to modify the type with schema generator hooks