Merge pull request #1895 from Milyardo/APIREG-321-render-nullable-as-nullable

[0.19] Render fields marked nullable as smithy4s.Nullable rather than Option

Author: lewisjkl

CHANGELOG.md

@@ -74,6 +74,7 @@ The behavior of `@default(null)` has changed to better align with Smithy semanti
   - **Breaking change**: previously generated non-optional Scala fields with type-specific defaults (e.g., `0`, `false`).
   - Now generates **optional (`Option`) fields without default**.
   - Still renders `Default(Document.DNull)` to preserve model fidelity.
+  - The underlying value type in `@sparse` collections are now rendered as `Nullable` rather than `Option`
 
 - **In smithy4s-core**:
   - `Document.DNull` is interpreted as `Nullable.Null` when `@nullable` is present.

modules/bootstrapped/src/generated/smithy4s/example/SparseStringList.scala

@@ -2,17 +2,18 @@ package smithy4s.example
 
 import smithy4s.Hints
 import smithy4s.Newtype
+import smithy4s.Nullable
 import smithy4s.Schema
 import smithy4s.ShapeId
 import smithy4s.schema.Schema.bijection
 import smithy4s.schema.Schema.list
 import smithy4s.schema.Schema.string
 
-object SparseStringList extends Newtype[List[Option[String]]] {
+object SparseStringList extends Newtype[List[Nullable[String]]] {
   val id: ShapeId = ShapeId("smithy4s.example", "SparseStringList")
   val hints: Hints = Hints(
     Hints.dynamic(ShapeId("smithy.api", "sparse"), smithy4s.Document.obj()),
   )
-  val underlyingSchema: Schema[List[Option[String]]] = list(string.option).withId(id).addHints(hints)
+  val underlyingSchema: Schema[List[Nullable[String]]] = list(string.nullable).withId(id).addHints(hints)
   implicit val schema: Schema[SparseStringList] = bijection(underlyingSchema, asBijection)
 }

modules/bootstrapped/src/generated/smithy4s/example/SparseStringMap.scala

@@ -2,17 +2,18 @@ package smithy4s.example
 
 import smithy4s.Hints
 import smithy4s.Newtype
+import smithy4s.Nullable
 import smithy4s.Schema
 import smithy4s.ShapeId
 import smithy4s.schema.Schema.bijection
 import smithy4s.schema.Schema.map
 import smithy4s.schema.Schema.string
 
-object SparseStringMap extends Newtype[Map[String, Option[String]]] {
+object SparseStringMap extends Newtype[Map[String, Nullable[String]]] {
   val id: ShapeId = ShapeId("smithy4s.example", "SparseStringMap")
   val hints: Hints = Hints(
     Hints.dynamic(ShapeId("smithy.api", "sparse"), smithy4s.Document.obj()),
   )
-  val underlyingSchema: Schema[Map[String, Option[String]]] = map(string, string.option).withId(id).addHints(hints)
+  val underlyingSchema: Schema[Map[String, Nullable[String]]] = map(string, string.nullable).withId(id).addHints(hints)
   implicit val schema: Schema[SparseStringMap] = bijection(underlyingSchema, asBijection)
 }

modules/codegen/src/smithy4s/codegen/internals/Renderer.scala

@@ -1689,7 +1689,7 @@ private[internals] class Renderer(compilationUnit: CompilationUnit) { self =>
         line"${underlyingTpe.schemaRef}.refined[${e: Type}](${renderHint(hint)})${maybeProviderImport
           .map { providerImport => Import(providerImport).toLine }
           .getOrElse(Line.empty)}"
-      case Nullable(underlying) => line"${underlying.schemaRef}.option"
+      case Nullable(underlying) => line"${underlying.schemaRef}.nullable"
     }
 
     private def schemaRefP(primitive: Primitive): String = primitive match {

modules/codegen/src/smithy4s/codegen/internals/ToLine.scala

@@ -72,7 +72,7 @@ private[internals] object ToLine {
       case e: Type.ExternalType =>
         NameRef(e.fullyQualifiedName, e.typeParameters.map(typeToNameRef))
       case Type.Nullable(underlying) =>
-        NameRef("scala", "Option").copy(typeParams =
+        NameRef("smithy4s", "Nullable").copy(typeParams =
           List(typeToNameRef(underlying))
         )
     }

modules/codegen/test/src/smithy4s/codegen/internals/RendererSpec.scala

@@ -727,4 +727,70 @@ final class RendererSpec extends munit.ScalaCheckSuite {
     )
 
   }
+
+  test("nullable fields should be rendered as smithy4s.Nullable") {
+    val smithy =
+      """
+        |$version: "2.0"
+        |
+        |namespace smithy4s
+        |
+        |use alloy#nullable
+        |
+        |structure NullableExample {
+        |  @nullable
+        |  @required
+        |  nullableString: String
+        |}
+        |""".stripMargin
+
+    val contents = generateScalaCode(smithy).values
+    val definition =
+      contents.find(_.contains("final case class NullableExample")).get
+
+    assert(
+      definition.contains("nullableString: Nullable[String]"),
+      s"$definition does not contain Nullable[String]"
+    )
+  }
+
+  test("sparse collection types should be rendered as Nullable") {
+    val smithy =
+      """
+        |$version: "2.0"
+        |
+        |namespace smithy4s
+        |
+        |@sparse
+        |list SparseStringList {
+        |  member: String
+        |}
+        |
+        |@sparse
+        |map SparseStringMap {
+        |  key: String
+        |  value: String
+        |}
+        |""".stripMargin
+
+    val contents = generateScalaCode(smithy).values
+
+    val listDefinition =
+      contents.find(_.contains("object SparseStringList")).getOrElse {
+        fail("No SparseStringList definition")
+      }
+
+    val mapDefinition =
+      contents.find(_.contains("object SparseStringMap")).getOrElse {
+        fail("No SparseStringMap definition")
+      }
+
+    val sparseListSchema =
+      "val underlyingSchema: Schema[List[Nullable[String]]] = list(string.nullable)"
+    assert(listDefinition.contains(sparseListSchema))
+
+    val sparseMapSchema =
+      "val underlyingSchema: Schema[Map[String, Nullable[String]]] = map(string, string.nullable)"
+    assert(mapDefinition.contains(sparseMapSchema))
+  }
 }

modules/docs/resources/markdown/04-codegen/01-customisation/13-nullable-values.md

@@ -52,5 +52,6 @@ The annotation `@nullable` can be combined with both `@required` and `@default`,
 
 * annotating as `@required` will forbid the field from being omitted but permit null to be passed explicitly on deserialization. It will always include the field but potentially set it to null on serialization.
 * annotating as `@default` works the same as default values for non-nullable fields, with the exception that the default can be set to null and [not automatically adjusted into a "zero value"](../03-default-values.md)
+* annotating a collection as `@sparse` will render that collections value type as `Nullable` rather than `Option`
 
 In both cases, the resulting Scala type of the field will be `smithy.Nullable[T]`.