What’s the point of input type in GraphQL?

What’s the point of input type in GraphQL?

165

Could you please explain why if input argument of mutation is object it should be input type? I think much simpler just reuse type without providing id.

For example:

type Sample {
  id: String
  name: String
}

input SampleInput {
  name: String
}

type RootMutation {
  addSample(sample: Sample): Sample  # <-- instead of it should be
  addSample(sample: SampleInput): Sample
}

It’s okay for small object, but when you have plenty of objects with 10+ properties in schema that’ll become a burden.

Share
Improve this question

3

  • 55

    Input objects must be serializable. Because output objects can contain cycles, they can’t be reused for input.

    – Jesse Buchanan

    Jan 19, 2017 at 13:45

  • 2

    Jesse, it looks like enough answer! You can answer and I mark it so.

    – Dmitry Dushkin

    Jan 19, 2017 at 14:19

  • Wondering if it is possible to combine interfaces with it

    – MVCDS

    Apr 11, 2017 at 16:13


3 Answers
3

Reset to default

233

From the spec:

The GraphQL Object type (ObjectTypeDefinition)… is inappropriate for reтАРuse [as an input], because Object types can contain fields that define arguments or contain references to interfaces and unions, neither of which is appropriate for use as an input argument. For this reason, input objects have a separate type in the system.

That’s the “official reason”, but there’s several practical reasons why you can’t use an object type as an input object type or use an object type as an input object type:

Functionality

Object types and input object types both have fields, however those fields have different properties that reflect how these types are used by the schema. Your schema will potentially define arguments and some kind of resolver function for an object type’s fields, but these properties don’t make sense in an input context (i.e. you can’t resolve an input object’s field — it already has an explicit value). Similarly, default values can only be provided for input object type fields, and not object type fields.

In other words, this may seem like duplication:

type Student {
  name: String
  grade: Grade
}

input StudentInput {
  name: String
  grade: Grade
}

But adding features specific to either object types or input object types makes it clear that they behave differently:

type Student {
  name(preferred: Boolean): String
  grade: Grade
}

input StudentInput {
  name: String
  grade: Grade = F
}

Type system limitations

Types in GraphQL are grouped into output types and input types.

Output types are types that may be returned as part of a response produced by a GraphQL service. Input types are types that are valid inputs for field or directive arguments.

There’s overlap between these two groups (i.e. scalars, enums, lists and non-nulls). However, abstract types like unions and interfaces don’t make sense in an input context and cannot be used as inputs. Separating object types and input object types allows you to ensure that an abstract type is never used where an input type is expected.

Schema design

When representing an entity in your schema, it’s likely that some entities will indeed “share fields” between their respective input and output types:

type Student {
  firstName: String
  lastName: String
  grade: Grade
}

input StudentInput {
  firstName: String
  lastName: String
  grade: Grade
}

However, object types can (and in reality frequently do) model very complex data structures:

type Student {
  fullName: String!
  classes: [Class!]!
  address: Address!
  emergencyContact: Contact
  # etc
}

While these structures may translate into appropriate inputs (we create a Student, so we also pass in an object representing their address), often they do not — i.e. maybe we need to specify the student’s classes by class ID and section ID, not an object. Similarly, we may have fields that we want to return, but don’t want to mutate, or vice versa (like a password field).

Moreover, even for relatively simple entities, we often have different requirements around nullability between object types and their “counterpart” input objects. Often we want to guarantee that a field will also be returned in a response, but we don’t want to make the same fields required in our input. For example,

type Student {
  firstName: String!
  lastName: String!
}

input StudentInput {
  firstName: String
  lastName: String
}

Lastly, in many schemas, there’s often not a one-to-one mapping between object type and input object type for a given entity. A common pattern is to utilize separate input object types for different operations to further fine-tune the schema-level input validation:

input CreateUserInput {
  firstName: String!
  lastName: String!
  email: String!
  password: String!
}

input UpdateUserInput {
  email: String
  password: String
}

All of these examples illustrate an important point — while an input object type may mirror an object type some of the time, you’re much less likely to see that in production schemas due to business requirements.

Share
Improve this answer

11

  • 22

    this is indeed a great answer!

    – Charlie Ng

    Oct 23, 2019 at 0:52

  • 1

    Correct me if I’m wrong but in your example, the type Grade cannot be reused in the input StudentInput, right? You’ll need to either inline fields in the input object or have a GradeInput input object.

    – Matt

    May 15, 2020 at 8:44

  • 3

    @Matt Good question! In the above example, Grade is an enum type. Unlike with objects, scalar types (like String, Int, etc.) and enums types can be used as both input types and output types.

    – Daniel Rearden

    May 15, 2020 at 10:32

  • 1

    This is so much clearer now — if I’m understanding things correctly, in GraphQL there are both Input Types and “output types”, that each deal separately with incoming requests or outgoing responses. But, the GraphQL “output types” are actually never referred to as such, output types are simply called Type. Perhaps in a later version instead of using type and input it would be clearer to use output and input. Thanks for the explanation

    – FireDragon

    Nov 21, 2021 at 17:18

  • 1

    @RoyLeibovitz as outlined in the “Functionality” section above, fields on output types and input types each have different properties, so having an output type extend an input type (or vice versa) would be problematic and is not supported by the spec. Depending on the language, libraries and frameworks you’re using, it may be possible using some hacky method, but I would highly discourage doing so.

    – Daniel Rearden

    Dec 30, 2021 at 1:56

29

Jesse’s comment is correct. For more formal answer, here is the excerpt from GraphQL documentation on input types:

The Object type defined above is inappropriate for reтАРuse here,
because Objects can contain fields that express circular references or
references to interfaces and unions, neither of which is appropriate
for use as an input argument. For this reason, input objects have a
separate type in the system.

UPDATE

Since posting it, I found that circular references actually are acceptable, so long as those are nilable (or else it would declare an infinite chain). But, still there are other limitations (e.g. interfaces) that seem to necessitate a separate type system for inputs.

Share
Improve this answer

1

1

Simply because you don’t want to couple your public API to your Domain models or DB models. Incoming data is represented differently in response data. You don’t want to reuse the same data type for incoming vs outcoming…or you’ll completely tie your users to your domain or db model and that means anything you change can break your clients

What Input types are, are essentially RequestTypes. When you think of boundaries between the delivery mechanism (the client making the request) and the boundary between that and the business logic below your controller when you think about a Hexagonal Architecture for example.

Share
Improve this answer



    Your Answer


    Post as a guest

    Required, but never shown


    By clicking тАЬPost Your AnswerтАЭ, you agree to our terms of service, privacy policy and cookie policy

    Not the answer you’re looking for? Browse other questions tagged

    or ask your own question.

    Leave a Reply

    Your email address will not be published. Required fields are marked *