From 5cb364f7ae807ced8e82992dab5d1cba8ceea51b Mon Sep 17 00:00:00 2001 From: Glen Date: Tue, 17 Dec 2024 15:02:29 +0200 Subject: [PATCH] Editorial Changes (#62) --- spec/Section 2 -- Source Schema.md | 22 ++++++++++++---------- spec/Section 4 -- Composition.md | 12 ++++++------ spec/Spec.md | 15 ++++++++------- 3 files changed, 26 insertions(+), 23 deletions(-) diff --git a/spec/Section 2 -- Source Schema.md b/spec/Section 2 -- Source Schema.md index 5bbc683..50656e1 100644 --- a/spec/Section 2 -- Source Schema.md +++ b/spec/Section 2 -- Source Schema.md @@ -261,7 +261,8 @@ lookup fields that can resolve entities by different keys. ```graphql example extend type Query { person( - by: PersonByInput @is(field: "{ id } | { addressId: address.id } { name }") + by: PersonByInput + @is(field: "{ id } | { addressId: address.id } | { name }") ): Person } @@ -298,7 +299,7 @@ type Product { } ``` -The upper example would translate to the following in the _composite schema_. +The above example would translate to the following in the _composite schema_. ```graphql example type Product { @@ -309,7 +310,7 @@ type Product { This can also be done by using input types. The selection path map specifies which data is required and needs to be resolved from other source schemas. If -the input type is only used to express a requirements it is removed from the +the input type is only used to express requirements it is removed from the composite schema. ```graphql example @@ -384,8 +385,8 @@ type Product @key(fields: "id") @key(fields: "key") { ``` While multiple keys define separate ways to reference the same entity based on -different sets of fields, a composite key allows to uniquely identify an entity -by using a combination of multiple fields. +different sets of fields, a composite key allows for uniquely identifying an +entity by using a combination of multiple fields. ```graphql example type Product @key(fields: "id sku") { @@ -416,8 +417,8 @@ field to an object type. This prevents source schemas from inadvertently defining similarly named fields that are semantically not the same. Fields have to be explicitly marked as `@shareable` to allow multiple source -schemas to define it, and ensures that the step of allowing a field to be served -from multiple source schemas is an explicit, coordinated decision. +schemas to define it, and this ensures that the step of allowing a field to be +served from multiple source schemas is an explicit, coordinated decision. If multiple source schemas define the same field, these are assumed to be semantically equivalent, and the executor is free to choose between them as it @@ -433,7 +434,8 @@ directive @provides(fields: SelectionSet!) on FIELD_DEFINITION The `@provides` directive is an optimization hint specifying child fields that can be resolved locally at the given source schema through a particular query -path. This allows for a variation of overlapping field to improve data fetching. +path. This allows for a variation of overlapping fields to improve data +fetching. **Arguments:** @@ -446,7 +448,7 @@ directive @external on OBJECT_DEFINITION | INTERFACE_DEFINITION | FIELD_DEFINITI ``` The `@external` directive is used in combination with the `@provides` directive -and specifies data that is not owned ba a particular source schema. +and specifies data that is not owned by a particular source schema. ### @override @@ -454,5 +456,5 @@ and specifies data that is not owned ba a particular source schema. directive @override(from: String!) on FIELD_DEFINITION ``` -The `@override` directive allows to migrate fields from one source schema to +The `@override` directive allows for migrating fields from one source schema to another. diff --git a/spec/Section 4 -- Composition.md b/spec/Section 4 -- Composition.md index 4a18fd3..f9e4cdf 100644 --- a/spec/Section 4 -- Composition.md +++ b/spec/Section 4 -- Composition.md @@ -4,11 +4,11 @@ The schema composition describes the process of merging multiple source schemas into a single GraphQL schema, known as the _composite execution schema_, which is a valid GraphQL schema annotated with execution directives. This composite execution schema is the output of the schema composition process. The schema -composition process is divided into four major algorithms: **Validate Source -Schema**, **Merge Source Schema**, and **Validate Satisfiability**, which are +composition process is divided into three main steps: **Validate Source +Schemas**, **Merge Source Schemas**, and **Validate Satisfiability**, which are run in sequence to produce the composite execution schema. -## Validate Source Schema +## Validate Source Schemas ## Merge Source Schemas @@ -126,7 +126,7 @@ input Input1 { **Error Code** -OUTPUT_FIELD_TYPES_NOT_MERGEABLE +`OUTPUT_FIELD_TYPES_NOT_MERGEABLE` **Severity** @@ -253,8 +253,8 @@ ERROR This rule ensures that certain essential elements of a GraphQL schema, particularly built-in scalars, directives and introspection types, cannot be -marked as `@inaccessible`. These types are fundamental to GraphQL's. Making -these elements inaccessible would break core GraphQL functionalities. +marked as `@inaccessible`. These types are fundamental to GraphQL. Making these +elements inaccessible would break core GraphQL functionality. Here, the `String` type is not marked as `@inaccessible`, which adheres to the rule: diff --git a/spec/Spec.md b/spec/Spec.md index d138d78..146d4d4 100644 --- a/spec/Spec.md +++ b/spec/Spec.md @@ -2,7 +2,7 @@ **Introduction** -The GraphQL Composite Schemas introduces a comprehensive specification for +The GraphQL Composite Schemas Spec introduces a comprehensive specification for creating distributed GraphQL systems that seamlessly merges multiple GraphQL schemas. This specification describes the process of composing a federated GraphQL schema and outlines algorithms for executing GraphQL queries on the @@ -41,9 +41,10 @@ POSSIBILITY OF SUCH DAMAGE. **Conformance** -A conforming implementation of GraphQL over HTTP must fulfill all normative -requirements. Conformance requirements are described in this document via both -descriptive assertions and key words with clearly defined meanings. +A conforming implementation of the GraphQL Composite Schemas Spec must fulfill +all normative requirements. Conformance requirements are described in this +document via both descriptive assertions and key words with clearly defined +meanings. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the normative portions of @@ -52,9 +53,9 @@ this document are to be interpreted as described in in lowercase and still retain their meaning unless explicitly declared as non-normative. -A conforming implementation of GraphQL over HTTP may provide additional -functionality, but must not where explicitly disallowed or would otherwise -result in non-conformance. +A conforming implementation of the GraphQL Composite Schemas Spec may provide +additional functionality, but must not where explicitly disallowed or would +otherwise result in non-conformance. **Non-Normative Portions**