refactor(serde): return Result from ToJson for schema/type/metadata serializers

Column default values make single-value (Literal) serialization fallible, so the
schema/type serializers must propagate errors instead of throwing. Change ToJson for
SchemaField, Type, Schema, TableMetadata and TableUpdate (plus the REST
CreateTableRequest/CommitTableRequest/LoadTableResult/CommitTableResponse, which embed
them) to return Result<nlohmann::json>, replacing the ICEBERG_ASSIGN_OR_THROW in
SchemaField default serialization with ICEBERG_ASSIGN_OR_RAISE.

- The shared ToJsonList template (also used by infallible serializers) is left
  unchanged; TableMetadata serializes its schema list with an explicit loop.
- REST adds an ICEBERG_DECLARE_JSON_SERDE_FALLIBLE macro variant for the four models
  that embed a schema/metadata; the other REST models keep the bare-json ToJson.
- Callers bottom out at existing Result boundaries (ToJsonString wrappers,
  rest_catalog.cc, TableMetadataUtil::Write).
- Tests unwrap via ICEBERG_UNWRAP_OR_FAIL.

Author: huan233usc

src/iceberg/catalog/rest/json_serde.cc

@@ -690,10 +690,10 @@ Result<RenameTableRequest> RenameTableRequestFromJson(const nlohmann::json& json
 }
 
 // LoadTableResult (used by CreateTableResponse, LoadTableResponse)
