[SPEC] Add base-location keyword for GenericTable API (#1543)

Author: gh-yzou

api/polaris-catalog-service/build.gradle.kts

@@ -122,3 +122,5 @@ sourceSets {
 tasks.named("javadoc") { dependsOn("jandex") }
 
 tasks.named("processResources") { dependsOn("openApiGenerate") }
+
+tasks.named("openApiGenerate") { outputs.cacheIf { false } }

integration-tests/src/main/java/org/apache/polaris/service/it/test/PolarisRestCatalogIntegrationTest.java

@@ -1468,11 +1468,12 @@ public void testCreateGenericTableWithReservedProperty() {
                 Map.of("cat", currentCatalogName, "ns", ns))
             .post(
                 Entity.json(
-                    new CreateGenericTableRequest(
-                        tableIdentifier.name(),
-                        "format",
-                        "doc",
-                        Map.of("polaris.reserved", "true"))))) {
+                    CreateGenericTableRequest.builder()
+                        .setName(tableIdentifier.name())
+                        .setFormat("format")
+                        .setDoc("doc")
+                        .setProperties(Map.of("polaris.reserved", "true"))
+                        .build()))) {
       Assertions.assertThat(res.getStatus()).isEqualTo(Response.Status.BAD_REQUEST.getStatusCode());
       Assertions.assertThat(res.readEntity(String.class)).contains("reserved prefix");
     }

plugins/spark/v3.5/spark/src/main/java/org/apache/polaris/spark/rest/CreateGenericTableRESTRequest.java

@@ -36,13 +36,19 @@ public class CreateGenericTableRESTRequest extends CreateGenericTableRequest
   public CreateGenericTableRESTRequest(
       @JsonProperty(value = "name", required = true) String name,
       @JsonProperty(value = "format", required = true) String format,
+      @JsonProperty(value = "base-location") String baseLocation,
       @JsonProperty(value = "doc") String doc,
       @JsonProperty(value = "properties") Map<String, String> properties) {
-    super(name, format, doc, properties);
+    super(name, format, baseLocation, doc, properties);
   }
 
   public CreateGenericTableRESTRequest(CreateGenericTableRequest request) {
-    this(request.getName(), request.getFormat(), request.getDoc(), request.getProperties());
+    this(
+        request.getName(),
+        request.getFormat(),
+        request.getBaseLocation(),
+        request.getDoc(),
+        request.getProperties());
   }
 
   @Override

spec/generated/bundled-polaris-catalog-service.yaml

@@ -3880,6 +3880,8 @@ components:
           type: string
         format:
           type: string
+        base-location:
+          type: string
         doc:
           type: string
         properties:
@@ -3890,10 +3892,15 @@ components:
       type: object
       description: |
         Generic Table information.
-        - `name` name for the generic table
-        - `format` format for the generic table, i.e. "delta", "csv"
-        - `properties` properties for the generic table passed on creation
-        - `doc` comment or description for the generic table
+        - `name` (REQUIRED): name for the generic table
+        - `format` (REQUIRED): format for the generic table, i.e. "delta", "csv"
+        - `base-location` (OPTIONAL): table base location in URI format. For example: s3://<my-bucket>/path/to/table.
+          - The table base location is a location that includes all files for the table.
+          - A table with multiple disjoint locations (i.e. containing files that are outside the configured base location) is not compliant with the current generic table support in Polaris.
+          - If no location is provided, clients or users are responsible for managing the location.
+
+        - `properties` (OPTIONAL): properties for the generic table passed on creation
+        - `doc` (OPTIONAL): comment or description for the generic table
       required:
         - name
         - format
@@ -3902,6 +3909,8 @@ components:
           type: string
         format:
           type: string
+        base-location:
+          type: string
         doc:
           type: string
         properties:

spec/polaris-catalog-apis/generic-tables-api.yaml

@@ -193,6 +193,8 @@ components:
           type: string
         format:
           type: string
+        base-location:
+          type: string
         doc:
           type: string
         properties:
@@ -205,13 +207,18 @@ components:
       description: >
         Generic Table information.
         
-        - `name` name for the generic table
+        - `name` (REQUIRED): name for the generic table
+        
+        - `format` (REQUIRED): format for the generic table, i.e. "delta", "csv"
         
-        - `format` format for the generic table, i.e. "delta", "csv"
+        - `base-location` (OPTIONAL): table base location in URI format. For example: s3://<my-bucket>/path/to/table.
+          - The table base location is a location that includes all files for the table.
+          - A table with multiple disjoint locations (i.e. containing files that are outside the configured base location) is not compliant with the current generic table support in Polaris.
+          - If no location is provided, clients or users are responsible for managing the location.
         
-        - `properties` properties for the generic table passed on creation
+        - `properties` (OPTIONAL): properties for the generic table passed on creation
         
-        - `doc` comment or description for the generic table
+        - `doc` (OPTIONAL): comment or description for the generic table
       required:
         - name
         - format
@@ -220,6 +227,8 @@ components:
           type: string
         format:
           type: string
+        base-location:
+          type: string
         doc:
           type: string
         properties: