What makes a schema "be defined"?

[SimonSapin]

GraphQL has unfortunate name overloading. I will call:

• “A schema” is a collection of type system definitions, typically parsed from one or more TypeSystemExtensionDocument
• “A schema definition“ is the syntax element SchemaDefinition that starts with the schema keyword

Spec divination

SchemaExtension starts with the extend schema keywords and has validation rules:

Schema extensions have the potential to be invalid if incorrectly defined.

1. The Schema must already be defined.
2. […]

“Schema” in the first rule is capitalized but not a link. My interpretation of this rule is: a SchemaDefinition must exist.

Separately, Default Root Operation Type Names specifies:

While any type can be the root operation type for a GraphQL operation, the type system definition language can omit the schema definition when the query, mutation, and subscription root types are named "Query", "Mutation", and "Subscription" respectively.

Likewise, when representing a GraphQL schema using the type system definition language, a schema definition should be omitted if it only uses the default root operation type names.

Unfortunately this is written from the point of view of SDL authors (or authoring tools), and only suggests by implication what’s expected of tools reading SDL. My interpretation is: in the absence of a SchemaDefinition, root operations are defined based on which type Query {…}, type Mutation {…}, or type Subscription {…} are defined.

1.0 beta 1 behavior

Based on the above, I implemented apollo-compiler 1.0.0-beta.1 such that:

• Schema::schema_definition is an Option, set to Some if SchemaDefinition exists. It contains stuff from that SchemaDefinition and any SchemaExtension
• The Schema::root_operation method looks either at schema_definition if it’s Some, or at which object types exist if it’s None

Test case

type Query { field: Int }
extend schema @someDirective
directive @someDirective on SCHEMA

1.0.0-beta.1 records an error for extend schema without a schema definition, and sets Schema::schema_definition to None. The extension and its directive application are ignored.

Reportedly, the behavior of some other tools is that type Query creates a sort of implicit schema definition, which means that "the schema is defined" for the purpose of extend schema validation, so the extension and its directive application are accounted for.

What behavior do we want?

[SimonSapin]

We (apollo-rs team) discussed this and agreed that we should align with other implementations and make the test case above valid.

But what does this mean for the data structure? Should Schema::schema_definition no longer be an Option? I think another couple of test cases may help make this choice:

schema { query: MyQuery }
type MyQuery { … }
type Mutation { … }

schema { query: Query }
type Query { … }
type Mutation { … }

Which of these schemas have a mutation root operation? If neither, I think we need an Option to encode the difference between the second case and an implicit schema.

[SimonSapin]

According to graphql/graphql-spec#987 neither of the last two cases above have a mutation root operation. However I think we can still remove the Option by having a more specific heuristic in serialization.