Skip to content

Latest commit

 

History

History
57 lines (47 loc) · 3.24 KB

Section 1 -- Overview.md

File metadata and controls

57 lines (47 loc) · 3.24 KB
Raw

Overview

The GraphQL Composite Schemas specification describes how to construct a single unified GraphQL schema, the composite schema, from multiple GraphQL schemas, each termed a source schema.

The composite schema presents itself as a regular GraphQL schema; the implementation details and complexities of the underlying distributed systems are not visible to clients, all observable behavior is the same as described by the GraphQL specification.

The GraphQL Composite Schemas specification has a number of design principles:

  • Composable: Rather than defining each source schema in isolation and reshaping it to fit the composite schema later, this specification encourages developers to design the source schemas as part of a larger whole from the start. Each source schema defines the types and fields it is responsible for serving within the context of the larger schema, referencing and extending that which is provided by other source schemas. The GraphQL Composite Schemas specification does not describe how to combine arbitrary schemas.

  • Collaborative: The GraphQL Composite Schemas specification is explicitly designed around team collaboration. By building on a principled composition model, it ensures that conflicts and inconsistencies are surfaced early and can be resolved before deployment. This allows many teams to contribute to a single schema without the danger of breaking it. The GraphQL Composite Schemas specification facilitates the coordinated effort of combining collaboratively designed source schemas into a single coherent composite schema.

  • Evolvable: A composite schema enables offering an integrated, product-centric API interface to clients; source schema boundaries are an implementation detail, a detail that is not exposed to clients. As each underlying GraphQL service evolves, the same functionality may be provided from a different combination of services. This specification helps to ensure that changes to underlying services can be made whilst maintaining support for existing requests from all clients to the composite schema interface.

  • Explicitness: To make the composition process easier to understand and to avoid ambiguities that can lead to confusing failures as the system grows, the GraphQL Composite Schemas specification prefers to be explicit about intentions and minimize reliance on inference and convention.

To enable greater interoperability between different implementations of tooling and gateways, this specification focuses on two core components: schema composition and distributed execution.

  • Schema Composition: Schema composition describes the process of merging multiple source schema into a single GraphQL schema, the composite schema. During this process, an intermediary schema, the composite execution schema, is generated. This composite execution schema is annotated with directives to describe execution, and may have additional internal fields or arguments that won't be exposed in the client-facing composite schema.

  • Distributed Execution: The distributed GraphQL executor specifies the core execution behavior and algorithms that enable fulfillment of a GraphQL request performed against the composite schema.