Skip to content

OpenAPI: Mark StructField doc as nullable in REST catalog spec #16070

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Amneet13 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

OpenAPI: Mark StructField doc as nullable in REST catalog spec #16070

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions open-api/rest-catalog-open-api.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2293,6 +2293,7 @@ components:
type: boolean
doc:
type: string
nullable: true
Comment on lines 2294 to +2296
Copy link
Copy Markdown
Contributor

@singhpk234 singhpk234 Apr 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

isn't this optional ?

iceberg/core/src/main/java/org/apache/iceberg/SchemaParser.java

Lines 92 to 94 in 1f0579f

if (field.doc() != null) {
generator.writeStringField(DOC, field.doc());
}

while sending to server this is omitted ? i know while reading i.e fromJson we are null tolerant but i think its fine

Copy link
Copy Markdown
Author

@Amneet13 Amneet13 Apr 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@singhpk234 Thanks for the review! You're right that the Iceberg serializer omits doc when it's null. However, we ran into a real-world case where an Iceberg table is created on top of a Paimon table — in that scenario doc is explicitly sent as null (not omitted) in the response. This causes deserialization failures in clients auto-generated from the OpenAPI spec since the spec didn't allow null. Adding nullable: true makes the spec tolerant of both cases — absent and explicitly null — which is the safer contract for external clients.

initial-default:
$ref: "#/components/schemas/PrimitiveTypeValue"
write-default:
Expand Down
Loading