A GraphQL union represents a set of object types that share no required common fields. Unlike interfaces, union members do not need to declare the same fields. Clients use inline fragments to select fields from each possible type.

GraphQL schema

type TextContent {
  text: String!
}

type ImageContent {
  imageUrl: String!
  height: Int!
}

union PostContent = TextContent | ImageContent

Client query

{
  content {
    ... on TextContent {
      text
    }
    ... on ImageContent {
      imageUrl
    }
  }
}

Defining a Union Type

Use a marker interface (an interface with no members) or an abstract class to group the types that belong to the union.

// Types/IPostContent.cs
[UnionType("PostContent")]
public interface IPostContent
{
}

// Types/TextContent.cs
public class TextContent : IPostContent
{
    public string Text { get; set; }
}

// Types/ImageContent.cs
public class ImageContent : IPostContent
{
    public string ImageUrl { get; set; }
    public int Height { get; set; }
}

// Types/ContentQueries.cs
[QueryType]
public static partial class ContentQueries
{
    public static IPostContent GetContent()
    {
        // ...
    }
}

// Program.cs
builder
    .AddGraphQL()
    .AddType<TextContent>()
    .AddType<ImageContent>();

Each type that implements the marker interface must be registered so Hot Chocolate includes it in the union.

Union vs Interface

Choose a union when the grouped types have no meaningful shared fields. Choose an interface when you want to guarantee a common set of fields across all implementing types.

Next Steps

• Need shared fields across types? See Interfaces.
• Need to define output types? See Object Types.
• Need input polymorphism? See OneOf Input Objects.