subschema composability rules #37

yaacovCR · 2022-07-17T16:08:32Z

Comments welcome!

This is just an initial version, and has much room for improvement.

JohnStarich

@yaacovCR This is great. 👏 I've also been thinking about mergability and a common merging spec as a primary concern.

I've added some of my riffs as suggestions to your riffs 🙂

rfcs/SubschemaComposability.md

WIP See: graphql#35

to drop the number of used terms/simply, we can just use type composition

1. separate composability rules by execution strategy. I am not sure if these should be separate in the final document, but separating helps me reason about them better within this draft stage. 2. remove discussion of runtime translation from composability rules thats basically mixing the idea of "transforms" with composability. For example, if there is a way of translating a missing enum value for a given subschema into an enum value that is present, we are basically transforming that subschema into a subschema that has the missing enum value by using a transformRequest method Instead, let's make the composability rules strict and discuss separately the idea of transforms

yaacovCR · 2022-08-08T18:11:16Z

I have marked this PR as no longer DRAFT, as I have added section regarding all types. But it would certainly benefit from additional input and further revision. Comments are welcome.

JohnStarich

I had some more thoughts on "what does it mean to be composable?". This feels like it could be a whole separate topic, so I'm happy to move this to a discussion too.

rfcs/SubschemaComposability.md

obi1kenobi · 2022-08-15T17:58:02Z

This is a great doc! I don't find the GitHub PR interface great for reviewing Markdown, so I wrote up a few thoughts in the discussion thread:
#35 (comment)

benjie · 2022-08-16T10:03:00Z

Minor markdown styling comment: please use

`backticksForCode`

and

*italics for references*

i.e. change

`Subschemas as remote GraphQL services`

to

*Subschemas as remote GraphQL services*

This follows the pattern used by spec-md.

rfcs/SubschemaComposability.md

@michaelstaib

Thanks @michaelstaib Co-authored-by: Michael Staib <[email protected]>

@michaelstaib

Thanks @michaelstaib Co-authored-by: Michael Staib <[email protected]>

yaacovCR · 2022-08-18T19:15:24Z

This follows the pattern used by spec-md.

@benjie any styling for definitions like for “composability” ?

benjie · 2022-08-20T16:43:01Z

@yaacovCR Indeed; if you're actually using spec-md then the paragraph that defines a term should start with :: and the term should be the first italicised term. Then references to it should use italics. Here's an example of request being defined in the spec:

https://github.com/graphql/graphql-spec/pull/949/files

benjie

Should we go ahead and merge this since it's an RFC doc?

benjie · 2022-09-08T08:09:50Z

rfcs/SubschemaComposability.md

+subschemas. This set of subschemas is then considered to be `composable`.
+Inversely, it may be impossible to generate a valid composite schema containing
+all of the GraphQL elements of a given set of subschemas; this set of subschemas
+is considered `not composable`.


Mathematically speaking, isn't it always possible to generate a composite schema from any two schemas A and B that implement the same version of the GraphQL spec and whose root types don't implement any interfaces by renaming every non-standard non-root type and directive in them, prefixing the names of all the fields on the root types with the name of the schema when adding them to the composite schema's root types, and replacing references to the root types in the sub-schemas with the respective composite schema's root types? Sure this becomes A + B rather than A & B - i.e. each field is resolved by exactly one subschema - but that's not really at odds with this paragraph?

I think the wording here needs to be more crisp... not sure how exactly - perhaps refer to the overlapping elements somehow?

benjie · 2022-09-08T08:17:45Z

rfcs/SubschemaComposability.md

+ composite schema will yield request(s) against spec-compliant (or even
+ non-spec compliant) GraphQL subservices that are then merged into a single
+ request.


The term "GraphQL" implies it's spec compliant. If they're not spec compliant then they're not GraphQL.

Also do you mean "result" rather than "request" here?

Suggested change

composite schema will yield request(s) against spec-compliant (or even

non-spec compliant) GraphQL subservices that are then merged into a single

