OneOf inhabitability by jbellenger · Pull Request #1211 · graphql/graphql-spec

jbellenger · 2026-02-17T00:16:11Z

OneOf types can form graphs for which finite values cannot be created.

The simplest example of this is a self-recursing OneOf type:

input A @oneOf { a:A }

While this is the simplest form, OneOfs can also be combined with non-OneOf input object types to create other uninhabited types:

input A @oneOf { b:B }
input B { a:A! }

These kinds of types are considered valid on two fronts today:

They are valid as OneOf types because all field types are nullable and there are no default values
They are valid as a circular input object because there are no unbreakable chains of non-null non-list fields

While this follows the letter of the Circular References part of the spec, it violates the spirit of the spec in that there is no way to create a finite, legal value for these types. I propose that these topologies be declared invalid.

I took a stab at reworking the Circular References section to consider OneOfs and added a more formal specification framed around finite values.

netlify · 2026-02-17T00:16:20Z

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	`3ef9ff7`
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/69a6d0b787ee71000837a77c
😎 Deploy Preview	https://deploy-preview-1211--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

benjie · 2026-02-17T08:39:52Z

Excellent catch! I think we can and should fast track this. Once you have the GraphQL.js implementation in place either add it to the next GraphQL WG agenda or let me know if you’d rather I represent it on your behalf.

spec/Section 3 -- Type System.md

benjie

Let's change the named type to an assertion for clarity

benjie · 2026-02-17T10:36:54Z

spec/Section 3 -- Type System.md

+  - Let {namedFieldType} be the underlying named type of {fieldType}.
+  - If {namedFieldType} is not an Input Object type:
+    - Return {true}.
+  - If {namedFieldType} is not a _OneOf Input Object_:
+    - Return {true}.
+  - If {OneOfInputObjectCanBeProvidedAFiniteValue(namedFieldType, nextVisited)}:
+    - Return {true}.


Suggested change

- Let {namedFieldType} be the underlying named type of {fieldType}.

- If {namedFieldType} is not an Input Object type:

- Return {true}.

- If {namedFieldType} is not a _OneOf Input Object_:

- Return {true}.

- If {OneOfInputObjectCanBeProvidedAFiniteValue(namedFieldType, nextVisited)}:

- Return {true}.

- Assert: {fieldType} is a named type.

- If {fieldType} is not an Input Object type:

- Return {true}.

- If {fieldType} is not a _OneOf Input Object_ type:

- Return {true}.

- If {OneOfInputObjectCanBeProvidedAFiniteValue(fieldType, nextVisited)}:

- Return {true}.

viaduct.arbitrary.graphql is a suite of generators used to property test Viaduct and other internal airbnb systems. The generators in this package use a model for GraphQL values, which can be applied to GraphQL objects that require them. Examples of this include the default values for a graphql argument definition, the arguments/variables used in a GraphQL document, or the result of executing a selection set. This value model has evolved over time -- the initial `RawValue` family of types has been gradually replaced with an `IR.Value` model. Currently, both models exist in the code base and are used for slightly different jobs. This PR completely removes the `RawValue` model and updates all systems to use `IR.Value`. Along the way it also updates most components to operate on a ViaductSchema rather than graphql-java's GraphQLSchema. **Better Edgecase Coverage** Before this change, the schema generator would assign default values and applied directives as it generated each type. This created complexity in other parts of the system (eg value generators had to know how to not generate a value for a type that hadn't been defined yet), and made it impossible for the system to generate some kinds of edge cases. This PR changes this behavior to insert default values and applied directives as additional passes, after all types have been generated. This simplifies value generation and allows for more kinds of edge cases to be generated. This ability to generate more edge cases has surfaced some novel issues, such as this potential spec issue with OneOf types: graphql/graphql-spec#1211 Github-Change-Id: 998226 GitOrigin-RevId: 6ae10823b358faf51f883d593d33d6767933ee8b

@OneOf

