Remove withBuiltInDefinitions() and add flag to dump scalar definitions in SDL (#6389)

* Remove `withBuiltInDefinitions()` and add flag to dump scalar definitions in SDL

* add changelog entry

* oops, I forgot to actually write the file

Author: martinbonnin

CHANGELOG.md

@@ -1,6 +1,10 @@
 Change Log
 ==========
 
+# Next version
+
+* Downloading or converting a SDL schema from introspection now includes scalar definitions. This is required for clients to get a [full view of the schema](https://github.com/graphql/graphql-wg/blob/main/rfcs/FullSchemas.md). 
+
 # Version 4.1.1
 
 _2025-01-24_

libraries/apollo-annotations/src/commonMain/kotlin/com/apollographql/apollo/annotations/ApolloDeprecatedSince.kt

@@ -33,5 +33,6 @@ annotation class ApolloDeprecatedSince(val version: Version) {
     v4_0_0,
     v4_0_1,
     v4_0_2,
+    v4_1_2,
   }
 }

libraries/apollo-ast/src/commonMain/kotlin/com/apollographql/apollo/ast/Schema.kt

@@ -131,7 +131,7 @@ class Schema internal constructor(
   @ApolloInternal
   fun toMap(): Map<String, Any> {
     return mapOf(
-        "sdl" to GQLDocument(definitions, sourceLocation = null).toSDL(),
+        "sdl" to GQLDocument(definitions, sourceLocation = null).toSDL(indent = "", includeBuiltInScalarDefinitions = true),
         "keyFields" to keyFields.mapValues { it.value.toList().sorted() },
         "foreignNames" to foreignNames,
         "directivesToStrip" to directivesToStrip,
@@ -233,7 +233,7 @@ class Schema internal constructor(
     @ApolloInternal
     fun fromMap(map: Map<String, Any>): Schema {
       return Schema(
-          definitions = combineDefinitions((map["sdl"] as String).parseAsGQLDocument().getOrThrow().definitions, builtinDefinitions(), ConflictResolution.TakeLeft),
+          definitions = (map["sdl"] as String).parseAsGQLDocument().getOrThrow().definitions,
           keyFields = (map["keyFields"]!! as Map<String, Collection<String>>).mapValues { it.value.toSet() },
           foreignNames = map["foreignNames"]!! as Map<String, String>,
           directivesToStrip = map["directivesToStrip"]!! as List<String>,

libraries/apollo-ast/src/commonMain/kotlin/com/apollographql/apollo/ast/gqldocument.kt

@@ -22,6 +22,8 @@ import okio.Buffer
  * Scalars: https://spec.graphql.org/draft/#sel-GAHXJHABAB_D4G
  * Directives: https://spec.graphql.org/draft/#sel-FAHnBPLCAACCcooU
  */
+@Deprecated("use toFullSchemaGQLDocument instead", ReplaceWith("toFullSchemaGQLDocument()"))
+@ApolloDeprecatedSince(ApolloDeprecatedSince.Version.v4_1_2)
 fun GQLDocument.withBuiltinDefinitions(): GQLDocument {
   return withDefinitions(builtinDefinitions())
 }
@@ -201,22 +203,18 @@ private fun GQLDocument.withDefinitions(definitions: List<GQLDefinition>): GQLDo
  * See https://spec.graphql.org/draft/#sel-GAHXJHABAB_D4G
  */
 @ApolloExperimental
-fun GQLDocument.toSDL(indent: String = "  "): String {
+fun GQLDocument.toSDL(indent: String = "  ", includeBuiltInScalarDefinitions: Boolean = false): String {
   val buffer = Buffer()
   val writer = SDLWriter(buffer, indent)
 
   definitions.forEachIndexed { index, definition ->
     when {
-      definition is GQLScalarTypeDefinition && definition.name in GQLTypeDefinition.builtInTypes -> {
+      definition is GQLScalarTypeDefinition
+          && definition.name in GQLTypeDefinition.builtInTypes
+          && !includeBuiltInScalarDefinitions -> {
         // Always skip scalar definitions, it's a must in the spec
         return@forEachIndexed
       }
-
-      definition is GQLTypeDefinition && definition.name in GQLTypeDefinition.builtInTypes ||
-          definition is GQLDirectiveDefinition && definition.name in GQLDirectiveDefinition.builtInDirectives -> {
-        writer.write(definition)
-      }
-
       else -> {
         writer.write(definition)
       }
@@ -227,3 +225,8 @@ fun GQLDocument.toSDL(indent: String = "  "): String {
   }
   return buffer.readUtf8()
 }
+
+@ApolloExperimental
+@ApolloDeprecatedSince(ApolloDeprecatedSince.Version.v4_1_2)
+@Deprecated("This is only kept for backward compatibility reasons. Use the overload instead.", level = DeprecationLevel.HIDDEN)
+fun GQLDocument.toSDL(indent: String = "  ") = toSDL(indent, false)

libraries/apollo-ast/src/jvmTest/kotlin/com/apollographql/apollo/graphql/ast/test/SDLWriterTest.kt

@@ -1,6 +1,7 @@
 package com.apollographql.apollo.graphql.ast.test
 
 import com.apollographql.apollo.ast.parseAsGQLDocument
+import com.apollographql.apollo.ast.toFullSchemaGQLDocument
 import com.apollographql.apollo.ast.toGQLDocument
 import com.apollographql.apollo.ast.toSDL
 import com.apollographql.apollo.ast.withBuiltinDefinitions
@@ -18,15 +19,6 @@ class SDLWriterTest {
     }
   }
 
-  @Test
-  fun typeRedefinitionInspectionIsIgnored() {
-    val sdlSchema = File("${CWD}/test-fixtures/sdl/type_redefinitions.graphqls")
-
-    checkExpected(sdlSchema) {
-      it.parseAsGQLDocument().getOrThrow().withBuiltinDefinitions().toSDL("    ")
-    }
-  }
-
   @Test
   fun introspectionSchema() {
     val jsonSchema = File("${CWD}/test-fixtures/sdl/introspection.json")

libraries/apollo-ast/test-fixtures/sdl/type_redefinitions.expected

@@ -5,6 +5,7 @@ import com.apollographql.apollo.ast.introspection.toIntrospectionSchema
 import com.apollographql.apollo.ast.introspection.writeTo
 import com.apollographql.apollo.ast.toFullSchemaGQLDocument
 import com.apollographql.apollo.ast.toGQLDocument
+import com.apollographql.apollo.ast.toSDL
 import com.apollographql.apollo.ast.toUtf8
 import org.gradle.api.DefaultTask
 import org.gradle.api.provider.Property
@@ -46,7 +47,9 @@ abstract class ApolloConvertSchemaTask : DefaultTask() {
     }
 
     if (from.isIntrospection()) {
-      from.toIntrospectionSchema().toGQLDocument().toUtf8(to)
+      from.toIntrospectionSchema().toGQLDocument().toSDL(includeBuiltInScalarDefinitions = true).let {
+        to.writeText(it)
+      }
     } else {
       from.toGQLDocument().toFullSchemaGQLDocument().toIntrospectionSchema().writeTo(to)
     }

libraries/apollo-ast/test-fixtures/sdl/type_redefinitions.graphqls

@@ -127,7 +127,7 @@ object SchemaDownloader {
       if (sdlSchema == null) {
         check(introspectionSchema != null)
         // Convert from JSON to SDL
-        schema.writeText(introspectionSchema.toGQLDocument().toSDL(indent = "  "))
+        schema.writeText(introspectionSchema.toGQLDocument().toSDL(indent = "  ", includeBuiltInScalarDefinitions = true))
       } else {
         // Copy SDL verbatim
         schema.writeText(sdlSchema)