Composability of schemas

[obi1kenobi]

Opening this discussion so @yaacovCR, I, and anyone else interested can fill it in.

Will write more in a bit as a I try to collect my thoughts and produce something more tightly edited than just a big wall of text :)

[yaacovCR]

I started riffing in #37, feel free to add suggestions/edits there or discuss here or both, as it feels best. :) @obi1kenobi , thanks for getting this discussion going!

[obi1kenobi]

I've been following the work in #37, and I have to commend @yaacovCR for the high quality of the document 💯

Here are my notes on things I'm interested in discussing.

Overlapping enum types with different values

In my opinion, it's also quite possible that different enum values in single-service composite schemas may be due to a bug, rather than an intentional choice. This is especially true for enum values used as inputs.

In the interest of choosing a good tradeoff between spec completeness and simplicity, I'd be in favor of saying "overlapping enum types used as inputs must match exactly to make the schemas composable." Otherwise, I worry about the risk of providing a complete spec that is unimplementable in practice due to overwhelming complexity.

I could also be convinced to disallow composition of enums with different values altogether, regardless of input/output use or manner of execution.

Default values for input object fields

Two questions and one comment here.

If composing a field with a default value with a matching field without a default value, is the resulting field required to specify a default in the composed schema? And is that default required to match the default of the underlying field that had a default?

Perhaps it would be good to specify that default values can be unset or overridden by composition metadata, subject to waves hands making the types/nullability work out. I'm intentionally hand-waving away the specific rule so we don't get hung up on defining what it is before deciding if this piece of metadata is worth it or not.

Addition of schema entities as part of composition

During composition, it's also sometimes useful to add entities that are only valid in the scope of the composed schema, and are not valid in any of the subschemas individually. For example:

• adding fields representing edges from one schema's type to another
• marking object types in one schema as implementing interfaces from another
• adding types or perhaps even directives that reference components of multiple subschemas

There are multiple ways of going about this, and it's not immediately clear to me that one of the approaches dominates all others in all use cases. This is something I'd be interested in discussing in more detail.

Treatment of __typename with type renaming / namespacing

What happens when a query asks for the __typename field on a type that has been renamed as part of schema composition?

[JohnStarich]

In the interest of choosing a good tradeoff between spec completeness and simplicity, I'd be in favor of saying "overlapping enum types used as inputs must match exactly to make the schemas composable."

One issue that comes up when "enums must match" is in the composition timing for "dynamic" or "runtime". Enforcing "enums must match" may be more correct, but it also means the composite schema cannot be merged unless all downstream subschema enums are perfectly aligned. As a consequence, the downstream subschemas are already using schemas with incompatible enums but the composite schema cannot be updated. This means query results could contain new enum values not present in the composite.

Maybe this is as simple as "don't have enums in more than one subschema" but this is hard to achieve when each subschema tries to be valid independently.

If composing a field with a default value with a matching field without a default value, is the resulting field required to specify a default in the composed schema? And is that default required to match the default of the underlying field that had a default?

The default value might be something we can let the composer decide. In some cases, I've seen some implementations "arbitrarily choose the first one" where the order of schema merges is deterministic.

So merging this 1st subschema

type Query {
    foo(bar: String = "baz")
}

with this as the 2nd subschema

type Query {
    foo(bar: String = "biff")
}

would result in this:

type Query {
    foo(bar: String = "baz")
}

But if I had deterministically ordered them in reverse (perhaps by using their remote schema endpoint URL), then it would like this:

type Query {
    foo(bar: String = "baz")
}

Thoughts?

During composition, it's also sometimes useful to add entities that are only valid in the scope of the composed schema, and are not valid in any of the subschemas individually.

This is interesting to me, though I lack experience here. I'd be interested in others thoughts as well. Can the composer insert its own subschema into the pool of schemas it merges together?