From 1c1d2b3d43d153ab19ff76fdce652aac4c488c0b Mon Sep 17 00:00:00 2001
From: nicolas-paris <nicolas.paris@adevinta.com>
Date: Tue, 3 Feb 2026 10:36:04 +0100
Subject: [PATCH 1/2] feat: extract comments from avro schema

---
 .../java/org/apache/xtable/avro/AvroSchemaConverter.java   | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/xtable-core/src/main/java/org/apache/xtable/avro/AvroSchemaConverter.java b/xtable-core/src/main/java/org/apache/xtable/avro/AvroSchemaConverter.java
index 9b4c3eacb..b08248b94 100644
--- a/xtable-core/src/main/java/org/apache/xtable/avro/AvroSchemaConverter.java
+++ b/xtable-core/src/main/java/org/apache/xtable/avro/AvroSchemaConverter.java
@@ -186,12 +186,19 @@ private InternalSchema toInternalSchema(
         List<InternalField> subFields = new ArrayList<>(schema.getFields().size());
         for (Schema.Field avroField : schema.getFields()) {
           IdMapping idMapping = fieldNameToIdMapping.get(avroField.name());
+          String fieldDoc = avroField.doc();
+          if (fieldDoc == null) {
+            fieldDoc = avroField.getProp("comment");
+          }
           InternalSchema subFieldSchema =
               toInternalSchema(
                   avroField.schema(),
                   SchemaUtils.getFullyQualifiedPath(parentPath, avroField.name()),
                   getChildIdMap(idMapping));
           Object defaultValue = getDefaultValue(avroField);
+          if (fieldDoc != null && subFieldSchema.getComment() == null) {
+            subFieldSchema = InternalSchema.builderFrom(subFieldSchema).comment(fieldDoc).build();
+          }
           subFields.add(
               InternalField.builder()
                   .parentPath(parentPath)

From ffd67611c058735714193839790b733de75fe25f Mon Sep 17 00:00:00 2001
From: nicolas-paris <nicolas.paris@adevinta.com>
Date: Wed, 11 Feb 2026 17:06:34 +0100
Subject: [PATCH 2/2] add ut

---
 .../xtable/avro/TestAvroSchemaConverter.java  | 21 +++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/xtable-core/src/test/java/org/apache/xtable/avro/TestAvroSchemaConverter.java b/xtable-core/src/test/java/org/apache/xtable/avro/TestAvroSchemaConverter.java
index 4e2991989..b01b4f326 100644
--- a/xtable-core/src/test/java/org/apache/xtable/avro/TestAvroSchemaConverter.java
+++ b/xtable-core/src/test/java/org/apache/xtable/avro/TestAvroSchemaConverter.java
@@ -889,4 +889,25 @@ public void testIcebergToAvroUUIDSupport() {
     assertEquals(
         internalSchema, AvroSchemaConverter.getInstance().toInternalSchema(avroRepresentation));
   }
+
+  @Test
+  public void testExtractFieldCommentsFromAvroDocOrProp() {
+    Schema avroRepresentation =
+        new Schema.Parser()
+            .parse(
+                "{\"type\":\"record\",\"name\":\"commentRecord\",\"fields\":["
+                    + "{\"name\":\"withDoc\",\"type\":\"string\",\"doc\":\"doc comment\"},"
+                    + "{\"name\":\"withProp\",\"type\":\"int\",\"comment\":\"prop comment\"}"
+                    + "]}");
+
+    InternalSchema internalSchema =
+        AvroSchemaConverter.getInstance().toInternalSchema(avroRepresentation);
+
+    Map<String, InternalField> fieldsByName =
+        internalSchema.getFields().stream()
+            .collect(java.util.stream.Collectors.toMap(InternalField::getName, f -> f));
+
+    assertEquals("doc comment", fieldsByName.get("withDoc").getSchema().getComment());
+    assertEquals("prop comment", fieldsByName.get("withProp").getSchema().getComment());
+  }
 }