Editorial: Type kinds #970

leebyron · 2022-06-27T19:05:03Z

This provides definitions at the introduction of "Type System" for leaf type, composite type, and abstract type. Then, these definitions are used throughout the spec.

Inspired by #957 which had included clarifications around "leaf" types and fields. This uses definition syntax to formally define the terms so they can be used.

This ended up being a pretty big change, so I'd love a review

This provides definitions at the introduction of "Type System" for _leaf type_, _composite type_, and _abstract type_. Then, these definitions are used throughout the spec.

netlify · 2022-06-27T19:05:12Z

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	`3b00fdb`
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/62b9ff6434c4f2000956e6be
😎 Deploy Preview	https://deploy-preview-970--graphql-spec-draft.netlify.app/draft
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

rivantsov · 2022-06-27T20:06:18Z

spec/Section 3 -- Type System.md

-enumerable. GraphQL offers an `Enum` type in those cases, where the type
-specifies the space of valid responses.
+:: A _leaf type_ is a kind of type representing a primitive value which cannot
+be further selected and thus form the leaves in a response tree. GraphQL


something does not match; if subject is 'kind' (singular) then the verb should be 'forms' (singular)

General suggestion
I think 'kind of type' is confusing, since we have already TYPE_KIND, different kind. What we introduce here are groups of types, sort of, purely for easier references in the spec; these groups or categories do not appear anywhere at runtime or in graphql artifacts - purely for shorter and simpler spec references.

So instead of
A Leaf type is a kind of type representing ...

we can say simply
Leaf types are types representing

without even explicitly calling it a group or category

(Edit) PS - actually this way (without kind) is phrased in other cases, so we would need to just change this spot.

rivantsov · 2022-06-27T20:08:21Z

spec/Section 3 -- Type System.md


-GraphQL supports two abstract types: interfaces and unions.
+:: A _composite type_ is a type composed of other types via a set of named


need consistency in capitalizing - if 'Leaf type' then 'Composite type'

rivantsov · 2022-06-27T20:11:21Z

spec/Section 3 -- Type System.md

-A `Union` defines a list of possible types; similar to interfaces, whenever the
-type system claims a union will be returned, one of the possible types will be
-returned.
+:: An _abstract type_ allows a GraphQL schema to introduce polymorphism; where a


I think it should be comma after polymorphism, not semicolon.

rivantsov · 2022-06-27T20:15:27Z

spec/Section 3 -- Type System.md

+of which yield a value of a specific type. Object values should be serialized as
+ordered maps, where the selected field names (or aliases) are the keys and the
+result of evaluating the field is the value, ordered by the order in which they
+appear in the selection set.


we might mention here that field names might repeat in this output map, as a result of field merging

rivantsov · 2022-06-27T20:18:18Z

spec/Section 3 -- Type System.md

-differ from interfaces in that Object types declare what interfaces they
-implement, but are not aware of what unions contain them.
+GraphQL Unions are an _abstract type_ representing one of a list of GraphQL
+Object possible types, but provides for no guaranteed fields between those


provides -> provide ? since Unions (plural)

rivantsov · 2022-06-27T20:22:52Z

spec/Section 4 -- Introspection.md

-out in `possibleTypes`.
+Interfaces are an _abstract type_ where there are common fields declared. Any
+type that implements an interface must define all the fields with names and
+types exactly matching. The implementations of this interface are explicitly


I do not think we require exact matching of type for implementing field. It can be derived/compatible type
Like interface declares:
boo : IBoo
while implementing type can declare
boo: Boo # implements IBoo

rivantsov · 2022-06-27T20:27:37Z

spec/Section 5 -- Validation.md

-possible types of the scope and the spread, the spread is considered valid.
+In the scope of an _abstract type_ (interface or union), a fragment spread of
+another _abstract type_ can be used as long as there exists at least _one_
+object type that exists in the intersection of the possible types of the scope


there exists... that exists ...

