Document Level Directives

[tusharmath]

GraphQL Document-Level Directives Proposal

Introduction

As GraphQL's popularity continues to surge, its potential extends beyond just efficient data fetching. Solutions like Apollo Federation, Hasura, Prisma and Tailcall have already showcased the power and flexibility of the GraphQL DSL. Recognizing this, our proposal seeks to further harness this potential by allowing directives at the document level, opening doors to more intuitive ORMs, CMS configurations, and backend tooling.

Problem Statement

While the current GraphQL specification permits directives on the schema, it does not support them at a broader document level. This limitation restricts the configuration options for applications that use the GraphQL DSL for more than just data-fetching.

Proposed Solution

Allow directives to be attached directly to the document. Instead of the current:

schema
  @disableHttpCache
  @idleConnectionPool(size: 300, timeout: 300)
  @namespace(name: "global") {
    query: Query
    mutation: Mutation
}

We propose:

@disableHttpCache
@idleConnectionPool(size: 300, timeout: 300)
@namespace(name: "global")

schema {
  query: Query
  mutation: Mutation
}

This change provides a cleaner syntax, especially when directives don't semantically fit at the schema level.

Test On Guiding Principles

• Backwards Compatibility: Existing APIs remain unaffected. This proposal introduces a new type for directive definitions: DOCUMENT.

  directive @disableHttpCache on DOCUMENT
  

• Performance: No performance implications.

• Favour No Change: Implementing this proposal will require changes in existing GraphQL parsers.

• Real Use Cases: With GraphQL DSL powering ORMs, proxies (e.g., [Tailcall]), and orchestrations through Federation, this change can make directive definitions even more impactful.

• Simplicity & Consistency: The proposal aligns with existing syntax and does not introduce new complexities.

• Preserve Option: No implications on this principle.

• Understandability: The proposed change aims to be intuitive, but we welcome community feedback.

Conclusion

By embracing document-level directives, GraphQL can further solidify its position as a versatile tool for diverse applications. We look forward to the community's feedback on this proposal.