Introduce FieldDefinition

This is intended to associate a definition to a field name, allowing to
include the latter in error messages

Author: Andrea Fiore

README.md

@@ -286,7 +286,7 @@ groups into a single Swagger API description.
 
 ``` {.scala}
 scala> PathGroup.aggregate(apiInfo, List(PetsRoute, DinosRoute))
-res13: cats.data.ValidatedNel[com.timeout.docless.swagger.SchemaError,com.timeout.docless.swagger.APISchema] = Invalid(NonEmptyList(MissingDefinition(RefWithContext(TypeRef(Dino),ResponseContext(Get,/dinos/{id})))))
+res13: cats.data.ValidatedNel[com.timeout.docless.swagger.SchemaError,com.timeout.docless.swagger.APISchema] = Invalid(NonEmptyList(MissingDefinition(RefWithContext(TypeRef(Dino,None),ResponseContext(Get,/dinos/{id})))))
 ```
 
 The `aggregate` method will also verify that the schema definitions

src/main/scala/com/timeout/docless/encoders/Swagger.scala

@@ -75,14 +75,14 @@ object Swagger {
   }
 
   implicit val schemaRefEnc = Encoder.instance[JsonSchema.Ref] {
-    case ArrayRef(id) =>
+    case ArrayRef(id, _) =>
       Json.obj(
         "type" -> Json.fromString("array"),
         "items" -> Json.obj(
           "$ref" -> Json.fromString(s"#/definitions/$id")
         )
       )
-    case TypeRef(id) =>
+    case TypeRef(id, _) =>
       Json.obj("$ref" -> Json.fromString(s"#/definitions/$id"))
   }
 

src/main/scala/com/timeout/docless/schema/JsonSchema.scala

@@ -1,5 +1,6 @@
 package com.timeout.docless.schema
 
+import com.timeout.docless.schema.JsonSchema.NamedDefinition
 import com.timeout.docless.swagger.Responses.Response
 import io.circe._
 import io.circe.syntax._