suggest to rephrase

benjie

Looking good; great readability/cross-referencing improvements I think 👍

benjie · 2022-06-28T10:04:09Z

spec/Section 3 -- Type System.md

+:: A _leaf type_ is a kind of type representing a primitive value which cannot
+be further selected and thus form the leaves in a response tree. GraphQL


A bit wordy, but...

Suggested change

:: A _leaf type_ is a kind of type representing a primitive value which cannot

be further selected and thus form the leaves in a response tree. GraphQL

:: A _leaf type_ is a kind of type representing a primitive value which cannot

be further selected, thus the type of each leaf in a response tree is a leaf type. GraphQL

benjie · 2022-06-28T10:04:54Z

spec/Section 3 -- Type System.md

-`Object` types, which define a set of fields, where each field is another type
-in the system, allowing the definition of arbitrary type hierarchies.
+A `Scalar` represents a primitive scalar value, such as a string or number.
+Oftentimes, the possible responses for a scalar field are enumerable. GraphQL


Suggested change

Oftentimes, the possible responses for a scalar field are enumerable. GraphQL

Oftentimes, the possible responses for a leaf field are enumerable. GraphQL

benjie · 2022-06-28T10:24:01Z

spec/Section 3 -- Type System.md

@@ -635,14 +646,14 @@ FieldDefinition : Description? Name ArgumentsDefinition? : Type
 Directives[Const]?

 GraphQL operations are hierarchical and composed, describing a tree of
-information. While Scalar types describe the leaf values of these hierarchical
+information. While _leaf types_ describe the leaf values of these hierarchical
 operations, Objects describe the intermediate levels.


Objects (and lists) descr...

benjie · 2022-06-28T10:24:57Z

spec/Section 3 -- Type System.md

-selected field names (or aliases) are the keys and the result of evaluating the
-field is the value, ordered by the order in which they appear in the selection
-set.
+GraphQL Objects are a _composite type_ representing a list of named fields, each


Suggested change

GraphQL Objects are a _composite type_ representing a list of named fields, each

GraphQL Objects are a _composite type_ comprised of a list of named fields, each

benjie · 2022-06-28T10:28:51Z

spec/Section 3 -- Type System.md

+GraphQL interfaces are an _abstract type_ which when used as the type of a field
+provides polymorphism where any implementation may be a possible type during
+execution.


Previously it was stated that an interface may implement an interface. So "any implementation" could be perceived as including object types and interfaces. Let's clarify:

Suggested change

GraphQL interfaces are an _abstract type_ which when used as the type of a field

provides polymorphism where any implementation may be a possible type during

execution.

GraphQL interfaces are an _abstract type_ which when used as the type of a field

provides polymorphism where any implementing object type may be a possible type during

execution.

benjie · 2022-06-28T11:02:40Z

spec/Section 4 -- Introspection.md

+Input Objects are a _composite type_ defined as a list of named input field
+values. They are only used as inputs to arguments and variables and cannot be a
+field return type.


Want to make it clear that input objects can be comprised of other input objects, and thus they are not only the full input to arguments but also parts thereof. I'm not sure if dropping the s conveys this subtlety, but...

Suggested change

Input Objects are a _composite type_ defined as a list of named input field

values. They are only used as inputs to arguments and variables and cannot be a

field return type.

An Input Object is a _composite type_ defined as a list of named input field

values. They are only used as input to arguments and variables and cannot be a

field return type.

benjie · 2022-06-28T11:05:44Z

spec/Section 5 -- Validation.md

@@ -446,7 +446,7 @@ SameResponseShape(fieldA, fieldB):
 - If {typeA} or {typeB} is Scalar or Enum:
  - If {typeA} and {typeB} are the same type return true, otherwise return
    false.
- Assert: {typeA} and {typeB} are both composite types.
+- Assert: {typeA} and {typeB} are both Object, Interface or Union.


