Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b600a58

Browse files
benjiepatrick91spawnia
authored
Add oneOf blog post (#2011)
* Add oneOf blog post * Update src/pages/blog/2025-06-19-multioption-inputs-with-oneof/index.mdx * Apply suggestions from code review * Add comments and availability * Formatting * Don't break markdown formatting * Update src/pages/blog/2025-06-19-multioption-inputs-with-oneof/index.mdx Co-authored-by: Patrick Arminio <[email protected]> * Update src/pages/blog/2025-06-19-multioption-inputs-with-oneof/index.mdx Co-authored-by: Benedikt Franke <[email protected]> * Re-date * Update links --------- Co-authored-by: Patrick Arminio <[email protected]> Co-authored-by: Benedikt Franke <[email protected]>
1 parent 71b97cb commit b600a58

File tree

2 files changed

+157
-0
lines changed

2 files changed

+157
-0
lines changed

‎.prettierignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ pnpm-lock.yaml
66
!src/pages/community/foundation/community-grant.mdx
77
!src/pages/blog/2025-05-31-graphiql-4/index.mdx
88
!src/pages/blog/2025-06-10-graphiql-5/index.mdx
9+
!src/pages/blog/2025-06-19-multioption-inputs-with-oneof/index.mdx
910
*.jpg
1011

1112
scripts/sync-sched/*.json

‎src/pages/blog/2025-09-04-multioption-inputs-with-oneof/index.mdx‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
---
2+
title: Safer Multi-option Inputs with `@oneOf`
3+
tags: [announcements, spec]
4+
date: 2025-09-04
5+
byline: Benjie Gillam
6+
---
7+
8+
We’re excited to announce **[OneOf Input
9+
Objects](https://spec.graphql.org/September2025/#sec-OneOf-Input-Objects)** has
10+
landed in the GraphQL specification! This enhancement solves a long-standing
11+
challenge in API design: how to allow users to provide **exactly one** of
12+
several possible options as input, in a clean and enforceable way. This feature
13+
is a [small change](https://github.com/graphql/graphql-spec/pull/825) that packs
14+
a big return for developers building modern digital products with GraphQL.
15+
16+
## Simplifying entrypoints
17+
18+
Most GraphQL queries start at a single node, and traverse the data graph from
19+
there. But often, there is more than one way of locating that node; for example
20+
you might find a user by their ID, email address, or username. Traditionally,
21+
that meant multiple root-level fields:
22+
23+
```graphql
24+
type Query {
25+
user(id: ID!): User
26+
userByEmail(email: String!): User
27+
userByUsername(username: String!): User
28+
}
29+
```
30+
31+
_(An alternative approach was a less-than-type-safe field presenting all the
32+
options along with custom runtime validation to enforce the constraints. Either
33+
way, neither solution was ideal.)_
34+
35+
With `@oneOf`, you can now consolidate those options into a single,
36+
user-friendly input which ensures users supply _exactly one_ input field, the
37+
value of which must not be null. The result: a user-friendly schema with fewer
38+
root-level fields and without sacrificing type safety:
39+
40+
```graphql
41+
input UserBy @oneOf {
42+
id: ID
43+
email: String
44+
username: String
45+
}
46+
47+
type Query {
48+
user(by: UserBy!): User
49+
}
50+
```
51+
52+
## Input polymorphism
53+
54+
Of course, `@oneOf`'s use isn't limited to simple scalars — it can also be used
55+
to choose between multiple complex input types, allowing for polymorphism in
56+
GraphQL inputs.
57+
58+
Imagine you were building a user-friendly blogging website, and each post is
59+
made up of elements — paragraphs, image galleries, block quotes, code blocks,
60+
and the like. Each of these elements come with their own set of (potentially
61+
overlapping) attributes, and you want to feed a list of them into your mutation.
62+
With @oneOf you can do so in a type safe manner:
63+
64+
```graphql
65+
type Mutation {
66+
createPost(elements: [PostElementInput]): Post
67+
}
68+
input PostElementInput @oneOf {
69+
paragraph: ParagraphInput
70+
blockquote: BlockQuoteInput
71+
gallery: GalleryInput
72+
}
73+
input ParagraphInput {
74+
text: String!
75+
}
76+
input BlockQuoteInput {
77+
text: String!
78+
attribution: String
79+
attributionUrl: String
80+
}
81+
input GalleryInput {
82+
imageUrls: [String!]!
83+
caption: String
84+
attribution: String
85+
}
86+
```
87+
88+
## What makes `@oneOf` the right solution?
89+
90+
- **Backward Compatible**: Existing tools, queries and clients still work,
91+
meaning no major overhauls are required. Existing clients can even use oneOf
92+
inputs without updating; just be careful to always supply exactly one value!
93+
- **Minimal Complexity**: This feature introduces only a small change to the
94+
existing type system, but delivers very significant benefits.
95+
- **Type-Safe Input Polymorphism**: Offers a safe and scalable way to accept a
96+
variety of inputs under a single structure—something previously hard to
97+
achieve in GraphQL.
98+
- **Now part of the GraphQL standard**: Several GraphQL implementations
99+
including Ruby, Java, JavaScript and .NET already ship `@oneOf` as a stable
100+
feature
101+
102+
You might wonder why this is expressed as a directive in SDL rather than
103+
explicitly having a new type keyword; Brad Baker, contributor to GraphQL-Java,
104+
summed it up in
105+
[this comment back in 2023](https://github.com/graphql/graphql-spec/pull/825#issuecomment-1659900665):
106+
107+
> use of the directive means that:
108+
>
109+
> - it's minimally invasive in terms of SDL tooling that might be out there,
110+
> - it's minimally invasive in terms of Introspection,
111+
> - it's minimally invasive in terms of engine implementation, it proved quite
112+
> easy to implement in graphql-java.
113+
>
114+
> Great stuff!
115+
116+
Since then there have been a number of reports of success:
117+
118+
> I'm very happy with where this landed. We'd use it internally at my company. —
119+
> [Ethan Resnick](https://github.com/graphql/graphql-spec/pull/825#issuecomment-2128262620)
120+
121+
> More positive feedback: We are using it at HubSpot through the graphql-java
122+
> implementation and look forward to it becoming standardized. —
123+
> [Henry Q. Dineen](https://github.com/graphql/graphql-spec/pull/825#issuecomment-2128324080)
124+
125+
> I implemented support for OneOf input objects for the Caliban GraphQL library
126+
> (Scala) [...] it's been fairly straightforward implementing support for it and
127+
> I couldn't really identify any areas that could have been improved. —
128+
> [kyri-petrou](https://github.com/kyri-petrou)
129+
130+
> We have been eagerly waiting at Jobber for this to land as well. [...] We have
131+
> many use cases internally for it and we're very excited to see this land! —
132+
> [Clinton Pahl](https://github.com/graphql/graphql-spec/pull/825#issuecomment-2135724148)
133+
134+
> Colleagues at work (Atlassian) have been really happy with @oneOf, works
135+
> exactly as you want it to and I haven't heard any negative feedback. —
136+
> [Donna Zhou](https://github.com/dondonz)
137+
138+
## Availability
139+
140+
`@oneOf` is already available in at least the following implementations of GraphQL:
141+
142+
- GraphQL.js v16+
143+
- GraphQL Ruby v2.0.21+
144+
- GraphQL.NET v8+
145+
- GraphQL Java v21.2+
146+
- HotChocolate v16.0.0+
147+
- Strawberry GraphQL v0.230.0+
148+
- GraphQL Core (Python) v3.3.0+
149+
- webonyx/graphql-php (PHP) v15.21.0+
150+
- Probably others!
151+
152+
## The bottom line
153+
154+
`@oneOf` allows for more expressive, capable, and less overwhelming schemas,
155+
helping technical teams to move faster with increased safety. It’s simple and
156+
easy to implement, try it today!

0 commit comments

Comments
 (0)