OneOf Input Objects

Some inputs will behave differently depending on what input we choose. Let’s look at the case for a field named product, we can fetch a Product by either its id or its name. Currently we’d make a tradeoff for this by introducing two arguments that are both nullable, now if both are passed as null (or both non-null) we’d have to handle that in code - the type system wouldn’t indicate that exactly one was required. To fix this, the @oneOf directive was introduced so we can create this “exactly one option” constraint without sacrificing the strictly typed nature of our GraphQL Schema.

const schema = buildSchema(`
  type Product {
    id: ID!
    name: String!
  }
 
  input ProductLocation {
    aisleNumber: Int!
    shelfNumber: Int!
    positionOnShelf: Int!
  }
 
  input ProductSpecifier @oneOf {
    id: ID
    name: String
    location: ProductLocation
  }
 
  type Query {
    product(by: ProductSpecifier!): Product
  }
`);

const Product = new GraphQLObjectType({
  name: 'Product',
  fields: {
    id: {
      type: new GraphQLNonNull(GraphQLID),
    },
    name: {
      type: new GraphQLNonNull(GraphQLString),
    },
  },
});
 
const ProductLocation = new GraphQLInputObjectType({
  name: 'ProductLocation',
  fields: {
    aisleNumber: { type: new GraphQLNonNull(GraphQLInt) },
    shelfNumber: { type: new GraphQLNonNull(GraphQLInt) },
    positionOnShelf: { type: new GraphQLNonNull(GraphQLInt) },
  },
});
 
const ProductSpecifier = new GraphQLInputObjectType({
  name: 'ProductSpecifier',
  isOneOf: true,
  fields: {
    id: { type: GraphQLID },
    name: { type: GraphQLString },
    location: { type: ProductLocation },
  },
});
 
const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      product: {
        type: Product,
        args: { by: { type: new GraphQLNonNull(ProductSpecifier) } },
      },
    },
  }),
});

It doesn’t matter whether you have 2 or more inputs here, all that matters is that your user will have to specify one, and only one, for this input to be valid. The values are not limited to scalars, lists and other input object types are also allowed.

OneOf fields themselves must be nullable and must not define defaults. Nested input object types can still have their own required fields, as shown by ProductLocation.

In GraphQL.js v17, OneOf coercion is stricter around defaults, unknown fields, undefined, and values that are present before coercion but invalid after coercion. Schemas that accidentally rely on ambiguous OneOf inputs should fail earlier and with clearer errors.

Recursive OneOf input objects

Recursive input objects are valid only when a client can provide a finite value. For OneOf input objects, that means at least one branch must eventually escape the cycle through a scalar, enum, list, nullable non-OneOf field, or another input object that can be provided a finite value.

This schema is invalid because the only possible value for A points back to A:

input A @oneOf {
  self: A
}

Add a real escape branch or move the recursive shape into a nullable field on a regular input object:

input A @oneOf {
  id: ID
  nested: NestedA
}
 
input NestedA {
  value: A
}