Introducing: GraphQL Cost Directives Specification

4 minute read

We’ve just released a first draft of a specification for directives to enable GraphQL Cost Analysis.


I’ve discussed why GraphQL cost analysis is important, and surveyed current use by some public endpoints and open source libraries as well as products and academic research.

I think it would help the industry to standardize how GraphQL servers express the cost of their types and fields. We laid out the goals of standardizing, but it basically comes down to interop: we see GraphQL cost as something that can be expressed from the server, through the proxy, to the client. Therefore it is likely to involve software from multiple sources and written in multiple programming languages, which means that it helps to standardize. I also expect that input from others will improve the spec.

GraphQL Cost Directives Spec


With this first published draft, we introduce a GraphQL Cost Directives Spec, a formalization of how to express cost in GraphQL. We spent over 3 years researching the GraphQL industry, implementing different cost metrics, analyzing problem cases, and engaging with customers. Our goal is to share things we’ve learned over these years and to find people who would like to work with us in evolving the spec as well as developing tools around it.

GraphQL Cost Directives Spec


Why are we not seeing more GraphQL public endpoints at the world’s largest companies? There are multiple reasons for this, but we believe that one of the core reasons is the inability to easily protect GraphQL endpoints without better modeling of the cost of GraphQL queries. Maybe we can solve this as a united GraphQL community effort to close this gap in GraphQL schema expressiveness.


Thanks to the entire team who have contributed to this first public draft!

  • We’re building on years of rigorous academic work in IBM Research, which in November 2020 led to a distinguished paper award at ESEC/FSE 2020.
  • We’re relying on years of development experience both implementing these ideas as well as working them through large customer GraphQL deployments around the world. Thanks to the core development team: Daniel Shih, Andy Chang, Igor Belyi, Yali Nachum, Naveed Annur, Di Zhang, Ketki Thakre, Shawn Laflamme, and so many more people who made our development effort a reality.
  • Great thanks to our IBM Research partners Jim Laredo and Alan Cha who after having motivated our work, also graciously keep discussing both our work and their continuing research, advising us, and even reviewing and improving our drafts.
  • Extra thanks to Igor Belyi and Andy Chang who made especially substantive and pervasive comments on the spec that significantly improved what we are publishing today.

Last but not least, a very special thanks and great credit needs to go to my friend Erik Wittern. He was both part of the IBM Research team that started developing the ideas we built on, and then moved over to the IBM Development team that dramatically modified those ideas “when the rubber hit the road.”

Erik was a great partner to have in this effort, working collaboratively with me both when he was my counterpart in Research, and also after he joined my team. Erik was always willing to have another conversation delving into another far-fetched GraphQL schema or GraphQL query and what it would mean for our query analysis or cost directives. Even after finally coming to consensus after hours and hours of discussion and consideration, he would still be willing to re-consider it the next day, next week, or next month, regardless of which of the two of us figured out the need to reconsider it.

I made changes to the spec when he was on leave with his family, so if you don’t like a section it can be my fault entirely, but without Erik there would be no spec at all, so if you like it then we should thank him!


Do you have comments, advice, or want to discuss tradeoffs? In the collaboration section, we point people to a #cost-analysis slack channel in the GraphQL Workspace. I’m also happy to have a call to discuss - just let me know!