This could be considered as (a is object and b is object) or (a is interface and b is interface) or (a is union and b is union). I think it's clearer without this change; alternatively use "each":

Suggested change

- Assert: {typeA} and {typeB} are both Object, Interface or Union.

- Assert: each of {typeA} and {typeB} are an Object, Interface or Union.

benjie · 2022-06-28T11:08:09Z

spec/Section 5 -- Validation.md

+A field subselection is not allowed on a _leaf field_, a field with a Scalar or
+Enum unwrapped type.


Use parenthesis to make it clear this isn't a list:

Suggested change

A field subselection is not allowed on a _leaf field_, a field with a Scalar or

Enum unwrapped type.

A field subselection is not allowed on a _leaf field_ (a field with a Scalar or

Enum unwrapped type).

benjie · 2022-06-28T11:14:52Z

spec/Section 5 -- Validation.md

-exists at least _one_ object type that exists in the intersection of the
-possible types of the scope and the spread, the spread is considered valid.
+In the scope of an _abstract type_ (interface or union), a fragment spread of
+another _abstract type_ can be used as long as there exists at least _one_


Emphasis unnecessary?

Suggested change

another _abstract type_ can be used as long as there exists at least _one_

another _abstract type_ can be used as long as there exists at least one

benjie · 2022-06-28T11:20:02Z

spec/Section 6 -- Execution.md

+When completing a field with an _abstract type_, that is an Interface or Union
+return type, first the abstract type must be resolved to a relevant Object type.


Alternative wording:

Suggested change

When completing a field with an _abstract type_, that is an Interface or Union

return type, first the abstract type must be resolved to a relevant Object type.

When completing a field whose return type is an _abstract type_ (an Interface or Union), first the abstract type must be resolved to a suitable Object type.

"a suitable object type" or "the relevant object type" I think?

Editorial: Type kinds

3b00fdb

This provides definitions at the introduction of "Type System" for _leaf type_, _composite type_, and _abstract type_. Then, these definitions are used throughout the spec.

leebyron requested a review from benjie June 27, 2022 19:05

rivantsov reviewed Jun 27, 2022

View reviewed changes

benjie requested changes Jun 28, 2022

View reviewed changes


		GraphQL supports two abstract types: interfaces and unions.
		:: A _composite type_ is a type composed of other types via a set of named

		:: A _leaf type_ is a kind of type representing a primitive value which cannot
		be further selected and thus form the leaves in a response tree. GraphQL

	Oftentimes, the possible responses for a scalar field are enumerable. GraphQL
	Oftentimes, the possible responses for a leaf field are enumerable. GraphQL

	GraphQL Objects are a _composite type_ representing a list of named fields, each
	GraphQL Objects are a _composite type_ comprised of a list of named fields, each

	- Assert: {typeA} and {typeB} are both Object, Interface or Union.
	- Assert: each of {typeA} and {typeB} are an Object, Interface or Union.

		A field subselection is not allowed on a _leaf field_, a field with a Scalar or
		Enum unwrapped type.

	another _abstract type_ can be used as long as there exists at least _one_
	another _abstract type_ can be used as long as there exists at least one

		When completing a field with an _abstract type_, that is an Interface or Union
		return type, first the abstract type must be resolved to a relevant Object type.

	When completing a field with an _abstract type_, that is an Interface or Union
	return type, first the abstract type must be resolved to a relevant Object type.
	When completing a field whose return type is an _abstract type_ (an Interface or Union), first the abstract type must be resolved to a suitable Object type.

Editorial: Type kinds #970

Are you sure you want to change the base?

Editorial: Type kinds #970

Uh oh!

Conversation

leebyron commented Jun 27, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Jun 27, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for graphql-spec-draft ready!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rivantsov Jun 28, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

leebyron commented Jun 27, 2022 •

edited

Loading

netlify bot commented Jun 27, 2022 •

edited

Loading

rivantsov Jun 28, 2022 •

edited

Loading