request.

composite schema will yield request(s) against GraphQL subservices that

are then merged into a single result.

benjie · 2022-09-08T08:20:07Z

rfcs/SubschemaComposability.md

+ "build-time" composition, a single service executes the composite schema
+ without delegation to remote services tied to each subschema. Subschemas
+ exist for the purpose of code organization, but only the composite schema
+ exists at the time of execution.


Suggested change

exists at the time of execution.

exists at the time of execution.

3. `Hybrid execution`: a combination of the above approaches.

benjie · 2022-09-08T08:32:21Z

rfcs/SubschemaComposability.md

+The below RFC examines composability separately for the above two forms of
+composite schema execution.


If you accept my Hybrid suggestion above, this will need adjusting.

benjie · 2022-09-08T08:36:30Z

rfcs/SubschemaComposability.md

+example, if a request against the composite schema must ultimately be translated
+to request(s) against the still extant source subschemas, then the composition
+must be -- in some sense -- reversed during execution, which is not always
+possible, and introduces significant complexity.


Under what circumstances would it be something that we'd do and yet it wouldnot be possible to reverse?

Suggested change

example, if a request against the composite schema must ultimately be translated

to request(s) against the still extant source subschemas, then the composition

must be -- in some sense -- reversed during execution, which is not always

possible, and introduces significant complexity.

example, if a request against the composite schema must ultimately be translated

to request(s) against the still extant source subschemas, then the composition

must be -- in some sense -- reversed during execution, which introduces

complexity.

benjie · 2022-09-08T08:48:21Z

rfcs/SubschemaComposability.md

+to different types in the composite schema. Or, when metadata denotes types as
+overlapping in the first instance, namespacing may be accomplished simply by
+adjusting the existing metadata or via additional metadata. Finally, a new
+namespace construct may be introduced into the GraphQL specification itself such


Suggested change

namespace construct may be introduced into the GraphQL specification itself such

namespace construct might be introduced into the GraphQL specification itself such

benjie · 2022-09-08T08:58:11Z

rfcs/SubschemaComposability.md

+1. Overlapping enum types where the types define identical sets of values can
+ always be composed, as they are identical in all subschemas.


A risk of this, however, is if you compose them as equivalent but it turns out they have different meanings and they later wish to diverge. For example:

enum Can { DUCK }

might evolve in one schema (capabilities) to enum Can { DUCK RUN } 🏃 or in another (canned goods) to enum Can { DUCK BEANS } 🥫

benjie · 2022-09-08T09:00:11Z

rfcs/SubschemaComposability.md

+2. Subschemas with overlapping enum types where the disparate types define
+ different value sets are only sometimes composable.


Suggested change

2. Subschemas with overlapping enum types where the disparate types define

different value sets are only sometimes composable.

2. Subschemas with overlapping enum types where the disparate types define

different value sets are sometimes composable.

benjie · 2022-09-08T09:15:33Z

rfcs/SubschemaComposability.md

+1. Overlapping interface types cannot be composed if any overlapping fields
+ cannot be composed, see below.


May need a comment on the interfaces that the interface implements.

benjie · 2022-09-08T09:15:57Z

rfcs/SubschemaComposability.md

+1. Overlapping object types cannot be composed if any overlapping fields cannot
+ be composed, see below.


Needs a comment on the interfaces the object type implements too.

JohnStarich · 2024-01-18T17:16:26Z

During our call today we outlined where we're going, and sounds like composability rules are on the horizon again.

@michaelstaib @martijnwalraven We could use Yaacov's PR here as a discussion starter.

JohnStarich reviewed Aug 1, 2022

View reviewed changes

rfcs/SubschemaComposability.md Outdated Show resolved Hide resolved

rfcs/SubschemaComposability.md Outdated Show resolved Hide resolved

yaacovCR commented Aug 2, 2022

View reviewed changes

rfcs/SubschemaComposability.md Outdated Show resolved Hide resolved

yaacovCR added 6 commits August 5, 2022 06:50

initial Subschema Composability riffs

3855956

WIP See: graphql#35

language edits

10ecf16

use merging for types more consistently rather than composing

20f4345

remove references to partial composability

f3423fd

Add case where enum types contain equivalent value sets

c3edd84

add some initial thoughts about input objects and fields

9995117

yaacovCR force-pushed the schema-composability branch from ea371d8 to 9995117 Compare August 5, 2022 03:50

yaacovCR added 7 commits August 5, 2022 07:14

remove use of term "type merging"

97c795a

to drop the number of used terms/simply, we can just use type composition

standardize

2f99a74

Add objects, interfaces, unions

3ee86b5

switch order vis a vis execution strategies

34e0064

prettier

44cd0c5

unify

958becd

yaacovCR marked this pull request as ready for review August 8, 2022 18:10

yaacovCR changed the title ~~initial Subschema Composability riffs~~ subschema composability rules Aug 8, 2022

JohnStarich reviewed Aug 10, 2022

View reviewed changes

rfcs/SubschemaComposability.md Show resolved Hide resolved

rfcs/SubschemaComposability.md Show resolved Hide resolved

michaelstaib reviewed Aug 18, 2022

View reviewed changes

rfcs/SubschemaComposability.md Outdated Show resolved Hide resolved

michaelstaib reviewed Aug 18, 2022

View reviewed changes

rfcs/SubschemaComposability.md Outdated Show resolved Hide resolved

yaacovCR and others added 2 commits August 18, 2022 15:13

Feedback

0ad6fd3

Thanks @michaelstaib Co-authored-by: Michael Staib <[email protected]>

Feedback

71c9b2a

Thanks @michaelstaib Co-authored-by: Michael Staib <[email protected]>

benjie mentioned this pull request Aug 18, 2022

[2022-08-17] EVERYONE: please review Schema Composibility Rules #67

Closed

benjie requested changes Sep 8, 2022

View reviewed changes

michaelstaib force-pushed the main branch 2 times, most recently from 5aab83d to a48b466 Compare January 11, 2024 13:17

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

subschema composability rules #37

subschema composability rules #37

yaacovCR commented Jul 17, 2022 •

edited

JohnStarich left a comment

yaacovCR commented Aug 8, 2022

JohnStarich left a comment

obi1kenobi commented Aug 15, 2022

benjie commented Aug 16, 2022

yaacovCR commented Aug 18, 2022

benjie commented Aug 20, 2022

benjie left a comment

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

benjie Sep 8, 2022

JohnStarich commented Jan 18, 2024

	exists at the time of execution.
	exists at the time of execution.
	3. `Hybrid execution`: a combination of the above approaches.

		The below RFC examines composability separately for the above two forms of
		composite schema execution.

	namespace construct may be introduced into the GraphQL specification itself such
	namespace construct might be introduced into the GraphQL specification itself such

		1. Overlapping enum types where the types define identical sets of values can
		always be composed, as they are identical in all subschemas.

		2. Subschemas with overlapping enum types where the disparate types define
		different value sets are only sometimes composable.

		1. Overlapping interface types cannot be composed if any overlapping fields
		cannot be composed, see below.

		1. Overlapping object types cannot be composed if any overlapping fields cannot
		be composed, see below.

subschema composability rules #37

Are you sure you want to change the base?

subschema composability rules #37

Conversation

yaacovCR commented Jul 17, 2022 • edited

JohnStarich left a comment

Choose a reason for hiding this comment

yaacovCR commented Aug 8, 2022

JohnStarich left a comment

Choose a reason for hiding this comment

obi1kenobi commented Aug 15, 2022

benjie commented Aug 16, 2022

yaacovCR commented Aug 18, 2022

benjie commented Aug 20, 2022

benjie left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JohnStarich commented Jan 18, 2024

yaacovCR commented Jul 17, 2022 •

edited