Custom Scalar Specification URLs

core/src/main/scala-2/caliban/schema/SchemaDerivation.scala

@@ -124,7 +124,7 @@ trait SchemaDerivation[R] extends LowPriorityDerivedSchema {
         makeEnum(
           Some(getName(ctx)),
           getDescription(ctx),
-          subtypes.collect { case (__Type(_, Some(name), description, _, _, _, _, _, _, _, _), annotations) =>
+          subtypes.collect { case (__Type(_, Some(name), description, _, _, _, _, _, _, _, _, _), annotations) =>
             __EnumValue(
               name,
               description,

core/src/main/scala-3/caliban/schema/SchemaDerivation.scala

@@ -73,7 +73,7 @@ trait SchemaDerivation[A] {
               makeEnum(
                 Some(getName(annotations, info)),
                 getDescription(annotations),
-                subTypes.collect { case (name, __Type(_, _, description, _, _, _, _, _, _, _, _), annotations) =>
+                subTypes.collect { case (name, __Type(_, _, description, _, _, _, _, _, _, _, _, _), annotations) =>
                   __EnumValue(
                     name,
                     description,

core/src/main/scala/caliban/Rendering.scala

@@ -18,7 +18,10 @@ object Rendering {
           case __TypeKind.SCALAR   =>
             t.name.flatMap(name =>
               if (isBuiltinScalar(name)) None
-              else Some(s"""${renderDescription(t.description)}scalar $name""".stripMargin)
+              else
+                Some(
+                  s"""${renderDescription(t.description)}scalar $name${renderSpecifiedBy(t.specifiedBy)}""".stripMargin
+                )
             )
           case __TypeKind.NON_NULL => None
           case __TypeKind.LIST     => None
@@ -91,6 +94,11 @@ object Rendering {
     case Some(value)            => if (value.contains("\n")) s"""\"\"\"$value\"\"\" """ else s""""$value" """
   }
 
+  private def renderSpecifiedBy(specifiedBy: Option[String]): String = specifiedBy match {
+    case None      => ""
+    case Some(url) => s""" @specifiedBy(url: "$url")"""
+  }
+
   private def renderDirectiveArgument(value: InputValue): Option[String] = value match {
     case InputValue.ListValue(values)   =>
       Some(values.flatMap(renderDirectiveArgument).mkString("[", ",", "]"))

core/src/main/scala/caliban/introspection/Introspector.scala

@@ -30,6 +30,14 @@ object Introspector extends IntrospectionDerivation {
       ),
       Set(__DirectiveLocation.FIELD, __DirectiveLocation.FRAGMENT_SPREAD, __DirectiveLocation.INLINE_FRAGMENT),
       List(__InputValue("if", None, () => Types.makeNonNull(Types.boolean), None))
+    ),
+    __Directive(
+      "specifiedBy",
+      Some(
+        "The @specifiedBy directive is used within the type system definition language to provide a URL for specifying the behavior of custom scalar types. The URL should point to a human-readable specification of the data format, serialization, and coercion rules. It must not appear on built-in scalar types."
+      ),
+      Set(__DirectiveLocation.SCALAR),
+      List(__InputValue("url", None, () => Types.makeNonNull(Types.string), None))
     )
   )
 

core/src/main/scala/caliban/introspection/adt/__Type.scala

@@ -1,5 +1,6 @@
 package caliban.introspection.adt
 
+import caliban.Value.StringValue
 import caliban.parsing.adt.Definition.TypeSystemDefinition.TypeDefinition
 import caliban.parsing.adt.Definition.TypeSystemDefinition.TypeDefinition._
 import caliban.parsing.adt.Type.{ ListType, NamedType }
@@ -15,6 +16,7 @@ case class __Type(
   enumValues: __DeprecatedArgs => Option[List[__EnumValue]] = _ => None,
   inputFields: Option[List[__InputValue]] = None,
   ofType: Option[__Type] = None,
+  specifiedBy: Option[String] = None,
   directives: Option[List[Directive]] = None,
   origin: Option[String] = None
 ) {
@@ -28,6 +30,7 @@ case class __Type(
     args => (enumValues(args) ++ that.enumValues(args)).reduceOption(_ ++ _),
     (inputFields ++ that.inputFields).reduceOption(_ ++ _),
     (ofType ++ that.ofType).reduceOption(_ |+| _),
+    (specifiedBy ++ that.specifiedBy).reduceOption((_, b) => b),
     (directives ++ that.directives).reduceOption(_ ++ _),
     (origin ++ that.origin).reduceOption((_, b) => b)
   )
@@ -46,7 +49,17 @@ case class __Type(
   def toTypeDefinition: Option[TypeDefinition] =
     kind match {
       case __TypeKind.SCALAR       =>
-        Some(ScalarTypeDefinition(description, name.getOrElse(""), directives.getOrElse(Nil)))
+        Some(
+          ScalarTypeDefinition(
+            description,
+            name.getOrElse(""),
+            directives
+              .getOrElse(Nil) ++
+              specifiedBy
+                .map(url => Directive("specifiedBy", Map("url" -> StringValue(url)), directives.size))
+                .toList
+          )
+        )
       case __TypeKind.OBJECT       =>
         Some(
           ObjectTypeDefinition(

core/src/main/scala/caliban/schema/Schema.scala

@@ -123,11 +123,18 @@ trait GenericSchema[R] extends SchemaDerivation[R] with TemporalSchema {
    * Creates a scalar schema for a type `A`
    * @param name name of the scalar type
    * @param description description of the scalar type
+   * @param specifiedBy URL of the scalar specification
    * @param makeResponse function from `A` to [[ResponseValue]] that defines how to resolve `A`
    */
-  def scalarSchema[A](name: String, description: Option[String], makeResponse: A => ResponseValue): Schema[Any, A] =
+  def scalarSchema[A](
+    name: String,
+    description: Option[String],
+    specifiedBy: Option[String],
+    makeResponse: A => ResponseValue
+  ): Schema[Any, A] =
     new Schema[Any, A] {
-      override def toType(isInput: Boolean, isSubscription: Boolean): __Type = makeScalar(name, description)
+      override def toType(isInput: Boolean, isSubscription: Boolean): __Type =
+        makeScalar(name, description, specifiedBy)
       override def resolve(value: A): Step[Any]                              = PureStep(makeResponse(value))
     }
 
@@ -239,18 +246,18 @@ trait GenericSchema[R] extends SchemaDerivation[R] with TemporalSchema {
       directives
     )
 
-  implicit val unitSchema: Schema[Any, Unit]             = scalarSchema("Unit", None, _ => ObjectValue(Nil))
-  implicit val booleanSchema: Schema[Any, Boolean]       = scalarSchema("Boolean", None, BooleanValue.apply)
-  implicit val stringSchema: Schema[Any, String]         = scalarSchema("String", None, StringValue.apply)
-  implicit val uuidSchema: Schema[Any, UUID]             = scalarSchema("ID", None, uuid => StringValue(uuid.toString))
-  implicit val shortSchema: Schema[Any, Short]           = scalarSchema("Short", None, IntValue(_))
-  implicit val intSchema: Schema[Any, Int]               = scalarSchema("Int", None, IntValue(_))
-  implicit val longSchema: Schema[Any, Long]             = scalarSchema("Long", None, IntValue(_))
-  implicit val bigIntSchema: Schema[Any, BigInt]         = scalarSchema("BigInt", None, IntValue(_))
-  implicit val doubleSchema: Schema[Any, Double]         = scalarSchema("Float", None, FloatValue(_))
-  implicit val floatSchema: Schema[Any, Float]           = scalarSchema("Float", None, FloatValue(_))
-  implicit val bigDecimalSchema: Schema[Any, BigDecimal] = scalarSchema("BigDecimal", None, FloatValue(_))
-  implicit val uploadSchema: Schema[Any, Upload]         = scalarSchema("Upload", None, _ => StringValue("<upload>"))
+  implicit val unitSchema: Schema[Any, Unit]             = scalarSchema("Unit", None, None, _ => ObjectValue(Nil))
+  implicit val booleanSchema: Schema[Any, Boolean]       = scalarSchema("Boolean", None, None, BooleanValue.apply)
+  implicit val stringSchema: Schema[Any, String]         = scalarSchema("String", None, None, StringValue.apply)
+  implicit val uuidSchema: Schema[Any, UUID]             = scalarSchema("ID", None, None, uuid => StringValue(uuid.toString))
+  implicit val shortSchema: Schema[Any, Short]           = scalarSchema("Short", None, None, IntValue(_))
+  implicit val intSchema: Schema[Any, Int]               = scalarSchema("Int", None, None, IntValue(_))
+  implicit val longSchema: Schema[Any, Long]             = scalarSchema("Long", None, None, IntValue(_))
+  implicit val bigIntSchema: Schema[Any, BigInt]         = scalarSchema("BigInt", None, None, IntValue(_))
+  implicit val doubleSchema: Schema[Any, Double]         = scalarSchema("Float", None, None, FloatValue(_))
+  implicit val floatSchema: Schema[Any, Float]           = scalarSchema("Float", None, None, FloatValue(_))
+  implicit val bigDecimalSchema: Schema[Any, BigDecimal] = scalarSchema("BigDecimal", None, None, FloatValue(_))
+  implicit val uploadSchema: Schema[Any, Upload]         = scalarSchema("Upload", None, None, _ => StringValue("<upload>"))
 
   implicit def optionSchema[R0, A](implicit ev: Schema[R0, A]): Schema[R0, Option[A]]                                  = new Schema[R0, Option[A]] {
     override def optional: Boolean                                         = true

core/src/main/scala/caliban/schema/Types.scala

@@ -10,8 +10,8 @@ object Types {
   /**
    * Creates a new scalar type with the given name.
    */
-  def makeScalar(name: String, description: Option[String] = None): __Type =
-    __Type(__TypeKind.SCALAR, Some(name), description)
+  def makeScalar(name: String, description: Option[String] = None, specifiedBy: Option[String] = None): __Type =
+    __Type(__TypeKind.SCALAR, Some(name), description, specifiedBy = specifiedBy)
 
   val boolean: __Type = makeScalar("Boolean")
   val string: __Type  = makeScalar("String")

core/src/main/scala/caliban/validation/FragmentValidator.scala

@@ -95,7 +95,7 @@ object FragmentValidator {
 
           fields.foreach {
             case field @ SelectedField(
-                  __Type(_, Some(name), _, _, _, _, _, _, _, _, _),
+                  __Type(_, Some(name), _, _, _, _, _, _, _, _, _, _),
                   _,
                   _
                 ) if isConcrete(field.parentType) =>

core/src/test/scala/caliban/RenderingSpec.scala

@@ -17,7 +17,7 @@ object RenderingSpec extends DefaultRunnableSpec {
                     |}
                     |
                     |"Description of custom scalar emphasizing proper captain ship names"
-                    |scalar CaptainShipName
+                    |scalar CaptainShipName @specifiedBy(url: "http://someUrl")
                     |
                     |union Role = Captain | Engineer | Mechanic | Pilot
                     |

core/src/test/scala/caliban/TestUtils.scala

@@ -40,6 +40,7 @@ object TestUtils {
     implicit val captainShipNameSchema: Schema[Any, CaptainShipName] = scalarSchema(
       "CaptainShipName",
       Some("Description of custom scalar emphasizing proper captain ship names"),
+      Some("http://someUrl"),
       name => StringValue(name.value)
     )
   }