@@ -19,6 +20,9 @@ trait JsonSchema[A] extends JsonSchema.HasRef {
 
   def relatedDefinitions: Set[JsonSchema.Definition]
 
+  def fieldDefinitions: Set[JsonSchema.NamedDefinition] =
+    relatedDefinitions.collect { case d: NamedDefinition => d }
+
   def jsonObject: JsonObject
 
   def asJson: Json = jsonObject.asJson
@@ -30,8 +34,16 @@ trait JsonSchema[A] extends JsonSchema.HasRef {
 
   def asJsonRef: Json = asObjectRef.asJson
 
-  lazy val definition: JsonSchema.Definition =
-    JsonSchema.Definition(id, relatedDefinitions.map(_.asRef), asJson)
+  def namedDefinition(fieldName: String): NamedDefinition =
+    JsonSchema.NamedDefinition(
+      id,
+      fieldName,
+      relatedDefinitions.map(_.asRef),
+      asJson
+    )
+
+  lazy val definition: JsonSchema.UnnamedDefinition =
+    JsonSchema.UnnamedDefinition(id, relatedDefinitions.map(_.asRef), asJson)
 
   def definitions: Set[JsonSchema.Definition] =
     relatedDefinitions + definition
@@ -49,27 +61,43 @@ object JsonSchema
     with derive.CoprodInstances {
   trait HasRef {
     def id: String
-    def asRef: Ref      = TypeRef(id)
-    def asArrayRef: Ref = ArrayRef(id)
+    def asRef: Ref      = TypeRef(id, None)
+    def asArrayRef: Ref = ArrayRef(id, None)
   }
 
-  case class Definition(id: String, relatedRefs: Set[Ref], json: Json)
-      extends HasRef
+  sealed trait Definition extends HasRef {
+    def id: String
+    def json: Json
+    def relatedRefs: Set[Ref]
+  }
+
+  case class UnnamedDefinition(id: String, relatedRefs: Set[Ref], json: Json)
+      extends Definition
+
+  case class NamedDefinition(id: String,
+                             fieldName: String,
+                             relatedRefs: Set[Ref],
+                             json: Json)
+      extends Definition {
+    override def asRef      = TypeRef(id, Some(fieldName))
+    override def asArrayRef = ArrayRef(id, Some(fieldName))
+  }
 
   sealed trait Ref {
     def id: String
+    def fieldName: Option[String]
   }
 
-  case class TypeRef(id: String) extends Ref
+  case class TypeRef(id: String, fieldName: Option[String]) extends Ref
   object TypeRef {
-    def apply(definition: Definition): TypeRef = TypeRef(definition.id)
-    def apply(schema: JsonSchema[_]): TypeRef  = TypeRef(schema.id)
+    def apply(definition: Definition): TypeRef = TypeRef(definition.id, None)
+    def apply(schema: JsonSchema[_]): TypeRef  = TypeRef(schema.id, None)
   }
 
-  case class ArrayRef(id: String) extends Ref
+  case class ArrayRef(id: String, fieldName: Option[String]) extends Ref
   object ArrayRef {
-    def apply(definition: Definition): ArrayRef = ArrayRef(definition.id)
-    def apply(schema: JsonSchema[_]): ArrayRef  = ArrayRef(schema.id)
+    def apply(definition: Definition): ArrayRef = ArrayRef(definition.id, None)
+    def apply(schema: JsonSchema[_]): ArrayRef  = ArrayRef(schema.id, None)
   }
 
   trait PatternProperty[K] {

src/main/scala/com/timeout/docless/schema/derive/HListInstances.scala

@@ -18,15 +18,17 @@ trait HListInstances {
       lazyHSchema: Lazy[JsonSchema[H]],
       lazyTSchema: Lazy[JsonSchema[T]]
   ): JsonSchema[FieldType[K, H] :: T] = instanceAndRelated {
-    val hSchema = lazyHSchema.value
-    val tSchema = lazyTSchema.value
+    val fieldName = witness.value.name
+    val hSchema   = lazyHSchema.value
+    val tSchema   = lazyTSchema.value
     val (hValue, related) =
       if (hSchema.inline)
         hSchema.asJson -> tSchema.relatedDefinitions
       else
-        hSchema.asJsonRef -> (tSchema.relatedDefinitions + hSchema.definition)
+        hSchema.asJsonRef -> (tSchema.relatedDefinitions + hSchema
+          .namedDefinition(fieldName))
 
-    val hField  = witness.value.name -> hValue
+    val hField  = fieldName -> hValue
     val tFields = tSchema.jsonObject.toList
 
     JsonObject.fromIterable(hField :: tFields) -> related

src/main/scala/com/timeout/docless/swagger/PathGroup.scala

@@ -33,7 +33,7 @@ object PathGroup {
     val missingDefinitions =
       allDefs.foldMap { d =>
         d.relatedRefs.collect {
-          case r @ TypeRef(id) if !definedIds.exists(_ === id) =>
+          case r @ TypeRef(id, _) if !definedIds.exists(_ === id) =>
             SchemaError.missingDefinition(RefWithContext.definition(r, d))
         }
       }

src/main/scala/com/timeout/docless/swagger/SchemaError.scala

@@ -12,7 +12,8 @@ object SchemaError {
 
   implicit val mdShow: Show[SchemaError] = Show.show {
     case MissingDefinition(RefWithContext(r, DefinitionContext(d))) =>
-      s"${d.id}: cannot find a field definition for: '${r.id}'"
+      val fieldName = r.fieldName.fold("")(fld => s"(in field name: $fld)")
+      s"${d.id}: cannot find a definition for '${r.id}' $fieldName"
     case MissingDefinition(RefWithContext(r, ParamContext(param, path))) =>
       s"$path: cannot find definition '${r.id}' for parameter name '$param'"
     case MissingDefinition(RefWithContext(r, ResponseContext(method, path))) =>

src/test/scala/com/timeout/docless/schema/JsonSchemaTest.scala

@@ -111,7 +111,7 @@ class JsonSchemaTest extends FreeSpec {
           """.stripMargin) should ===(Right(schema.asJson))
 
       schema.id should ===(id[Nested])
-      schema.relatedDefinitions should ===(Set(fs.definition))
+      schema.relatedDefinitions should ===(Set(fs.namedDefinition("foo")))
     }
 
     "with types extending enumeratum.EnumEntry" - {
@@ -175,18 +175,18 @@ class JsonSchemaTest extends FreeSpec {
 
       "provides JSON definitions of the coproduct" in {
         implicit val fs: JsonSchema[Foo] = fooSchema
-        val schema                       = JsonSchema.deriveFor[ADT]
-        val ySchema                      = JsonSchema.deriveFor[A]
-        val zSchema                      = JsonSchema.deriveFor[B]
 
-        val z1Schema = JsonSchema.deriveFor[C]
+        val schema  = JsonSchema.deriveFor[ADT]
+        val aSchema = JsonSchema.deriveFor[A]
+        val bSchema = JsonSchema.deriveFor[B]
+        val cSchema = JsonSchema.deriveFor[C]
 
         schema.relatedDefinitions should ===(
           Set(
-            ySchema.definition,
-            zSchema.definition,
-            z1Schema.definition,
-            fooSchema.definition
+            aSchema.definition,
+            bSchema.definition,
+            cSchema.definition,
+            fooSchema.namedDefinition("foo")
           )
         )
       }