From 1c7b915313648edf35265e9ba9c9162c322efc11 Mon Sep 17 00:00:00 2001 From: "Sung Yun (CODE SIGNING KEY)" Date: Wed, 8 Jul 2026 12:45:44 -0400 Subject: [PATCH 1/2] spec clarification on field-id handling in AddSchemaUpdate and CreateTableRequest --- open-api/rest-catalog-open-api.yaml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/open-api/rest-catalog-open-api.yaml b/open-api/rest-catalog-open-api.yaml index 419041d12a87..fd368558a9d9 100644 --- a/open-api/rest-catalog-open-api.yaml +++ b/open-api/rest-catalog-open-api.yaml @@ -3120,6 +3120,13 @@ components: AddSchemaUpdate: allOf: - $ref: '#/components/schemas/BaseUpdate' + description: + Adds a schema to the table. The field IDs in `schema` are assigned by the client. The client + assigns them so that the schema stays consistent with the data files, partition specs, and + sort orders it writes or co-commits, which reference fields by their field ID + (`StructField.id`). Servers SHOULD preserve the field IDs submitted by the client on + add-schema, as reassigning them would require re-deriving and rewriting every such reference, + including in already-written data files. required: - action - schema @@ -3930,6 +3937,9 @@ components: CreateTableRequest: type: object + description: + Table creation request. The field IDs in `schema` are assigned by the client, but because a newly + created table has no committed data, a server MAY (re)assign them when creating the table. required: - name - schema From 1e62402a3a7178c72810b154146fdd6ee0b0b463 Mon Sep 17 00:00:00 2001 From: "Sung Yun (CODE SIGNING KEY)" Date: Wed, 8 Jul 2026 12:52:14 -0400 Subject: [PATCH 2/2] gen open api pyfile --- open-api/rest-catalog-open-api.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/open-api/rest-catalog-open-api.py b/open-api/rest-catalog-open-api.py index 99fe855147c8..5f0e26c4ecad 100644 --- a/open-api/rest-catalog-open-api.py +++ b/open-api/rest-catalog-open-api.py @@ -1516,6 +1516,10 @@ class ViewMetadata(BaseModel): class AddSchemaUpdate(BaseUpdate): + """ + Adds a schema to the table. The field IDs in `schema` are assigned by the client. The client assigns them so that the schema stays consistent with the data files, partition specs, and sort orders it writes or co-commits, which reference fields by their field ID (`StructField.id`). Servers SHOULD preserve the field IDs submitted by the client on add-schema, as reassigning them would require re-deriving and rewriting every such reference, including in already-written data files. + """ + action: Literal['add-schema'] schema_: Schema = Field(..., alias='schema') last_column_id: int | None = Field( @@ -1636,6 +1640,10 @@ class CommitTransactionRequest(BaseModel): class CreateTableRequest(BaseModel): + """ + Table creation request. The field IDs in `schema` are assigned by the client, but because a newly created table has no committed data, a server MAY (re)assign them when creating the table. + """ + name: str location: str | None = None schema_: Schema = Field(..., alias='schema')