Transformations vs Composition

[yaacovCR]

One general question is whether schema transformation is within the scope of schema composition. It would certainly be easier to leave as much out of the scope as possible, but two types of schema transformations happen to be very useful for composition. I imagine we will want to include them within the scope, I am just calling them out because if we do want to leave space for a future transformation sub-specification, we might want to think about how these transformations fit into that broader context. Apologies is this is a bit rough around the edges or too elementary or plain wrong. :)

Argument Filtering between the public composite schema and the merged schema

Imagine a subchema A that specified some of SomeType as follows:

type SomeType {
  someField(someValue: Int): String
}

Now imagine another subschema B that specified some of SomeType as follows:

type SomeType {
  someValue: Int
}

If the composite schema will end up having the following portion of Query:

type Query {
  someObject: SomeType
}

and imagine against that the composite schema is

query {
  someObject {
    someValue: Int
    someField: String
  }
}

the executior would presumably reach to Subschema B for someValue and then access SubschemaA for someField using someValue.

It might be undesirable to expose the composite schema as

type SomeType {
  someValue: Int
  someField(someValue: Int): String
}

Field filtering

Each subschema if it operates without an entities accessor needs to provide accessors for all of the entities. It may be desirable to filter these from the public composite schema.

[smyrick]

I fully agree that connecting fields to args is something that users want to do often. Pretending that this concept is useful for all of GraphQL this is how I imagine some spec/directives would operation on one singular schema (which can be viewed as the result we get from composition or a traditional schema)

type SomeType {
    someValue: Int
    someField(someArg: Int): String @sourceArgValueFrom(argMaping: { "someArg": "{  someValue }" })
}

Where @sourceArgValueFrom allows you to pass a map of arg names to fields on where to get their value. Then we need some transform step that takes in this schema and produces a new one with the mapping built in or hidden somehow with directives

What clients want to see:

type SomeType {
    someValue: Int
    # Clients can now query without passing an arg
    # Metadata saved internally or in directives or old fields hidden with @internal 
    someField: String  @sourceArgValueFrom(argMaping: { "someArg": "{  someValue }" })
}

---

Now when it comes to composition across graphs I don't see any issue with supporting that logic as we can view this as a custom directive with composition. If you want to apply custom transformation that can happen after the composition step as compostion doesn't need to value your custom directives (ie it's not an issue that in Subschema B we reference a non-existant field when viewed from before composition)

# Subschema A
type SomeType {
    someValue: Int
}

# Subschema B
type SomeType {
    someField(someArg: Int): String @sourceArgValueFrom(argMaping: { "someArg": "{  someValue }" })
}

After composition we should still get the same merged schema:

# Composed schema
type SomeType {
   someValue: Int
    someField(someArg: Int): String @sourceArgValueFrom(argMaping: { "someArg": "{  someValue }" })
}

And then you can pass the above merged schema to your transformer library just like normal. This doesn't require the composer to know anything about these directives or validate them if those steps happen either before or after. It would be up to implementations to provide these exhaustive checks on their platform if you want to support all those features.

What would be an example where the composer needs to do something as part of merging?

[smyrick]

Follow up, how Apollo Federation handles subgraphs indicating today that they are referencing a field that they actually can't resolve is with the @external directive.

This concept could also be extended to arguments if we wanted to include that as part of composition

# Subschema B
type SomeType {
    someField(someArg: Int @external): String @sourceArgValueFrom(argMaping: { "someArg": "{  someValue }" })
}

[yaacovCR]

I don't believe we are in disagreement. You point out that we need a transformation step that in your final example removes the "external" @someArg argument. I am essentially pointing out the exact same thing, see graphql/composite-schemas-spec#20 which you have commented on.

The key point that I am bringing up is just in terms of scope; we cannot wholly say that schema transformation is out of scope for the the composition subgroup, (although it is not necessarily within the "merging" step of composition, in that the solution space of composition will encroach on the problem space of transformation.

I think for now directive based solution for filtering, something like @external (although I am not sure that is the best name, perhaps @internal or @private would make more sense), is fine. I just think we should explicitly point out that we are utilizing schema transformations (i.e. filtering) so that if/when GraphQL ever gets a transformation working group and a generic transformation nomenclature, we should be prepared to transition to that. The composition spec should be comfortable using the term transformation when it is appropriate, even though that's not the problem we are aimed at solving.

Another option, which I think I could see myself favoring, is to just drop the "filtering" step entirely, i.e. these fields could just be marked with metadata or directives (like deprecated marks fields), and leave it to implementations to decide whether to expose these or not. I think that's a very reasonable approach.

[smyrick]

Correct, I agree with all your points. Maybe to directly answer your question:

One general question is whether schema transformation is within the scope of schema composition?

I think the answer should be no. It could be worth calling out in this spec that we aim to identify what the merging/composing process looks like, which may involve having a field or type look slightly different in the resulting composed schema as compared to how it is defined in a single subschema. However, we do not want to create a general GraphQL transformation framework and we will leave that up to other WGs or tools that can be applied either before or after composition.