chore(docs): sync OpenAPI spec

docs/api-reference/rest/openapi.yml

@@ -439,7 +439,7 @@ paths:
 
         For DirectoryNamespace implementation, a table exists if either:
         - The table has Lance data versions (regular table created with CreateTable)
-        - A `.lance-reserved` file exists in the table directory (empty table created with CreateEmptyTable)
+        - A `.lance-reserved` file exists in the table directory (declared table created with DeclareTable)
       requestBody:
         required: true
         content:
@@ -1529,6 +1529,46 @@ paths:
         5XX:
           $ref: '#/components/responses/ServerErrorResponse'
 
+  /v1/table/{id}/declare:
+    parameters:
+      - $ref: '#/components/parameters/id'
+      - $ref: '#/components/parameters/delimiter'
+    post:
+      tags:
+        - Table
+        - Metadata
+      summary: Declare a table
+      operationId: DeclareTable
+      description: |
+        Declare a table with the given name without touching storage.
+        This is a metadata-only operation that records the table existence and sets up aspects like access control.
+
+        For DirectoryNamespace implementation, this creates a `.lance-reserved` file in the table directory
+        to mark the table's existence without creating actual Lance data files.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/DeclareTableRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/DeclareTableResponse'
+        400:
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '#/components/responses/UnauthorizedErrorResponse'
+        403:
+          $ref: '#/components/responses/ForbiddenErrorResponse'
+        404:
+          $ref: '#/components/responses/NotFoundErrorResponse'
+        409:
+          $ref: '#/components/responses/ConflictErrorResponse'
+        503:
+          $ref: '#/components/responses/ServiceUnavailableErrorResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+
   /v1/table/{id}/create-empty:
     parameters:
       - $ref: '#/components/parameters/id'
@@ -1539,12 +1579,15 @@ paths:
         - Metadata
       summary: Create an empty table
       operationId: CreateEmptyTable
+      deprecated: true
       description: |
         Create an empty table with the given name without touching storage.
         This is a metadata-only operation that records the table existence and sets up aspects like access control.
-        
+
         For DirectoryNamespace implementation, this creates a `.lance-reserved` file in the table directory
         to mark the table's existence without creating actual Lance data files.
+
+        **Deprecated**: Use `DeclareTable` instead.
       requestBody:
         required: true
         content:
@@ -1797,43 +1840,55 @@ components:
     ErrorResponse:
       type: object
       description: Common JSON error response model
+      required:
+        - code
       properties:
         error:
           type: string
-          description: a brief, human-readable message about the error
-          example: Incorrect username or password
+          description: A brief, human-readable message about the error.
+          example: Table 'users' not found in namespace 'production'
         code:
           type: integer
-          minimum: 400
-          maximum: 600
-          description: |
-            HTTP style response code, where 4XX represents client side errors 
-            and 5XX represents server side errors.
-
-            For implementations that uses HTTP (e.g. REST namespace),
-            this field can be optional in favor of the HTTP response status code.
-            In case both values exist and do not match, the HTTP response status code should be used.
-          example: 404
-        type:
-          type: string
+          minimum: 0
           description: |
-            An optional type identifier string for the error.
-            This allows the implementation to specify their internal error type,
-            which could be more detailed than the HTTP standard status code.
-          example: /errors/incorrect-user-pass
+            Lance Namespace error code identifying the error type.
+
+            Error codes:
+              0 - Unsupported: Operation not supported by this backend
+              1 - NamespaceNotFound: The specified namespace does not exist
+              2 - NamespaceAlreadyExists: A namespace with this name already exists
+              3 - NamespaceNotEmpty: Namespace contains tables or child namespaces
+              4 - TableNotFound: The specified table does not exist
+              5 - TableAlreadyExists: A table with this name already exists
+              6 - TableIndexNotFound: The specified table index does not exist
+              7 - TableIndexAlreadyExists: A table index with this name already exists
+              8 - TableTagNotFound: The specified table tag does not exist
+              9 - TableTagAlreadyExists: A table tag with this name already exists
+              10 - TransactionNotFound: The specified transaction does not exist
+              11 - TableVersionNotFound: The specified table version does not exist
+              12 - TableColumnNotFound: The specified table column does not exist
+              13 - InvalidInput: Malformed request or invalid parameters
+              14 - ConcurrentModification: Optimistic concurrency conflict
+              15 - PermissionDenied: User lacks permission for this operation
+              16 - Unauthenticated: Authentication credentials are missing or invalid
+              17 - ServiceUnavailable: Service is temporarily unavailable
+              18 - Internal: Unexpected server/implementation error
+              19 - InvalidTableState: Table is in an invalid state for the operation
+              20 - TableSchemaValidationError: Table schema validation failed
+          example: 4
         detail:
           type: string
           description: |
-            an optional human-readable explanation of the error.
-            This can be used to record information such as stack trace.
-          example: Authentication failed due to incorrect username or password
+            An optional human-readable explanation of the error.
+            This can be used to record additional information such as stack trace.
+          example: The table may have been dropped or renamed
         instance:
           type: string
           description: |
-            a string that identifies the specific occurrence of the error.
-            This can be a URI, a request or response ID, 
+            A string that identifies the specific occurrence of the error.
+            This can be a URI, a request or response ID,
             or anything that the implementation can recognize to trace specific occurrence of the error.
-          example: /login/log/abc123
+          example: /v1/table/production$users/describe
 
     CreateNamespaceRequest:
       type: object
@@ -2717,8 +2772,11 @@ components:
 
     CreateEmptyTableRequest:
       type: object
+      deprecated: true
       description: |
         Request for creating an empty table.
+
+        **Deprecated**: Use `DeclareTableRequest` instead.
       properties:
         id:
           type: array
@@ -2729,25 +2787,54 @@ components:
           description: |
             Optional storage location for the table.
             If not provided, the namespace implementation should determine the table location.
-        properties:
-          type: object
-          additionalProperties:
-            type: string
 
     CreateEmptyTableResponse:
       type: object
+      deprecated: true
       description: |
         Response for creating an empty table.
+
+        **Deprecated**: Use `DeclareTableResponse` instead.
       properties:
         transaction_id:
           type: string
           description: Optional transaction identifier
         location:
           type: string
-        properties:
+        storage_options:
           type: object
+          description: |
+            Configuration options to be used to access storage. The available
+            options depend on the type of storage in use. These will be
+            passed directly to Lance to initialize storage access.
           additionalProperties:
             type: string
+
+    DeclareTableRequest:
+      type: object
+      description: |
+        Request for declaring a table.
+      properties:
+        id:
+          type: array
+          items:
+            type: string
+        location:
+          type: string
+          description: |
+            Optional storage location for the table.
+            If not provided, the namespace implementation should determine the table location.
+
+    DeclareTableResponse:
+      type: object
+      description: |
+        Response for declaring a table.
+      properties:
+        transaction_id:
+          type: string
+          description: Optional transaction identifier
+        location:
+          type: string
         storage_options:
           type: object
           description: |
@@ -4084,6 +4171,13 @@ components:
           schema:
             $ref: '#/components/schemas/DropTableIndexResponse'
 
+    DeclareTableResponse:
+      description: Table properties result when declaring a table
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/DeclareTableResponse'
+
     CreateEmptyTableResponse:
       description: Table properties result when creating an empty table
       content:
@@ -4244,4 +4338,4 @@ components:
     ApiKeyAuth:
       type: apiKey
       in: header
-      name: x-api-key
+      name: x-api-key