reframe the issue as as general class of input object habitation, not just a special edge case around pure OneOf trees. This allows handling the case of mixed OneOf/non-OneOf types, like: ```graphql input A @OneOf { b: B } input B { a: A! } ``` To support this, I've also rewritten the previously-proposed `OneOfInputObjectCanBeProvidedAFiniteValue` function as `InputObjectCanBeProvidedAFiniteValue`, which handles both pure inputs, pure OneOfs, and mixed input/OneOfs validation.

jbellenger · 2026-02-26T20:31:38Z

@benjie after looking at this more, I realized that my previous proposal only dealt with closed OneOf trees, but that one can also define uninhabited types by mixing OneOf and non-OneOfs.

For example, this cycle is considered valid by both the current spec and my original proposal:

input A @oneOf { b:B }
input B { a:A! }

I've updated this PR to fold the overly-specific OneOf rules I'd originally written into the Cyclic References section, capturing the general shape of the problem for both flavors of input objects.

This is implemented in graphql-js PR graphql/graphql-js#4564

I was going to plan on being at the graphql-wg call on March 5th, though with the slightly wider scope of this PR I'd be fine to catch a different meeting.

benjie

Great work! For Non-Null type we normally say "Let {innerType} be the inner type of {...}" or "Let {nullableType} be the unwrapped nullable type of", but these are just editorial nits really - the structure looks correct to me.

spec/Section 3 -- Type System.md

benjie · 2026-02-26T22:03:03Z

spec/Section 3 -- Type System.md

+  - Let {innerType} be the type wrapped by {fieldType}.
+  - Return {FieldTypeCanBeProvidedAFiniteValue(innerType, visited)}.
+- Assert: {fieldType} is a named type.
+- If {fieldType} is not an Input Object type:


Not sure if we need this added for clarity... To make it clear that OneOf Input Objects are included?

Suggested change

- If {fieldType} is not an Input Object type:

- If {fieldType} is not an Input Object type (including variants):

I think this has the potential to add more confusion than it clarifies. "Input Object type", without an 'all variants' qualifier, is used consistently to describe OneOf and non-OneOf types. Adding "(including variants)" only here might make readers wonder whether the unqualified uses elsewhere are intentionally exclusive.

That said, you know the spec's editorial voice better than I do, so happy to add it if you think it helps.

Nah, I also don’t think it should be there, but I think it might warrant discussion.

- rename InputObjectCanBeProvidedAFiniteValue to InputObjectHasUnbreakableCycle - rename FieldTypeCanBeProvidedAFiniteValue to InputFieldTypeHasUnbreakableCycle

BoD · 2026-03-02T14:32:26Z

spec/Section 3 -- Type System.md


+Because _OneOf Input Objects_ require exactly one field to be set and non-null,
+nullable fields do not allow a finite value to be provided as they do in other
+Input Objects. This example is invalid because providing a value for `First`


I understand the issue and the counter-example below, but am having trouble parsing/understanding the meaning of this sentence "nullable fields do not allow a finite value to be provided as they do in other Input Objects". Maybe it could be rephrased or maybe it's just me :)

That's fair -- I was trying to describe that while a nullable field would normally provide an escape from infinite recursion, the field-value-may-not-be-null requirement of a OneOf prevents using this escape.

benjie · 2026-03-02T20:02:08Z

spec/Section 3 -- Type System.md

+Because _OneOf Input Objects_ require exactly one field to be set and non-null,
+nullable fields do not allow a finite value to be provided as they do in other
+Input Objects. This example is invalid because providing a value for `First`
+requires a non-null `Second`, and constructing a `Second` requires a non-null
+`First`:


Agree with @BoD; perhaps:

Suggested change

Because _OneOf Input Objects_ require exactly one field to be set and non-null,

nullable fields do not allow a finite value to be provided as they do in other

Input Objects. This example is invalid because providing a value for `First`

requires a non-null `Second`, and constructing a `Second` requires a non-null

`First`:

_OneOf Input Object_ require exactly one field be provided, and that field

cannot be `null`. This example is invalid because providing a value for `First`

requires a non-null `Second`, and constructing a `Second` requires a non-null

`First`:

Thanks @benjie !

In applying this change, I re-read the nearby Circular References section and saw some opportunities to simplify:

Counter Example No 84 uses a different order of value/self fields from other examples

The value field in these examples isn't discussed in the prose and isn't material to this section.

My inclination is to simplify these examples by removing the value fields, which I think would reduce some noise in these examples. Would you support including this change in this PR?

As a counter-argument, the value fields make these examples more realistic, rather than degenerate examples of recursion. Keeping them implies that the example I added around OneOf should probably also have them.

I have no preference either way on the end result (that's more a question for @leebyron) but if you want to rework the existing examples please do so via a separate PR not this one.

Scratch that I do have a preference: leave the existing circular references with the value since it shows its nullability doesn't matter to the problem (there's no branching). Leave your current examples with only one field, because they demonstrate the problem clearly without confusing the reader with combinatorics (because there is branching depending on which field you choose).

Changing the order of value/self in example 84 to be consistent would be a fine separate editorial PR if you were so inclined.

Great! I spun this out into another PR at #1214

apply Benjie's suggestion

spec edits for OneOf inhabitability

1e86f0a

jbellenger marked this pull request as ready for review February 17, 2026 00:17

benjie added the 💭 Strawman (RFC 0) RFC Stage 0 (See CONTRIBUTING.md) label Feb 17, 2026

martinbonnin mentioned this pull request Feb 17, 2026

MegaIssue: GraphQL spec tracking apollographql/apollo-kotlin#6474

Open

9 tasks

martinbonnin reviewed Feb 17, 2026

View reviewed changes

spec/Section 3 -- Type System.md Outdated Show resolved Hide resolved

benjie requested changes Feb 17, 2026

View reviewed changes

This was referenced Feb 17, 2026

OneOf Inhabitability graphql/graphql-js#4564

Open

OneOf Inhabitability graphql-java/graphql-java#4248

Merged

Copilot AI mentioned this pull request Feb 19, 2026

Add OneOf Inhabitability validation graphql-java/graphql-java#4250

Closed

benjie requested changes Feb 26, 2026

View reviewed changes

jbellenger mentioned this pull request Feb 27, 2026

Add OneOf Inhabitability to March WG agenda graphql/graphql-wg#1937

Merged

feedback

d73c3ea

- rename InputObjectCanBeProvidedAFiniteValue to InputObjectHasUnbreakableCycle - rename FieldTypeCanBeProvidedAFiniteValue to InputFieldTypeHasUnbreakableCycle

BoD reviewed Mar 2, 2026

View reviewed changes

benjie reviewed Mar 2, 2026

View reviewed changes

feedback

3ef9ff7

apply Benjie's suggestion

leebyron added 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) and removed 💭 Strawman (RFC 0) RFC Stage 0 (See CONTRIBUTING.md) labels Mar 5, 2026

martinbonnin mentioned this pull request Mar 5, 2026

@oneOf inhabitability apollographql/apollo-kotlin#6891

Open

jbellenger mentioned this pull request Mar 6, 2026

Editorial: consistent field ordering in Circular References examples #1214

Open

	- If {fieldType} is not an Input Object type:
	- If {fieldType} is not an Input Object type (including variants):

Conversation

jbellenger commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Feb 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for graphql-spec-draft ready!

Uh oh!

benjie commented Feb 17, 2026

Uh oh!

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbellenger commented Feb 26, 2026

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbellenger Feb 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BoD Mar 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jbellenger commented Feb 17, 2026 •

edited

Loading

netlify bot commented Feb 17, 2026 •

edited

Loading

jbellenger Feb 28, 2026 •

edited

Loading

BoD Mar 2, 2026 •

edited

Loading