graphql / graphql/graphql-js

Standardize the naming of the first argument to resolver functions (obj vs parent)

Open
#2,842 7 comments 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
20.3k
Forks
2.1k
Avg merge
44m
Merged PRs (30d)
6

Description

According to, [graphql.org/learn](https://graphql.org/learn/execution/#root-fields-resolvers), _"A resolver function receives four arguments"_. It lists the first one as:

> `obj` The previous object, which for a field on the root Query type is often not used.

However, [Apollo's](https://www.apollographql.com/docs/apollo-server/data/resolvers/#handling-arguments) [docs](https://www.apollographql.com/docs/apollo-server/data/resolvers/#resolver-arguments) calls this same argument 'parent':

> `parent` The return value of the resolver for this field's parent (i.e., the previous resolver in the resolver chain).

`obj` vs `parent` is a source of confusion throughout the ecosystem. We see this elsewhere too:

- Even within the same project (the popular graphql-tools), both [`obj`](https://www.graphql-tools.com/docs/resolvers#resolver-function-signature) and [`parent`](https://www.graphql-tools.com/docs/generate-schema#extending-types) are used.
- Outside of JavaScript, we see different projects using different terminology. [Scala uses `obj`](https://graphql-ruby.org/fields/resolvers.html#extensions), [Python uses `parent`](https://docs.graphene-python.org/en/latest/types/objecttypes/#resolver-parameters).

## "We already have a standard - obj! Ask the non-conformists to switch!"

I could see this argument, and I'm happy to close this issue out if that's how the mainters feel.

_However!_ ...allow me to put forward a case for `parent` and bikeshed for a moment:

1. **I believe the name "parent" converys more meaningful information than "obj".** It signals some sort of relationship to something above us. This more strongly hints that obj/parent === the return value of the previous (or "parent") resolver.
2. **"object" could be implementation detaily**, or at best, is ambiguous to if this represents the language-specific construct (e.g. javascript objects) or a conceptual "object" (not all languages have dicts/objects!)

I'm not sure what the timelines are or who first decided to use "parent", but I'm guessing this happened for a reason, and this isn't the first time this issue has been discussed. If anyone can find any written deliberation about this, I'd be interested to read up!

Speaking first hand, teaching resolver arguments concepts is hard. This in particular has come up as a source of confusion (hence me making this issue) internally at my workplace. Any gradual win here will be leveraged across many many folks learning this anew.

Members of the jury, in conclusion, I believe it would be an admirable goal to standardise obj vs parent. I personally vote for parent, but would be happy with obj. Either way, I would like to start a mission to try and standardize this across tooling/languages.

## What does the spec say?

The official GraphQL spec avoids giving language specific implementation details, so it doesn't (can't?) standardize a name for this. However it does [hint at "object" in an example given](https://spec.graphql.org/draft/#sec-Value-Resolution).

Perhaps a non-normative note somewhere in the spec would be a good place provide a hint and normalize the naming.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.