-nlohmann::json ToJson(const LoadTableResult& result) {
+Result<nlohmann::json> ToJson(const LoadTableResult& result) {
   nlohmann::json json;
   SetOptionalStringField(json, kMetadataLocation, result.metadata_location);
-  json[kMetadata] = ToJson(*result.metadata);
+  ICEBERG_ASSIGN_OR_RAISE(json[kMetadata], ToJson(*result.metadata));
   SetContainerField(json, kConfig, result.config);
   return json;
 }
@@ -820,12 +820,12 @@ Result<ListTablesResponse> ListTablesResponseFromJson(const nlohmann::json& json
   return response;
 }
 
-nlohmann::json ToJson(const CreateTableRequest& request) {
+Result<nlohmann::json> ToJson(const CreateTableRequest& request) {
   nlohmann::json json;
   json[kName] = request.name;
   SetOptionalStringField(json, kLocation, request.location);
   if (request.schema) {
-    json[kSchema] = ToJson(*request.schema);
+    ICEBERG_ASSIGN_OR_RAISE(json[kSchema], ToJson(*request.schema));
   }
   if (request.partition_spec) {
     json[kPartitionSpec] = ToJson(*request.partition_spec);
@@ -872,7 +872,7 @@ Result<CreateTableRequest> CreateTableRequestFromJson(const nlohmann::json& json
 }
 
 // CommitTableRequest serialization
-nlohmann::json ToJson(const CommitTableRequest& request) {
+Result<nlohmann::json> ToJson(const CommitTableRequest& request) {
   nlohmann::json json;
   if (!request.identifier.name.empty()) {
     json[kIdentifier] = ToJson(request.identifier);
@@ -886,7 +886,8 @@ nlohmann::json ToJson(const CommitTableRequest& request) {
 
   nlohmann::json updates_json = nlohmann::json::array();
   for (const auto& update : request.updates) {
-    updates_json.push_back(ToJson(*update));
+    ICEBERG_ASSIGN_OR_RAISE(auto update_json, ToJson(*update));
+    updates_json.push_back(std::move(update_json));
   }
   json[kUpdates] = std::move(updates_json);
 
@@ -932,11 +933,11 @@ Result<CommitTableRequest> CommitTableRequestFromJson(const nlohmann::json& json
 }
 
 // CommitTableResponse serialization
-nlohmann::json ToJson(const CommitTableResponse& response) {
+Result<nlohmann::json> ToJson(const CommitTableResponse& response) {
   nlohmann::json json;
   json[kMetadataLocation] = response.metadata_location;
   if (response.metadata) {
-    json[kMetadata] = ToJson(*response.metadata);
+    ICEBERG_ASSIGN_OR_RAISE(json[kMetadata], ToJson(*response.metadata));
   }
   return json;
 }

src/iceberg/catalog/rest/json_serde_internal.h

@@ -46,6 +46,16 @@ Result<Model> FromJson(const nlohmann::json& json);
                                                                                  \
   ICEBERG_REST_EXPORT nlohmann::json ToJson(const Model& model);
 
+// Same as ICEBERG_DECLARE_JSON_SERDE, but ToJson returns Result because the model
+// embeds a Schema/TableMetadata whose default-value serialization can fail.
+#define ICEBERG_DECLARE_JSON_SERDE_FALLIBLE(Model)                               \
+  ICEBERG_REST_EXPORT Result<Model> Model##FromJson(const nlohmann::json& json); \
+                                                                                 \
+  template <>                                                                    \
+  ICEBERG_REST_EXPORT Result<Model> FromJson(const nlohmann::json& json);        \
+                                                                                 \
+  ICEBERG_REST_EXPORT Result<nlohmann::json> ToJson(const Model& model);
+
 /// \note Don't forget to add `ICEBERG_DEFINE_FROM_JSON` to the end of
 /// `json_internal.cc` to define the `FromJson` function for the model.
 ICEBERG_DECLARE_JSON_SERDE(CatalogConfig)
@@ -57,15 +67,16 @@ ICEBERG_DECLARE_JSON_SERDE(GetNamespaceResponse)
 ICEBERG_DECLARE_JSON_SERDE(UpdateNamespacePropertiesRequest)
 ICEBERG_DECLARE_JSON_SERDE(UpdateNamespacePropertiesResponse)
 ICEBERG_DECLARE_JSON_SERDE(ListTablesResponse)
-ICEBERG_DECLARE_JSON_SERDE(LoadTableResult)
+ICEBERG_DECLARE_JSON_SERDE_FALLIBLE(LoadTableResult)
 ICEBERG_DECLARE_JSON_SERDE(RegisterTableRequest)
 ICEBERG_DECLARE_JSON_SERDE(RenameTableRequest)
-ICEBERG_DECLARE_JSON_SERDE(CreateTableRequest)
-ICEBERG_DECLARE_JSON_SERDE(CommitTableRequest)
-ICEBERG_DECLARE_JSON_SERDE(CommitTableResponse)
+ICEBERG_DECLARE_JSON_SERDE_FALLIBLE(CreateTableRequest)
+ICEBERG_DECLARE_JSON_SERDE_FALLIBLE(CommitTableRequest)
+ICEBERG_DECLARE_JSON_SERDE_FALLIBLE(CommitTableResponse)
 ICEBERG_DECLARE_JSON_SERDE(OAuthTokenResponse)
 
 #undef ICEBERG_DECLARE_JSON_SERDE
+#undef ICEBERG_DECLARE_JSON_SERDE_FALLIBLE
 
 ICEBERG_REST_EXPORT Result<PlanTableScanResponse> PlanTableScanResponseFromJson(
     const nlohmann::json& json,

src/iceberg/catalog/rest/rest_catalog.cc

@@ -666,7 +666,8 @@ Result<LoadTableResult> RestCatalog::CreateTableInternal(
       .properties = properties,
   };
 
-  ICEBERG_ASSIGN_OR_RAISE(auto json_request, ToJsonString(ToJson(request)));
+  ICEBERG_ASSIGN_OR_RAISE(auto request_json, ToJson(request));
+  ICEBERG_ASSIGN_OR_RAISE(auto json_request, ToJsonString(request_json));
   ICEBERG_ASSIGN_OR_RAISE(const auto response,
                           client_->Post(path, json_request, /*headers=*/{},
                                         *TableErrorHandler::Instance(), session));
@@ -709,7 +710,8 @@ Result<CommitTableResponse> RestCatalog::UpdateTableInternal(
     request.updates.push_back(update->Clone());
   }
 
-  ICEBERG_ASSIGN_OR_RAISE(auto json_request, ToJsonString(ToJson(request)));
+  ICEBERG_ASSIGN_OR_RAISE(auto request_json, ToJson(request));
+  ICEBERG_ASSIGN_OR_RAISE(auto json_request, ToJsonString(request_json));
   ICEBERG_ASSIGN_OR_RAISE(const auto response,
                           client_->Post(path, json_request, /*headers=*/{},
                                         *TableErrorHandler::Instance(), session));

src/iceberg/json_serde.cc

@@ -301,36 +301,35 @@ Result<std::unique_ptr<SortOrder>> SortOrderFromJson(const nlohmann::json& json)
   return SortOrder::Make(order_id, std::move(sort_fields));
 }
 
-nlohmann::json ToJson(const SchemaField& field) {
+Result<nlohmann::json> ToJson(const SchemaField& field) {
   nlohmann::json json;
   json[kId] = field.field_id();
   json[kName] = field.name();
   json[kRequired] = !field.optional();
-  json[kType] = ToJson(*field.type());
+  ICEBERG_ASSIGN_OR_RAISE(json[kType], ToJson(*field.type()));
   if (!field.doc().empty()) {
     json[kDoc] = field.doc();
   }
-  // Defaults are validated to be primitive literals matching the field type, so
-  // single-value serialization cannot fail here.
   if (field.initial_default().has_value()) {
-    ICEBERG_ASSIGN_OR_THROW(json[kInitialDefault],
+    ICEBERG_ASSIGN_OR_RAISE(json[kInitialDefault],
                             ToJson(field.initial_default()->get()));
   }
   if (field.write_default().has_value()) {
-    ICEBERG_ASSIGN_OR_THROW(json[kWriteDefault], ToJson(field.write_default()->get()));
+    ICEBERG_ASSIGN_OR_RAISE(json[kWriteDefault], ToJson(field.write_default()->get()));
   }
   return json;
 }
 
-nlohmann::json ToJson(const Type& type) {
+Result<nlohmann::json> ToJson(const Type& type) {
   switch (type.type_id()) {
     case TypeId::kStruct: {
       const auto& struct_type = internal::checked_cast<const StructType&>(type);
       nlohmann::json json;
       json[kType] = kStruct;
       nlohmann::json fields_json = nlohmann::json::array();
       for (const auto& field : struct_type.fields()) {
-        fields_json.push_back(ToJson(field));
+        ICEBERG_ASSIGN_OR_RAISE(auto field_json, ToJson(field));
+        fields_json.push_back(std::move(field_json));
       }
       json[kFields] = fields_json;
       return json;
@@ -343,7 +342,7 @@ nlohmann::json ToJson(const Type& type) {
       const auto& element_field = list_type.fields().front();
       json[kElementId] = element_field.field_id();
       json[kElementRequired] = !element_field.optional();
-      json[kElement] = ToJson(*element_field.type());
+      ICEBERG_ASSIGN_OR_RAISE(json[kElement], ToJson(*element_field.type()));
       return json;
     }
     case TypeId::kMap: {
@@ -353,12 +352,12 @@ nlohmann::json ToJson(const Type& type) {
 
       const auto& key_field = map_type.key();
       json[kKeyId] = key_field.field_id();
-      json[kKey] = ToJson(*key_field.type());
+      ICEBERG_ASSIGN_OR_RAISE(json[kKey], ToJson(*key_field.type()));
 
       const auto& value_field = map_type.value();
       json[kValueId] = value_field.field_id();
       json[kValueRequired] = !value_field.optional();
-      json[kValue] = ToJson(*value_field.type());
+      ICEBERG_ASSIGN_OR_RAISE(json[kValue], ToJson(*value_field.type()));
       return json;
     }
     case TypeId::kBoolean:
@@ -404,8 +403,9 @@ nlohmann::json ToJson(const Type& type) {
   std::unreachable();
 }
 
-nlohmann::json ToJson(const Schema& schema) {
-  nlohmann::json json = ToJson(internal::checked_cast<const Type&>(schema));
+Result<nlohmann::json> ToJson(const Schema& schema) {
+  ICEBERG_ASSIGN_OR_RAISE(nlohmann::json json,
+                          ToJson(internal::checked_cast<const Type&>(schema)));
   json[kSchemaId] = schema.schema_id();
   if (!schema.IdentifierFieldIds().empty()) {
     json[kIdentifierFieldIds] = schema.IdentifierFieldIds();
@@ -414,7 +414,8 @@ nlohmann::json ToJson(const Schema& schema) {
 }
 
 Result<std::string> ToJsonString(const Schema& schema) {
-  return ToJsonString(ToJson(schema));
+  ICEBERG_ASSIGN_OR_RAISE(auto json, ToJson(schema));
+  return ToJsonString(json);
 }
 
 nlohmann::json ToJson(const SnapshotRef& ref) {
@@ -956,7 +957,7 @@ Result<EncryptedKey> EncryptedKeyFromJson(const nlohmann::json& json) {
   };
 }
 
-nlohmann::json ToJson(const TableMetadata& table_metadata) {
+Result<nlohmann::json> ToJson(const TableMetadata& table_metadata) {
   nlohmann::json json;
 
   json[kFormatVersion] = table_metadata.format_version;
@@ -974,15 +975,22 @@ nlohmann::json ToJson(const TableMetadata& table_metadata) {
   if (table_metadata.format_version == 1) {
     for (const auto& schema : table_metadata.schemas) {
       if (schema->schema_id() == table_metadata.current_schema_id) {
-        json[kSchema] = ToJson(*schema);
+        ICEBERG_ASSIGN_OR_RAISE(json[kSchema], ToJson(*schema));
         break;
       }
     }
   }
 
   // write the current schema ID and schema list
   json[kCurrentSchemaId] = table_metadata.current_schema_id;
-  json[kSchemas] = ToJsonList(table_metadata.schemas);
+  // Schemas can carry fallible default-value serialization, so the shared ToJsonList
+  // helper (which assumes infallible ToJson) is not used here.
+  nlohmann::json schemas_json = nlohmann::json::array();
+  for (const auto& schema : table_metadata.schemas) {
+    ICEBERG_ASSIGN_OR_RAISE(auto schema_json, ToJson(*schema));
+    schemas_json.push_back(std::move(schema_json));
+  }
+  json[kSchemas] = std::move(schemas_json);
 
   // for older readers, continue writing the default spec as "partition-spec"
   if (table_metadata.format_version == 1) {
@@ -1032,7 +1040,8 @@ nlohmann::json ToJson(const TableMetadata& table_metadata) {
 }
 
 Result<std::string> ToJsonString(const TableMetadata& table_metadata) {
-  return ToJsonString(ToJson(table_metadata));
+  ICEBERG_ASSIGN_OR_RAISE(auto json, ToJson(table_metadata));
+  return ToJsonString(json);
 }
 
 namespace {
@@ -1435,7 +1444,7 @@ Result<Namespace> NamespaceFromJson(const nlohmann::json& json) {
   return ns;
 }
 
-nlohmann::json ToJson(const TableUpdate& update) {
+Result<nlohmann::json> ToJson(const TableUpdate& update) {
   nlohmann::json json;
   switch (update.kind()) {
     case TableUpdate::Kind::kAssignUUID: {
@@ -1454,7 +1463,7 @@ nlohmann::json ToJson(const TableUpdate& update) {
       const auto& u = internal::checked_cast<const table::AddSchema&>(update);
       json[kAction] = kActionAddSchema;
       if (u.schema()) {
-        json[kSchema] = ToJson(*u.schema());
+        ICEBERG_ASSIGN_OR_RAISE(json[kSchema], ToJson(*u.schema()));
       } else {
         json[kSchema] = nlohmann::json::value_t::null;
       }

src/iceberg/json_serde_internal.h

@@ -93,7 +93,7 @@ ICEBERG_EXPORT Result<std::unique_ptr<SortOrder>> SortOrderFromJson(
 ///
 /// \param schema The Iceberg schema to convert.
 /// \return The JSON representation of the schema.
-ICEBERG_EXPORT nlohmann::json ToJson(const Schema& schema);
+ICEBERG_EXPORT Result<nlohmann::json> ToJson(const Schema& schema);
 
 /// \brief Convert an Iceberg Schema to JSON.
 ///
@@ -111,7 +111,7 @@ ICEBERG_EXPORT Result<std::unique_ptr<Schema>> SchemaFromJson(const nlohmann::js
 ///
 /// \param type The Iceberg type to convert.
 /// \return The JSON representation of the type.
-ICEBERG_EXPORT nlohmann::json ToJson(const Type& type);
+ICEBERG_EXPORT Result<nlohmann::json> ToJson(const Type& type);
 
 /// \brief Convert JSON to an Iceberg Type.
 ///
@@ -123,7 +123,7 @@ ICEBERG_EXPORT Result<std::unique_ptr<Type>> TypeFromJson(const nlohmann::json&
 ///
 /// \param field The Iceberg field to convert.
 /// \return The JSON representation of the field.
-ICEBERG_EXPORT nlohmann::json ToJson(const SchemaField& field);
+ICEBERG_EXPORT Result<nlohmann::json> ToJson(const SchemaField& field);
 
 /// \brief Convert JSON to an Iceberg SchemaField.
 ///
@@ -300,7 +300,7 @@ ICEBERG_EXPORT Result<EncryptedKey> EncryptedKeyFromJson(const nlohmann::json& j
 ///
 /// \param table_metadata The `TableMetadata` object to be serialized.
 /// \return A JSON object representing the `TableMetadata`.
-ICEBERG_EXPORT nlohmann::json ToJson(const TableMetadata& table_metadata);
+ICEBERG_EXPORT Result<nlohmann::json> ToJson(const TableMetadata& table_metadata);
 
 /// \brief Serializes a `TableMetadata` object to JSON.
 ///
@@ -404,7 +404,7 @@ ICEBERG_EXPORT Result<Namespace> NamespaceFromJson(const nlohmann::json& json);
 ///
 /// \param update The `TableUpdate` object to be serialized.
 /// \return A JSON object representing the `TableUpdate`.
-ICEBERG_EXPORT nlohmann::json ToJson(const TableUpdate& update);
+ICEBERG_EXPORT Result<nlohmann::json> ToJson(const TableUpdate& update);
 
 /// \brief Deserializes a JSON object into a `TableUpdate` object.
 ///

src/iceberg/table_metadata.cc

@@ -489,7 +489,7 @@ Result<std::string> TableMetadataUtil::Write(FileIO& io, const TableMetadata* ba
 
 Status TableMetadataUtil::Write(FileIO& io, const std::string& location,
                                 const TableMetadata& metadata) {
-  auto json = ToJson(metadata);
+  ICEBERG_ASSIGN_OR_RAISE(auto json, ToJson(metadata));
   ICEBERG_ASSIGN_OR_RAISE(auto json_string, ToJsonString(json));
   return io.WriteFile(location, json_string);
 }