From 404150fbb8eb09fc35d82a2db5b61062b180bdf1 Mon Sep 17 00:00:00 2001 From: Michael Staib Date: Wed, 24 Jan 2024 11:13:53 +0100 Subject: [PATCH] merged introductions --- spec/Section 1 -- Overview.md | 32 +++++++++++++++++-- ...graph.md => Section 2 -- Source Schema.md} | 0 spec/Spec.md | 2 +- 3 files changed, 31 insertions(+), 3 deletions(-) rename spec/{Section 2 -- Subgraph.md => Section 2 -- Source Schema.md} (100%) diff --git a/spec/Section 1 -- Overview.md b/spec/Section 1 -- Overview.md index 1981286..1798007 100644 --- a/spec/Section 1 -- Overview.md +++ b/spec/Section 1 -- Overview.md @@ -9,13 +9,41 @@ and complexities of the underlying distributed systems are hidden. The observable behavior of the distributed GraphQL executor is the same as that of a standard GraphQL executor as described by the GraphQL specification. +GraphQL Composite Schemas specification has a number of design principles: + +- **Composable**: Rather than defining GraphQL schemas in isolation and + reshaping them to fit a composed graph later, it encourages developers to + think of GraphQL schemas as partial schemas that are designed as part of a + larger schema from the get go. Each source schema defines the types and fields + it is responsible for serving within the context of a larger schema, + referencing and extending what is already there. In other words, the GraphQL + Composite Schemas specification is not designed to glue arbitrary schemas + together, but to facilitate a coordinated effort to build a coherent composite + schema. + +- **Collaborative**: The GraphQL Composite Schemas specification is explicity + 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 deploying. This allows many teams to contribute to a + single schema without the danger of breaking it. + +- **Evolvable**: A composite schema offers an integrated, product-centric view + of underlying services. And these services should be able to evolve without + disrupting clients. Over time, the same functionality may be provided by a + different combination of services, while the schema surface stays the same. + Source schema boundaries are therefore considered an implementation detail and + should never be exposed to clients. + +- **Explicitness**: This specification values explicitness over inferring + intentions, as these tend to break down and can lead to ambiguity over time. + This specification focuses on two core components to allow interoperability between tooling and gateways from different implementers, the schema composition and the execution. -- **Composition**: The schema composition describes a process of merging +- **Composition**: The schema composition describes the process of merging multiple source schemas into a single GraphQL schema that is annotated with execution directives and is referred to as the composite schema. - **Execution**: The distributed GraphQL executor specifies the core execution - behavior and algorithms. \ No newline at end of file + behavior and algorithms. diff --git a/spec/Section 2 -- Subgraph.md b/spec/Section 2 -- Source Schema.md similarity index 100% rename from spec/Section 2 -- Subgraph.md rename to spec/Section 2 -- Source Schema.md diff --git a/spec/Spec.md b/spec/Spec.md index 95db05b..112d195 100644 --- a/spec/Spec.md +++ b/spec/Spec.md @@ -83,7 +83,7 @@ Note: This is an example of a non-normative note. # [Overview](Section%201%20--%20Overview.md) -# [Subgraph](Section%202%20--%20Subgraph.md) +# [Subgraph](Section%202%20--%20Source%20Schema.md) # [Supergraph](Section%203%20--%20Supergraph.md)