You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@polaris.apache.org by "flyingImer (via GitHub)" <gi...@apache.org> on 2026/08/25 00:01:10 UTC

[PR] Polaris Catalog Spec: Tag Management APIs [polaris]

flyingImer opened a new pull request, #5366:
URL: https://github.com/apache/polaris/pull/5366

   ## Why
   
   Polaris currently has no catalog-native way to classify catalog objects, read direct or inherited classifications, or discover objects by classification. This PR defines the first Tag API contract so clients and backends can agree on those semantics before implementation.
   
   ## API shape
   
   The contract follows the existing Policy API where that shape fits:
   
   * catalog-scoped Tag definition CRUD
   * structured targets for catalogs, namespaces, table-like objects, and columns
   * assignment and unassignment
   * direct and effective reads for a target
   * reverse lookup of direct assignments by Tag
   
   A Tag keeps a durable identifier across rename. `target-types` is create-only, while a present, non-null `allowed-values` list replaces the complete list on update. Request-side cardinality and uniqueness checks remain Tag-specific server validation so generated DTOs preserve the submitted order and duplicates for validation. `apply-method` remains an open string so later inheritance modes can be added without breaking generated clients.
   
   ## V1 boundaries
   
   V1 supports catalogs, namespaces, Iceberg and generic tables as whole objects, and top-level columns on Iceberg tables.
   
   Views, generic-table columns, nested fields, and multi-value assignments are deferred. Tags classify resources only; they do not grant or deny access in v1. Future Policy or external-authorizer integration remains separate from this contract.
   
   ## Scope and delivery plan
   
   This PR lands the public Tag API contract and generated models. It is the first of four independently reviewable PRs:
   
   1. **API contract:** define the Tag APIs, wire them into the catalog specification, and generate the models.
   2. **Tag definitions:** implement definition CRUD, authorization, events, and backend coverage.
   3. **Assignments:** implement assignment and unassignment, including durable storage, column resolution, and detach-all deletion.
   4. **Reads and discovery:** implement direct and inherited Tag reads, reverse lookup with pagination, and hiding assignments whose targets no longer exist.
   
   These PRs will be reviewed and merged in order, with each PR adding one complete functional slice on top of the previous one.
   
   A separately tracked follow-up will add grants on Tag resources to the management APIs. This is distinct from using Tags to grant or deny access to tagged objects, which remains out of scope for v1.
   
   This PR intentionally contains no REST resource, service implementation, persistence changes, or behavioral tests. Landing the API contract separately gives clients and implementations a stable contract for the following slices.
   
   
   ## Validation
   
   * OpenAPI generation was inspected for the generated request model shapes and nullable update behavior.
   * The source and bundled specifications were compared after rebundling.
   * Full CI is pending on this PR.
   
   ## Discussion and review
   
   * [[Design: Polaris Tag Spec](https://docs.google.com/document/d/1rIJGzcsmGhfrBiRXPac51hr-jeJuuKQQBYjgBdOb9-k/edit?usp=sharing)](https://docs.google.com/document/d/1rIJGzcsmGhfrBiRXPac51hr-jeJuuKQQBYjgBdOb9-k/edit?usp=sharing)
   * [[Dev-list design discussion](https://lists.apache.org/thread/n2p8rvgno67tv25b3f3kpwlj7bzt0421)](https://lists.apache.org/thread/n2p8rvgno67tv25b3f3kpwlj7bzt0421)
   * [[Bundled specification in Swagger Editor](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/flyingImer/polaris/d2e0bfffa53d4dbf1fd5b3d6ab7296d49a0d3066/spec/generated/bundled-polaris-catalog-service.yaml)](https://editor-next.swagger.io/?url=https://raw.githubusercontent.com/flyingImer/polaris/d2e0bfffa53d4dbf1fd5b3d6ab7296d49a0d3066/spec/generated/bundled-polaris-catalog-service.yaml)
   
   ## AI-assisted contribution
   
   AI assistance was used for consistency review. I reviewed the final API contract and diff and take full responsibility for the contribution.
   
   ## Checklist
   
   * [x] 🛡️ Don't disclose security issues! (contact [[security@apache.org](mailto:security@apache.org)](mailto:security@apache.org))
   * [x] 🔗 Clearly explained why the changes are needed, with design and dev-list links
   * [ ] 🧪 Added/updated tests with good coverage, or manually tested (PR CI pending)
   * [] 💡 Added comments for complex logic (not applicable to this spec-only PR)
   * [] 🧾 Updated `CHANGELOG.md` (not needed until runtime support is added)
   * [] 📚 Updated documentation in `site/content/in-dev/unreleased` (not needed until runtime support is added)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4043972329


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:

Review Comment:
   With only a name, I agree that a string would be enough. Given the stable ID addition discussed in the other thread, I’d keep TagIdentifier to carry both name and id in list results and object-tag responses. That lets clients identify the tag without returning its full definition.
   
   Requests will continue to address tags by name. This response object won’t introduce ID-based addressing.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098265476


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape

Review Comment:
   👍



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on

Review Comment:
   Hmmm, yea, the bodyless response isn’t the cause of the uncertainty. I’ll shorten this to the useful retry behavior: after a successful rename, the old name may return 404, while a recognized retry returns 204 without renaming again.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098340429


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'

Review Comment:
   The body already uses one shared schema, PolarisErrorResponse. I kept separate response components to reuse the status-specific error descriptions and headers across endpoints. I’d prefer to retain that distinction so each response stays explicit about its error types and retry behavior.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4020980714


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, named by an assignment request. The server never
+        guesses a target kind: a field combination that does not match `type` is rejected.
+
+        The fields per target type are:
+
+        | type | path | column |
+        |------|------|--------|
+        | catalog | absent or empty | absent or empty |
+        | namespace | one or more namespace levels | absent or empty |
+        | table-like | namespace levels followed by the table name | absent or empty |
+        | column | namespace levels followed by the containing table name | one top-level column name |
+
+        Each namespace level must be non-empty and must not contain U+001F, the character the
+        getObjectTags query uses to separate levels. A JSON body sends the original names as separate
+        strings without URI encoding, and U+001F inside a level returns 400 BadRequestException. The
+        rule covers every namespace level, including the levels that locate a table or a column.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            A list representing the hierarchical path to the target, ordered from the namespace level down
+            to the entity.
+
+            If the target is catalog, the path should be either empty or not set.
+
+            Each namespace level must be non-empty and must not contain U+001F; a violation returns
+            400 BadRequestException.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For column targets only, the name of one top-level column in the table named by path. More than
+            one column segment is invalid in v1.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The selected values. The v1 server requires exactly one member, and it must appear in the
+            definition's current allowed-values list. The list shape leaves room for later value forms.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag of the queried target, as returned by getObjectTags.
+
+        - **tag:** The tag definition name.
+        - **values:** The selected values. v1 returns exactly one item.
+        - **apply-method:** How the classification applies to the target being read. v1 defines two
+          well-known values: `MANUAL` (the ordinary assignment operation created this direct assignment) and
+          `INHERITED` (the winning assignment is stored on a parent target). The field is an open string:
+          implementations may return other documented direct methods, and clients must accept unknown
+          values.
+        - **assigned-at:** The target that stores the winning assignment. For a direct result this is the
+          queried target; for an inherited result it is the parent that stores the assignment.
+      required:
+        - tag
+        - values
+        - apply-method
+        - assigned-at
+      properties:
+        tag:
+          $ref: '#/components/schemas/TagIdentifier'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "MANUAL"
+        assigned-at:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    GetObjectTagsResponse:
+      type: object
+      required:
+        - object-tags
+      properties:
+        object-tags:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/ObjectTag'
+
+    TaggedObject:
+      type: object
+      description: |
+        One direct assignment of the named tag definition, as returned by listObjectsByTag. apply-method is
+        never `INHERITED` in this response.
+      required:
+        - target
+        - values
+        - apply-method
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "MANUAL"
+
+    ListObjectsByTagResponse:
+      type: object
+      required:
+        - objects
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        objects:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TaggedObject'
+
+  responses:
+    CreateTagResponse:
+      description: Tag definition result after creating a tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    LoadTagResponse:
+      description: Tag definition result when loading a tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    UpdateTagResponse:
+      description:
+        Response used when a tag definition is successfully updated
+
+        The updated definition is returned in the tag field
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    ListTagsResponse:
+      description: a list of tag definition identifiers
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListTagsResponse'
+          examples:
+            ListTagsResponseNonEmpty:
+              $ref: '#/components/examples/ListTagsNonEmptyExample'
+            ListTagsResponseEmpty:
+              $ref: '#/components/examples/ListTagsEmptyExample'
+
+    GetObjectTagsResponse:
+      description: The direct or effective tags of the queried target
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GetObjectTagsResponse'
+          examples:
+            GetObjectTagsResponseEffective:
+              $ref: '#/components/examples/GetObjectTagsEffectiveExample'
+
+    ListObjectsByTagResponse:
+      description: A page of targets that carry a direct assignment of the named tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListObjectsByTagResponse'
+          examples:
+            ListObjectsByTagResponseNonEmpty:
+              $ref: '#/components/examples/ListObjectsByTagNonEmptyExample'
+
+  examples:
+    NoSuchTagError:
+      summary: The requested tag definition does not exist
+      value: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTagException",
+          "code": 404
+        }
+      }
+
+    TagAlreadyExistsError:
+      summary: A tag definition with the requested name already exists
+      value: {
+        "error": {
+          "message": "A tag definition with the given name already exists in the catalog",
+          "type": "AlreadyExistsException",

Review Comment:
   Agreed. I'll document the error types in OpenAPI so clients can distinguish cases sharing the same HTTP status.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4031826933


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through

Review Comment:
   Why do we need a target type? I think the majority use cases do not limit the type of target. A tag by default should apply to table/view/ns/catalog freely by default, if not always.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted

Review Comment:
   Could we make tag rename a separate operation, following IRC's `POST /tables/rename` pattern?
   
   Here, changing `name` also changes the URL used to address the tag. If the rename succeeds but the response is lost, retrying the update against the old name can return 404. Looking up the new name is not enough to establish what happened, since it could belong to an unrelated tag.
   
   I'd prefer a dedicated `POST /tags/rename` with explicit source and destination names, while keeping `current-tag-version` as the concurrency check. That gives the operation a stable URL and makes the intent clearer. 
   
   Question: do we support idempotency keys in creation/update? A separate endpoint alone would not make replay safe.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:

Review Comment:
   Could we expose a stable tag ID, preferably a server-generated UUID, in `Tag` and `TagIdentifier`? This would let clients such as engines(e.g., Spark) and other clients(e.g., Python clients) tell whether they are referring to the same tag, even after a rename. The ID should stay unchanged across renames and updates, while deleting and recreating a tag should produce a new ID even if the name is reused.
   
   This would also help with synchronization between catalogs: a sync tool could track the source tag by ID, recognize renames, and map it to the corresponding destination tag instead of relying on matching names. We can leave the decision about preserving IDs versus maintaining a source-to-destination mapping to the sync design.
   
   Tag ID is generally exposed across different systems [1][2].  cc @singhpk234 
   
   1. Snowflake exposes `TAG_ID` in its [TAGS view](https://docs.snowflake.com/en/sql-reference/account-usage/tags). The version token would continue to serve as the concurrency check.
   2. Databricks tag ID https://docs.databricks.com/api/tag-policies/v1/tag-policy



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1

Review Comment:
   do we need to specify `minLength` here?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, named by an assignment request. The server never
+        guesses a target kind: a field combination that does not match `type` is rejected.
+
+        The fields per target type are:
+
+        | type | path | column |
+        |------|------|--------|
+        | catalog | absent or empty | absent or empty |
+        | namespace | one or more namespace levels | absent or empty |
+        | table-like | namespace levels followed by the table name | absent or empty |
+        | column | namespace levels followed by the containing table name | one top-level column name |

Review Comment:
   The table may not render well in the openAPI spec.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.

Review Comment:
   same here



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:

Review Comment:
   Do we need wrap a tag name with another schema called `TagIdentifier`? For places referring to a tag name, we should just use tag name instead.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and

Review Comment:
   I think we should relax this requirement by removing the `REQUIRED`.  It's a OK to create a tag without allowed-values even if we don't want to support that use cases. Making it optional allow that use case in the future, without introducing a v2 endpoint.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null

Review Comment:
   Could we make this a replacement of the complete editable tag definition, with renaming handled separately?
   
   The current per-field rules are hard to follow: omitted fields stay unchanged, `allowed-values: null` is ignored, and `target-types` is accepted only when null. It's also unclear how a client clears `comment`.
   
   For a small definition, I'd prefer a simple read/modify/write flow: send the desired values for all editable fields, with an explicit way to clear optional values, and use `current-tag-version` to prevent concurrent changes from being overwritten. `name` would be handled by a separate rename operation. 
   
   This would make the request describe the resulting definition without requiring clients to remember a different omitted/null rule for each field.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.

Review Comment:
   I'm not sure we need lengthy comment here. The tag creation part has covered all of them. Maybe we can keep it lean like this
   ```suggestion
           A tag definition
   ```



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must

Review Comment:
   ```suggestion
           The request body carries a structured target and the selected values. The values list must
   ```
   
   the whole doc is with v1, we dont' have to specify v1 here.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1

Review Comment:
   Same here



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, named by an assignment request. The server never
+        guesses a target kind: a field combination that does not match `type` is rejected.
+
+        The fields per target type are:
+
+        | type | path | column |
+        |------|------|--------|
+        | catalog | absent or empty | absent or empty |
+        | namespace | one or more namespace levels | absent or empty |
+        | table-like | namespace levels followed by the table name | absent or empty |
+        | column | namespace levels followed by the containing table name | one top-level column name |
+
+        Each namespace level must be non-empty and must not contain U+001F, the character the
+        getObjectTags query uses to separate levels. A JSON body sends the original names as separate
+        strings without URI encoding, and U+001F inside a level returns 400 BadRequestException. The
+        rule covers every namespace level, including the levels that locate a table or a column.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            A list representing the hierarchical path to the target, ordered from the namespace level down
+            to the entity.
+
+            If the target is catalog, the path should be either empty or not set.
+
+            Each namespace level must be non-empty and must not contain U+001F; a violation returns
+            400 BadRequestException.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For column targets only, the name of one top-level column in the table named by path. More than
+            one column segment is invalid in v1.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The selected values. The v1 server requires exactly one member, and it must appear in the
+            definition's current allowed-values list. The list shape leaves room for later value forms.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag of the queried target, as returned by getObjectTags.
+
+        - **tag:** The tag definition name.
+        - **values:** The selected values. v1 returns exactly one item.
+        - **apply-method:** How the classification applies to the target being read. v1 defines two
+          well-known values: `MANUAL` (the ordinary assignment operation created this direct assignment) and
+          `INHERITED` (the winning assignment is stored on a parent target). The field is an open string:
+          implementations may return other documented direct methods, and clients must accept unknown

Review Comment:
   Do we need to distinguish inherited or not?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are

Review Comment:
   same here



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on PR #5366:
URL: https://github.com/apache/polaris/pull/5366#issuecomment-6530093855

   @flyrain @dimas-b could you please take another pass?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4426793060


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'

Review Comment:
   Updated: I agree these fields need bounded resource usage, but I’m hesitant to put fixed description-length and allowed-values count limits into the public API contract without a portability requirement that justifies those specific numbers.
   
   I’d prefer to leave those limits implementation-configurable, while documenting that servers may reject requests exceeding their resource limits with a clear 4xx error, rather than silently truncating them.
   
   This also leaves room for future federated metadata, although federation imports may use a separate internal path and need not be constrained by the native create API.
   
   The 256-character TagName limit is already in the latest spec, and leading hyphens are explicitly allowed.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253033412


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes. The limit is measured on the decoded value in UTF-8
+            bytes: JSON escaping does not count toward it, and it does not prescribe how the server
+            represents the string internally. A longer value returns 400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement, or of a definition renamed into that name. A new
+            no-op update still has to match the current token. Where an already completed update or rename
+            is recognized from an Idempotency-Key, that recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes. The limit is
+            measured on the decoded value in UTF-8 bytes: JSON escaping does not count toward it, and it
+            does not prescribe how the server represents the string internally. A longer value returns
+            400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes. The limit
+            is measured on the decoded value in UTF-8 bytes: JSON escaping does not count toward it, and it
+            does not prescribe how the server represents the string internally. A longer value returns
+            400 BadRequest.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, update, or
+            newly committed rename.
+            Send it back unchanged. Do not parse, order, or increment it. The token identifies the
+            definition as well as its revision: a token from a definition that was deleted and recreated
+            under the same name, or from a definition whose name another definition was renamed into, is
+            refused as a version mismatch.
+
+    RenameTagRequest:
+      type: object
+      description: |
+        A rename of one definition. The source keeps its identity, its `id`, its assignments and its values;
+        only the name changes, and the version token changes on success.
+      required:
+        - source
+        - destination
+        - current-tag-version
+      properties:
+        source:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The current name of the definition to rename. It must exist in the resolved catalog.
+        destination:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The new name. It must match the TagName pattern, must not already name a definition in the
+            catalog, and must differ from `source`.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The source definition's current version token, as returned by a previous create, load,
+            update, or newly committed rename. Send it back unchanged. Do not parse, order, or increment
+            it. The token identifies the definition as well as its revision: a token from a definition
+            that was deleted and recreated under the same name, or from a definition whose name another
+            definition was renamed into, is
+            refused as a version mismatch.
+
+    RenameTagResponse:
+      type: object
+      description: |
+        The result of a request that performed a rename. A recognized retry returns 204 with no body
+        instead. This response contains the version produced by the committed rename, not a token
+        fetched by a later read. Concurrent changes may make it stale before the caller receives it.
+      required:
+        - version
+      properties:
+        version:
+          type: string
+          minLength: 1
+          description: |
+            The renamed definition's opaque version token. Send it back unchanged as
+            `current-tag-version` on a subsequent update or rename. Do not parse, order, or increment it.
+          example: "rev-c"
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '#/components/schemas/NextPageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, supplied by an assignment write or returned by
+        a read. A field combination that does not match `type` is invalid. The kind is required and never
+        inferred, so an incomplete address cannot select a broader target.
+
+        The fields per target type are:
+
+        - `CATALOG`: `path` absent or empty, `column` absent or empty.
+        - `NAMESPACE`: `path` is one or more namespace levels, `column` absent or empty.
+        - `TABLE`: `path` is the namespace levels followed by the table name, `column` absent or empty.
+        - `VIEW`: `path` is the namespace levels followed by the view name, `column` absent or empty.
+        - `COLUMN`: `path` is the namespace levels followed by the containing table name, and `column`
+          is an array containing exactly one non-empty top-level column name.
+
+        A supplied `path` or `column` must be a JSON array of strings, never null. Every `path` member
+        must be non-empty.
+
+        Each namespace level must be non-empty and must not contain U+001F, the character the query
+        parameters use to separate levels. A JSON body carries the original names as separate strings
+        without URI encoding. The rule covers every namespace level, including the levels that locate a
+        table or a column.
+
+        A column name is one literal string, even when it contains dots, slashes, plus signs or percent
+        sequences. In particular, `column: ["."]` and `column: [".."]` name literal top-level columns.
+        No path normalization, percent decoding or dot splitting is applied to JSON names. Existing
+        catalog and schema naming rules still apply.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            A list representing the hierarchical path to the target, ordered from the namespace level down
+            to the entity.
+
+            If the target is catalog, the path should be either empty or not set.
+
+            Each namespace level must be non-empty and must not contain U+001F; a violation returns
+            400 BadRequest.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For column targets only, the name of one top-level column in the table named by path. More than
+            one column segment is invalid.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      description: |
+        Set a direct assignment on one target. `target` and `values` are required and non-null.
+        The values list must contain exactly one allowed value; an absent, null or empty list never
+        removes an assignment.
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The v1 server requires exactly one member. It must appear in the definition's current
+            values list and is limited to 2000 bytes. The limit is measured on the decoded value in
+            UTF-8 bytes: JSON escaping does not count toward it, and it does not prescribe how the
+            server represents the string internally. A longer value returns 400 BadRequest.
+            The list shape leaves room for later value forms.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      description: |
+        Remove a direct assignment from one target. `target` is required and non-null. A `values`
+        field must not be supplied, including null or an empty array; the operation rejects it with
+        400 BadRequest before applying any change.
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag of the queried target, as returned by getObjectTags.
+
+        - **tag:** The tag definition name.

Review Comment:
   Good catch, I’ll update the description to reflect the stable id and current name.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4124914301


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds
+        that operation's privilege. A recognized createTag or updateTag retry answers 200 with the
+        definition's current state: not the original response, and not the state the original request wrote
+        if the definition has changed since. A recognized renameTag retry answers 204 without renaming
+        again, even after later renames, and the server never renames a definition back to satisfy a retry.
+        Recognition happens before the supplied `current-tag-version` is compared with the definition's
+        current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        The server records the key, not the request, so reusing one key with different arguments is a client
+        error: the outcome is undefined and no conflict response is promised. The server does not replay the
+        original response body.
+
+        Recognition ends when the definition is deleted. A request the server cannot match to a live key on
+        a live definition follows the ordinary path, with the usual name lookup, authorization and version
+        check and the errors those produce.
+
+        A definition holds a bounded number of live keys. When that set is full, a write that would record
+        another key is rejected with 503 ServiceUnavailable and a Retry-After header rather than evicting a
+        live key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none of
+        them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          minimum: 400
+          maximum: 600
+          description: HTTP response code
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes when encoded as UTF-8. A longer value returns
+            400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement. A new no-op update still has to match the current
+            token. Where an already completed update or rename is recognized from an Idempotency-Key, that
+            recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    RenameTagRequest:
+      type: object
+      description: |
+        A rename of one definition. The source keeps its identity, its `id`, its assignments and its values;
+        only the name changes, and the version token changes on success.
+      required:
+        - source
+        - destination
+        - current-tag-version
+      properties:
+        source:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The current name of the definition to rename. It must exist in the resolved catalog.
+        destination:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The new name. It must match the TagName pattern, must not already name a definition in the
+            catalog, and must differ from `source`.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The source definition's current version token, as returned by a previous create, load, or
+            update. Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'

Review Comment:
   Indeed, if we make `current-tag-version` an API concern, we will need response wrappers.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4124949617


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'

Review Comment:
   Since error codes are defined only inside documentation text, we might as well list them in the endpoint description :thinking: 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "laskoviymishka (via GitHub)" <gi...@apache.org>.
laskoviymishka commented on PR #5366:
URL: https://github.com/apache/polaris/pull/5366#issuecomment-6313615319

   Following up on the dev-list thread on labels as a projection over Tags ([link](https://lists.apache.org/thread.html/ls38t86m9mrpdmcqfmqmjtg768dny8tn)). 
   
   Highlighting a need from the Tags API if Polaris later consumes labels from a federated IRC catalog. None of this needs to be implemented in v1, but I’d like to avoid making it impossible.
   
   The model I have in mind is simple: foreign labels come into Polaris as read-only tags attributed to the source catalog, and stay separate from native Polaris tags.
   
   A few things this probably needs:
   
   1. Some origin on reads, e.g. `NATIVE` vs external. v1 can just return `NATIVE`, and clients should tolerate unknown values.
   2. A way to represent tags that are managed elsewhere and can’t be changed through this API. Something like `TagManagedExternally` is enough.
   3. Native and foreign tags with the same name need to coexist. Today that looks blocked by global name uniqueness / one assignment per target+definition.
   
   Two possible shapes:
   - put origin on the definition and scope name uniqueness by origin
   - put origin on the assignment, so identity becomes `(target, definition, origin)`
   
   I’d prefer the first one since it keeps the assignment model unchanged. @flyingImer what's your preference here?
   
   Federation endpoints/import logic/IRC changes are out of scope here. I just don’t want v1 to bake in the assumption that one tag name can only ever have one origin.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4067137871


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   Fair point, build wiring shouldn’t decide the API paths. Could we continue the API-root discussion on dev@ without blocking this PR?
   
   My preference is to proceed under the current catalog root alongside policies and generic tables. There are still several implementation PRs ahead, so we can revisit the path before release. If the decision comes later, we could introduce a separate root while retaining the current paths for compatibility. That has a maintenance cost, but keeps a migration path open.
   
   Would you be comfortable proceeding on that basis?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4021086378


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no

Review Comment:
   On reconsideration, I'll remove this unsupported case from the OpenAPI spec and design doc. Detach-all is part of the API contract, and physical cleanup may be deferred while preserving the all-or-nothing visible result. We haven't identified a concrete case that needs a separate 422 response here.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4031511180


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"

Review Comment:
   `/ \ : * ? " < > | # +` and backtick are not allowed chars of a NS, see here, https://github.com/apache/polaris/blob/dc42d99f3061ec7c5bcbae06dd27b8186ca833dc/runtime/service/src/main/java/org/apache/polaris/service/catalog/validation/EntityNameValidator.java#L79



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r3983387858


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   Thanks, this one is worth pinning down before I touch the paths. One correction first: today the base is /api/catalog/polaris/v1/{prefix}/…, not /api/polaris/v1/…. Policies and generic tables use the same base, and the Iceberg REST API is /api/catalog/v1/{prefix}/…, so every catalog-scoped API currently sits under /api/catalog.
   
   I can read your proposal as one of two shapes, and they cost very different things:
   
   1.  /api/catalog/tags/v1/{prefix}/…: tags gets its own segment and its own version inside the catalog service. Cheap (this PR plus the route constants in the follow-ups), but it adds a third pattern next to /api/catalog/v1 and /api/catalog/polaris/v1.
   2.  /api/tags/v1/{prefix}/…: a new top-level API family next to /api/catalog and /api/management. That needs its own spec document and generator wiring, and it moves a catalog-scoped API out of the catalog service.
   
   We went over this on the design doc in August and I kept tags under the catalog API for consistency with policies and generic tables. If the project wants per-extension roots, I'd rather policies and generic tables move with it than have tags be the one exception. Which of the two did you have in mind, and should this PR lead that change or follow a project-wide decision?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098357565


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds
+        that operation's privilege. A recognized createTag or updateTag retry answers 200 with the
+        definition's current state: not the original response, and not the state the original request wrote
+        if the definition has changed since. A recognized renameTag retry answers 204 without renaming
+        again, even after later renames, and the server never renames a definition back to satisfy a retry.
+        Recognition happens before the supplied `current-tag-version` is compared with the definition's
+        current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        The server records the key, not the request, so reusing one key with different arguments is a client
+        error: the outcome is undefined and no conflict response is promised. The server does not replay the
+        original response body.
+
+        Recognition ends when the definition is deleted. A request the server cannot match to a live key on
+        a live definition follows the ordinary path, with the usual name lookup, authorization and version
+        check and the errors those produce.
+
+        A definition holds a bounded number of live keys. When that set is full, a write that would record
+        another key is rejected with 503 ServiceUnavailable and a Retry-After header rather than evicting a
+        live key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none of
+        them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          minimum: 400
+          maximum: 600
+          description: HTTP response code
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes when encoded as UTF-8. A longer value returns
+            400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement. A new no-op update still has to match the current
+            token. Where an already completed update or rename is recognized from an Idempotency-Key, that
+            recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    RenameTagRequest:
+      type: object
+      description: |
+        A rename of one definition. The source keeps its identity, its `id`, its assignments and its values;
+        only the name changes, and the version token changes on success.
+      required:
+        - source
+        - destination
+        - current-tag-version
+      properties:
+        source:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The current name of the definition to rename. It must exist in the resolved catalog.
+        destination:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The new name. It must match the TagName pattern, must not already name a definition in the
+            catalog, and must differ from `source`.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The source definition's current version token, as returned by a previous create, load, or
+            update. Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'

Review Comment:
   Fair point. With version included in Tag, the wrapper currently adds no information. I’m happy to return Tag directly for create, load and update. If we decide to move version outside Tag in the other thread, we’ll need to account for that in the final response shape.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4198643006


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:

Review Comment:
   The rename success responses are asymmetric: a fresh rename returns `200` with `RenameTagResponse {version}`, while a recognized retry returns `204` with no body, so the client has to reload to get a token. Create/update return `200` with the full `Tag` in both cases.
   
   Could we pick one shape? Either always `204` (matching IRC `renameTable`), or always `200` with the full `Tag` (matching create/update). 



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag

Review Comment:
   This refers to "the tag validation row" and "the shared required-field row", but there's no such table in this spec. It looks carried over from the design doc. Could we state the rule directly?
   
   Also, a missing `values` returns `BadRequest` while a missing `description` returns `ValidationError`. Both are missing required fields, so I'd expect the same error type for both.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.

Review Comment:
   `InvalidIdempotencyKey` is listed here, but `dropTag` doesn't declare the `Idempotency-Key` parameter. Either declare it (as assign/unassign describe accepting and ignoring it), or drop this error type.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'

Review Comment:
   Can we not cause fragmentation in this spec? Instead, can we be consistent with notification/semantic-model/policy? If we were trying to introduce the Polaris own catalog prefix concept, I'd suggest do it for all as a followup. WDYT?
   
   ```suggestion
         - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
   ```



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from

Review Comment:
   Non-blocking: the spec is ~2250 lines, and a fair amount of it describes implementation behavior rather than the API contract, for example physical cleanup of assignment rows, how the shared handler inspects headers, work budgets / candidates examined, native writes outside this API, and the idempotency key-count bound. These make the spec hard to review and tie the implementation down. Some paragraphs are also duplicated verbatim (e.g. the identity/rename paragraphs in assign and unassign). Could we trim it a bit?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |

Review Comment:
   Following up on my earlier table-rendering comment: `TagAttachmentTarget` now uses a list. Same rendering concern. Could these be lists too?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:

Review Comment:
   Just noting that the assignment write style differs from the policy API: policy uses `PUT .../mappings` to attach and `POST .../mappings` to detach, while this uses `POST /assign` and `POST /unassign`. I'm fine either way, but could we mention the rationale in the PR description?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through

Review Comment:
   I'd still suggest we drop target-types from v1. Here's my reasoning:
   
   1. I'm not sure the "skip some levels" use case is valid. It brings more problem than benefits.The inheritance filtering is risky for governance. Say sales carries a `pii=true` tag scoped to NAMESPACE and COLUMN. An engine that checks the table's effective tags sees nothing, while every column of that table shows `pii`. Code that enforces rules at table level will quietly miss it. Classification usually needs "everything under this inherits it", not "skips some levels".
   
   2. Immutability makes mistakes expensive. target-types can't be changed after creation. If a tag is scoped too narrowly, the only fix is to drop it with detach-all and recreate it. That loses every assignment and gives the tag a new id, the very identity we added so clients can track tags over time.
   
   3. The default gets outdated. Leaving the field out stores the kinds that exist today, and later kinds don't extend existing definitions. Most users won't set this field, so most tags would silently fail to apply to new kinds such as functions or nested fields.
   
   4. It adds complexity across the API. Assign validation, effective-read filtering, an extra error type, the create-only rejection on update, and the matching tests. That's a lot for a feature whose main use, restricting where a tag can be assigned, a client or an admin process can handle.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to

Review Comment:
   This is different from any other entity(table/view/policy, etc) pagination in Polaris, which is really confusing for users. Can we be consistent?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400

Review Comment:
   Nit: this line is 136 characters; please rewrap (L923 is 148 as well).



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes. The limit is measured on the decoded value in UTF-8
+            bytes: JSON escaping does not count toward it, and it does not prescribe how the server
+            represents the string internally. A longer value returns 400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement, or of a definition renamed into that name. A new
+            no-op update still has to match the current token. Where an already completed update or rename
+            is recognized from an Idempotency-Key, that recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes. The limit is
+            measured on the decoded value in UTF-8 bytes: JSON escaping does not count toward it, and it
+            does not prescribe how the server represents the string internally. A longer value returns
+            400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes. The limit
+            is measured on the decoded value in UTF-8 bytes: JSON escaping does not count toward it, and it
+            does not prescribe how the server represents the string internally. A longer value returns
+            400 BadRequest.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, update, or
+            newly committed rename.
+            Send it back unchanged. Do not parse, order, or increment it. The token identifies the
+            definition as well as its revision: a token from a definition that was deleted and recreated
+            under the same name, or from a definition whose name another definition was renamed into, is
+            refused as a version mismatch.
+
+    RenameTagRequest:
+      type: object
+      description: |
+        A rename of one definition. The source keeps its identity, its `id`, its assignments and its values;
+        only the name changes, and the version token changes on success.
+      required:
+        - source
+        - destination
+        - current-tag-version
+      properties:
+        source:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The current name of the definition to rename. It must exist in the resolved catalog.
+        destination:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The new name. It must match the TagName pattern, must not already name a definition in the
+            catalog, and must differ from `source`.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The source definition's current version token, as returned by a previous create, load,
+            update, or newly committed rename. Send it back unchanged. Do not parse, order, or increment
+            it. The token identifies the definition as well as its revision: a token from a definition
+            that was deleted and recreated under the same name, or from a definition whose name another
+            definition was renamed into, is
+            refused as a version mismatch.
+
+    RenameTagResponse:
+      type: object
+      description: |
+        The result of a request that performed a rename. A recognized retry returns 204 with no body
+        instead. This response contains the version produced by the committed rename, not a token
+        fetched by a later read. Concurrent changes may make it stale before the caller receives it.
+      required:
+        - version
+      properties:
+        version:
+          type: string
+          minLength: 1
+          description: |
+            The renamed definition's opaque version token. Send it back unchanged as
+            `current-tag-version` on a subsequent update or rename. Do not parse, order, or increment it.
+          example: "rev-c"
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '#/components/schemas/NextPageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, supplied by an assignment write or returned by
+        a read. A field combination that does not match `type` is invalid. The kind is required and never
+        inferred, so an incomplete address cannot select a broader target.
+
+        The fields per target type are:
+
+        - `CATALOG`: `path` absent or empty, `column` absent or empty.
+        - `NAMESPACE`: `path` is one or more namespace levels, `column` absent or empty.
+        - `TABLE`: `path` is the namespace levels followed by the table name, `column` absent or empty.
+        - `VIEW`: `path` is the namespace levels followed by the view name, `column` absent or empty.
+        - `COLUMN`: `path` is the namespace levels followed by the containing table name, and `column`
+          is an array containing exactly one non-empty top-level column name.
+
+        A supplied `path` or `column` must be a JSON array of strings, never null. Every `path` member
+        must be non-empty.
+
+        Each namespace level must be non-empty and must not contain U+001F, the character the query
+        parameters use to separate levels. A JSON body carries the original names as separate strings
+        without URI encoding. The rule covers every namespace level, including the levels that locate a
+        table or a column.
+
+        A column name is one literal string, even when it contains dots, slashes, plus signs or percent
+        sequences. In particular, `column: ["."]` and `column: [".."]` name literal top-level columns.
+        No path normalization, percent decoding or dot splitting is applied to JSON names. Existing
+        catalog and schema naming rules still apply.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            A list representing the hierarchical path to the target, ordered from the namespace level down
+            to the entity.
+
+            If the target is catalog, the path should be either empty or not set.
+
+            Each namespace level must be non-empty and must not contain U+001F; a violation returns
+            400 BadRequest.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For column targets only, the name of one top-level column in the table named by path. More than
+            one column segment is invalid.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      description: |
+        Set a direct assignment on one target. `target` and `values` are required and non-null.
+        The values list must contain exactly one allowed value; an absent, null or empty list never
+        removes an assignment.
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The v1 server requires exactly one member. It must appear in the definition's current
+            values list and is limited to 2000 bytes. The limit is measured on the decoded value in
+            UTF-8 bytes: JSON escaping does not count toward it, and it does not prescribe how the
+            server represents the string internally. A longer value returns 400 BadRequest.
+            The list shape leaves room for later value forms.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      description: |
+        Remove a direct assignment from one target. `target` is required and non-null. A `values`
+        field must not be supplied, including null or an empty array; the operation rejects it with
+        400 BadRequest before applying any change.
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag of the queried target, as returned by getObjectTags.
+
+        - **tag:** The tag definition name.

Review Comment:
   Nit: `tag` is now a `TagIdentifier` (id + name), not just the definition name.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.

Review Comment:
   nit:
   ```suggestion
           Creates a tag definition within the catalog.
   ```



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the

Review Comment:
   ```suggestion
             inheritance. Omitting the field selects every target kind, and the response returns the
   ```



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:

Review Comment:
   Since `allowed-values` was renamed to `values`, the same field name means two things: the permitted set on a definition, and the selected value(s) on an assignment (`AssignTagRequest.values`, `ObjectTag.values`). I'd suggest renaming this one back to `allowed-values` for clarity.
   
   If we keep `values`, the examples still use the old name (`AllowedValuesInvalidError`, `InvalidAllowedValues`), and `AllowedValuesInvalidError` and `ValuesInvalidError` carry the same message.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'

Review Comment:
   Should `TagName` have a `maxLength`? Right now there's no upper bound. The pattern also allows a leading hyphen (e.g. `-foo`); is that intended?
   
   Similarly, `description` has no max length and the definition's `values` list has no cap on how many entries it holds (only per-value size is bounded).



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.

Review Comment:
   Later version means v2 endpoint or any compatible changes of v1 endpoint?



##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -5296,6 +7111,306 @@ components:
       required: true
       schema:
         $ref: '#/components/schemas/SemanticModelName'
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.

Review Comment:
   Can we use an array instead? So that we can avoid separator?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'

Review Comment:
   [Same as](https://github.com/apache/polaris/pull/5366/changes#r4198890769). We should avoid fragmentation as much as possible. I'm OK also if we want to speedup this PR by dropping pagination.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes. The limit is measured on the decoded value in UTF-8
+            bytes: JSON escaping does not count toward it, and it does not prescribe how the server
+            represents the string internally. A longer value returns 400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement, or of a definition renamed into that name. A new
+            no-op update still has to match the current token. Where an already completed update or rename
+            is recognized from an Idempotency-Key, that recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes. The limit is
+            measured on the decoded value in UTF-8 bytes: JSON escaping does not count toward it, and it
+            does not prescribe how the server represents the string internally. A longer value returns
+            400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |

Review Comment:
   Following up on the earlier "same here" comment: this still largely repeats the `updateTag` operation description. Could it be trimmed to a one-liner like `Tag`?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,

Review Comment:
   Following up on the earlier "v1" comment: a few remain, e.g. "The v1 server requires" here, plus L591, L708, L1417, L1741, L1766–1768, and the example error messages "not supported in v1" / "v1 supports exactly one selected value". "Every v1 target kind" (L47) carries meaning, but the rest could drop "v1".



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253061455


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.

Review Comment:
   I’ll declare the optional Idempotency-Key header on dropTag, assignTag, and unassignTag, and make clear that none of them recognizes completed requests by key. InvalidIdempotencyKey will remain because the shared handler can reject a malformed header when enabled.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4125843555


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'

Review Comment:
   I checked this with OpenAPI Generator 7.12.0, using Polaris’s Python client settings and an additional Java client generation. Neither generated classes such as TagUnauthorizedResponse. Both use the shared PolarisErrorResponse schema, and the Python Tag API maps all error statuses to that type. So these response components don’t add classes in the configurations tested.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4427092786


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1835 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog. A definition gives a classification a name and

Review Comment:
   IIRC, we usually label fresh new APIs as "beta" and/or "experimental". Shall we do that for Tags? Apologies if I missed that label somewhere else 😅 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on PR #5366:
URL: https://github.com/apache/polaris/pull/5366#issuecomment-6529593730

   Thanks @laskoviymishka for spelling out the consumer role, and cc @jbonofre since this came from the dev@ thread. Before committing to anything in v1, I'd like to make the underlying assumptions explicit and walk through this from first principles:
   
   0. **What is the federation model for tags?** The dev@ thread seems to assume foreign tags are read-only mirrors, synced one-way from the source ("A Polaris user cannot edit them (they change only when Polaris re-syncs from the source)"). Is that agreed, or could federated tags ever be writable/written through to the source? The answer changes what origin means: in a write-through model it drives routing of writes, not just provenance on reads.
   
   1. **Given that model, does any client need `origin` at all?** Under read-only one-way sync, everything discussed so far looks enforceable by the server on its own: rejecting writes to foreign tags (`TagManagedExternally`), re-sync, authorizer filtering of imported tags, and strict collision handling on the labels projection. Is there a concrete consumer (e.g. a policy/masking engine, a UI, a sync tool) that branches on origin in the Tag API response? If not, origin can stay server-internal.
   
   2. **Even if one does, a `NATIVE` vs external flag isn't enough.** Foreign tags are described as "attributed to the source catalog", and deciding "who is asserting it" needs the actual source. So origin would have to identify which catalog/connection asserted the tag. But if foreign tags only ever live in their own federated catalog, isn't the containing catalog already that answer?
   
   3. **Even if origin names the source, is same-name native + foreign on the same target a real requirement?** With strict-by-default collisions, that state would fail `loadTable` anyway. Namespacing foreign definitions by source would avoid changing name uniqueness and assignment identity.
   
   If we can't settle these before merge, my proposed v1 fallback is a minimal, read-only, server-set structured field, open to new `type` values ("clients must tolerate unknown values"):
   
   ```yaml
   origin:
     type: NATIVE      # open string
     source: null      # reserved: reference to a Polaris entity (e.g. federated catalog/connection id), not a mutable name; unset in v1
   ```
   
   Name uniqueness and assignment identity stay unchanged until the federation model is designed. WDYT?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "laskoviymishka (via GitHub)" <gi...@apache.org>.
laskoviymishka commented on PR #5366:
URL: https://github.com/apache/polaris/pull/5366#issuecomment-6530114485

   Thanks @flyingImer, fair to start from first principles. Taking them in order:
   
   0. **Federation model:** read-only, one-way sync, as agreed on dev@. Write-through is out of scope anyway because labels are read-only on the wire. So `origin` only tells us where the tag came from; it isn't used to route writes.
   
   1. **Does a client need it?** I think yes. On dev@ we agreed that the labels projection drops provenance, while the Tag API should keep it. @flyrain's point was that he wouldn't use an attribute for governance without knowing who asserted it. A UI or audit tool that separates imported tags from native ones is the concrete consumer, so I'd keep `origin` visible on reads rather than server-only.
   
   2. **Flag vs source:** agreed that a flag alone probably isn't enough. The containing catalog doesn't fully answer it either, because owners can add native tags to federated tables. So one federated catalog can contain both native and imported tags. Your idea of a reserved source/entity reference seems to handle that.
   
   3. **Coexistence:** fair, I'll drop that ask. If foreign definitions are namespaced by source, name uniqueness and assignment identity can stay as they are. Collisions then only happen in the labels projection, where we already have strict/override behavior.
   
   +1 to the fallback.
   
   One question on placement: if foreign definitions are namespaced by source, does `origin` belong on the definition (`Tag`) and then get surfaced through `ObjectTag` / `TaggedObject` reads? Or would you keep it only on the read results?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4127490387


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2150 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.

Review Comment:
   nit: why would we discuss "valid target-types" in an "bad request" description? 🤔 



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2150 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without renaming again, on the terms the Idempotency-Key
+        parameter describes.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.

Review Comment:
   nit: it might be worth returning the "version" for the renamed tag entity:
   * to be symmetric with creates
   * to remove the need for the client to GET immediately after renaming in order to make other changes.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'

Review Comment:
   Fair enough. Since we have a sub-path in this case (`.../rename`) this is probably a moot point (from my side).



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:

Review Comment:
   Fair enough 👍 



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   If we go with query parameters here, TBH, I do not see much benefit compared to using payload JSON data. On the other hand, JSON is much easier to parse and handle encoding (which query parameters are still exposed to).
   
   IIRC, payload was the original design. Apologies about back-and-forth on this. I'll leave it up to you whether to switch to payload or keep query params.
   
   We could model assign and unassign via a flag in the payload under the same `PUT` endpoint (no `DELETE`). I thinks that would match well with resource state updates and idempotency guarantees.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253139152


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'

Review Comment:
   I kept the local definition following [Dmitri’s earlier suggestion](https://github.com/apache/polaris/pull/5366#discussion_r3980556127)⁠ to make this spec self-contained. After your feedback, I retained prefix and its existing catalog-scoping semantics, with a fuller description in the local definition.
   
   Would you prefer reusing the IRC definition and keeping the catalog-specific explanation in the Tag API description? @dimas-b, would that work for you too?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253172711


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to

Review Comment:
   You’re right that this differs from the existing APIs. I chose default pagination following [Dmitri’s earlier feedback](https://github.com/apache/polaris/pull/5366#discussion_r3980253936), so an ordinary list request stays bounded as the collection grows. pagination=false retains an explicit full-result option, subject to server limits.
   
   For this new API, I’d prefer to keep that behavior and address broader consistency across APIs separately. @dimas-b, could you weigh in so we can settle the default behavior here?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4051268193


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   I do not think technical build concerns should be a factor in deciding API paths. I believe API clarity prevails as long as it is technically achievable.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4021053765


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:

Review Comment:
   No, `TagName` already excludes `/` through its pattern. I'll make that explicit in the path parameter description.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4021099704


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target

Review Comment:
   I'll switch unassign to DELETE with no request body. I'd use query parameters to identify the target, including an explicit `target-type`, so we can reuse the namespace encoding rules already defined for object-tag reads.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4087201731


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   Fair enough 👍 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r3980198150


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   So we have these base URIs ATM:
   `https://polaris.example.com/api/catalog/v1/{prefix}/` - IRC
   `https://polaris.example.com/api/management` - Management API
   `https://polaris.example.com/api/polaris/v1/{prefix}/namespaces/{namespace}/generic-tables:` - Generic Tables
   `https://polaris.example.com/api/polaris/v1/{prefix}/tags` - Tags (this PR)
   
   Some irksome points from my POV:
   
   * Tags and Generic Tables share the `v1` path segment (they are path siblings), but they are unrelated APIs
   * `tags` is the identifying name for this API, but it is buried deep in the path. This will (potentially) make general-purpose proxies / gateways harder to configure.
   
   Proposal:
   
   `https://polaris.example.com/api/tags/v1/{prefix}/`
   
   * The tags API has a distinct prefix (can be remapped / forwarded)
   * `v1` is specific to the tags API and can evolve to the next version independently of the Generic Tables API
   * The fact that the tags API is a "Polaris" API is implicit from the base URI. Even if the base URI does not have the word `polaris` in it, the user/admin must be aware that it refers to a Polaris server and the URI prefix distinguishes it from other APIs supported by Polaris.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'

Review Comment:
   I believe it is preferable to avoid referencing IRC for pagination parameters. IRC pagination has "interesting" spec features, which had better be avoided in Polaris, IMHO.
   
   See related discussion in #5282 
   
   Proposal:
   * Clients should always expect pagination to be in effect (no "get everything in one request")
   * Client-provided page size is a hint. Servers can reduce it at their discretion.
   * There's no need to submit empty `page-token` or any `page-size` - the server will choose a default page size.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like

Review Comment:
   Sicne tag definitions can have multiple target types, is there value in using a fuzzy type of `table-like`? Why not have `table` and `view` as separate, concrete entries?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, named by an assignment request. The server never
+        guesses a target kind: a field combination that does not match `type` is rejected.
+
+        The fields per target type are:
+
+        | type | path | column |
+        |------|------|--------|
+        | catalog | absent or empty | absent or empty |
+        | namespace | one or more namespace levels | absent or empty |
+        | table-like | namespace levels followed by the table name | absent or empty |
+        | column | namespace levels followed by the containing table name | one top-level column name |
+
+        Each namespace level must be non-empty and must not contain U+001F, the character the
+        getObjectTags query uses to separate levels. A JSON body sends the original names as separate
+        strings without URI encoding, and U+001F inside a level returns 400 BadRequestException. The
+        rule covers every namespace level, including the levels that locate a table or a column.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            A list representing the hierarchical path to the target, ordered from the namespace level down
+            to the entity.
+
+            If the target is catalog, the path should be either empty or not set.
+
+            Each namespace level must be non-empty and must not contain U+001F; a violation returns
+            400 BadRequestException.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For column targets only, the name of one top-level column in the table named by path. More than
+            one column segment is invalid in v1.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The selected values. The v1 server requires exactly one member, and it must appear in the
+            definition's current allowed-values list. The list shape leaves room for later value forms.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag of the queried target, as returned by getObjectTags.
+
+        - **tag:** The tag definition name.
+        - **values:** The selected values. v1 returns exactly one item.
+        - **apply-method:** How the classification applies to the target being read. v1 defines two
+          well-known values: `MANUAL` (the ordinary assignment operation created this direct assignment) and
+          `INHERITED` (the winning assignment is stored on a parent target). The field is an open string:
+          implementations may return other documented direct methods, and clients must accept unknown
+          values.
+        - **assigned-at:** The target that stores the winning assignment. For a direct result this is the
+          queried target; for an inherited result it is the parent that stores the assignment.
+      required:
+        - tag
+        - values
+        - apply-method
+        - assigned-at
+      properties:
+        tag:
+          $ref: '#/components/schemas/TagIdentifier'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "MANUAL"
+        assigned-at:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    GetObjectTagsResponse:
+      type: object
+      required:
+        - object-tags
+      properties:
+        object-tags:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/ObjectTag'
+
+    TaggedObject:
+      type: object
+      description: |
+        One direct assignment of the named tag definition, as returned by listObjectsByTag. apply-method is
+        never `INHERITED` in this response.
+      required:
+        - target
+        - values
+        - apply-method
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "MANUAL"
+
+    ListObjectsByTagResponse:
+      type: object
+      required:
+        - objects
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        objects:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TaggedObject'
+
+  responses:
+    CreateTagResponse:
+      description: Tag definition result after creating a tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    LoadTagResponse:
+      description: Tag definition result when loading a tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    UpdateTagResponse:
+      description:
+        Response used when a tag definition is successfully updated
+
+        The updated definition is returned in the tag field
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    ListTagsResponse:
+      description: a list of tag definition identifiers
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListTagsResponse'
+          examples:
+            ListTagsResponseNonEmpty:
+              $ref: '#/components/examples/ListTagsNonEmptyExample'
+            ListTagsResponseEmpty:
+              $ref: '#/components/examples/ListTagsEmptyExample'
+
+    GetObjectTagsResponse:
+      description: The direct or effective tags of the queried target
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GetObjectTagsResponse'
+          examples:
+            GetObjectTagsResponseEffective:
+              $ref: '#/components/examples/GetObjectTagsEffectiveExample'
+
+    ListObjectsByTagResponse:
+      description: A page of targets that carry a direct assignment of the named tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListObjectsByTagResponse'
+          examples:
+            ListObjectsByTagResponseNonEmpty:
+              $ref: '#/components/examples/ListObjectsByTagNonEmptyExample'
+
+  examples:
+    NoSuchTagError:
+      summary: The requested tag definition does not exist
+      value: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTagException",
+          "code": 404
+        }
+      }
+
+    TagAlreadyExistsError:
+      summary: A tag definition with the requested name already exists
+      value: {
+        "error": {
+          "message": "A tag definition with the given name already exists in the catalog",
+          "type": "AlreadyExistsException",

Review Comment:
   We should have a well-defined list of possible error types. I believe we will eventually have more than one error case mapped to the same HTTP response code (e.g. 409). Clients need to be able to distinguish them.



##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        '200':
+          $ref: '#/components/responses/CreateTagResponse'
+        '400':
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+        '409':
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'

Review Comment:
   Let's use a Polaris type for error responses (even if it matches IRC responses field-by-field). This API != IRC and has a different evolution path.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:

Review Comment:
   `.../assignments` maybe?
   
   A "mapping" feels like something static and unchanging.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:

Review Comment:
   Why not reuse `tags/{tag-name}/assignments` for the `GET` method?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.

Review Comment:
   nit: `comment` -> `description`?



##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one

Review Comment:
   nit: this header should probably be a separate PR for clarity. Why is it not validated by CI? 🤔 



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog

Review Comment:
   same here - let's keep HTTP-level error code fairly generic and define narrow error types in the response payload.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, named by an assignment request. The server never
+        guesses a target kind: a field combination that does not match `type` is rejected.
+
+        The fields per target type are:
+
+        | type | path | column |
+        |------|------|--------|
+        | catalog | absent or empty | absent or empty |
+        | namespace | one or more namespace levels | absent or empty |
+        | table-like | namespace levels followed by the table name | absent or empty |
+        | column | namespace levels followed by the containing table name | one top-level column name |
+
+        Each namespace level must be non-empty and must not contain U+001F, the character the
+        getObjectTags query uses to separate levels. A JSON body sends the original names as separate
+        strings without URI encoding, and U+001F inside a level returns 400 BadRequestException. The
+        rule covers every namespace level, including the levels that locate a table or a column.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            A list representing the hierarchical path to the target, ordered from the namespace level down
+            to the entity.
+
+            If the target is catalog, the path should be either empty or not set.
+
+            Each namespace level must be non-empty and must not contain U+001F; a violation returns
+            400 BadRequestException.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For column targets only, the name of one top-level column in the table named by path. More than
+            one column segment is invalid in v1.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The selected values. The v1 server requires exactly one member, and it must appear in the
+            definition's current allowed-values list. The list shape leaves room for later value forms.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag of the queried target, as returned by getObjectTags.
+
+        - **tag:** The tag definition name.
+        - **values:** The selected values. v1 returns exactly one item.
+        - **apply-method:** How the classification applies to the target being read. v1 defines two
+          well-known values: `MANUAL` (the ordinary assignment operation created this direct assignment) and
+          `INHERITED` (the winning assignment is stored on a parent target). The field is an open string:
+          implementations may return other documented direct methods, and clients must accept unknown
+          values.
+        - **assigned-at:** The target that stores the winning assignment. For a direct result this is the
+          queried target; for an inherited result it is the parent that stores the assignment.
+      required:
+        - tag
+        - values
+        - apply-method
+        - assigned-at
+      properties:
+        tag:
+          $ref: '#/components/schemas/TagIdentifier'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "MANUAL"
+        assigned-at:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    GetObjectTagsResponse:
+      type: object
+      required:
+        - object-tags
+      properties:
+        object-tags:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/ObjectTag'
+
+    TaggedObject:
+      type: object
+      description: |
+        One direct assignment of the named tag definition, as returned by listObjectsByTag. apply-method is
+        never `INHERITED` in this response.
+      required:
+        - target
+        - values
+        - apply-method
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "MANUAL"
+
+    ListObjectsByTagResponse:
+      type: object
+      required:
+        - objects
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        objects:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TaggedObject'
+
+  responses:
+    CreateTagResponse:
+      description: Tag definition result after creating a tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    LoadTagResponse:
+      description: Tag definition result when loading a tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    UpdateTagResponse:
+      description:
+        Response used when a tag definition is successfully updated
+
+        The updated definition is returned in the tag field
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/LoadTagResponse'
+
+    ListTagsResponse:
+      description: a list of tag definition identifiers
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListTagsResponse'
+          examples:
+            ListTagsResponseNonEmpty:
+              $ref: '#/components/examples/ListTagsNonEmptyExample'
+            ListTagsResponseEmpty:
+              $ref: '#/components/examples/ListTagsEmptyExample'
+
+    GetObjectTagsResponse:
+      description: The direct or effective tags of the queried target
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GetObjectTagsResponse'
+          examples:
+            GetObjectTagsResponseEffective:
+              $ref: '#/components/examples/GetObjectTagsEffectiveExample'
+
+    ListObjectsByTagResponse:
+      description: A page of targets that carry a direct assignment of the named tag definition
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListObjectsByTagResponse'
+          examples:
+            ListObjectsByTagResponseNonEmpty:
+              $ref: '#/components/examples/ListObjectsByTagNonEmptyExample'
+
+  examples:
+    NoSuchTagError:
+      summary: The requested tag definition does not exist
+      value: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTagException",

Review Comment:
   I believe the word "exception" is misleading here. REST errors do not have to be related to "exceptions". Some languages do not have exceptions at all.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'

Review Comment:
   Let's make this spec self-contained. TBH, I do not see any reason to reuse the `prefix` definition from IRC. It is probably the only definition reusable from the IRC spec, but there it is pretty barren: `An optional prefix in the path` 🤷 In any case, this API evolved independently from IRC.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no

Review Comment:
   I suggest `422` with a specific error type in the payload. 501 feels line the server simply does not support something in principle ("for any resource" in RFC 9110 wording), but in this case, clearly, the server understood the request, but is unable to fulfill it according to requested parameters.
   
   https://www.rfc-editor.org/info/rfc9110/#name-422-unprocessable-content
   
   https://www.rfc-editor.org/info/rfc9110/#status.501



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist

Review Comment:
   404 can have all sorts of root causes. The catalog not existing is probably a sub-case / example. Let's not narrow this case down too much and rely on the error payload to declare the real root cause.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:

Review Comment:
   Can `tag-name` have `/` chars in it? If so, mapping it to the URI path can be ambiguous.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target

Review Comment:
   Why not identify the target in the URI path and only use payload for the tag value? IMHO, it would be more natural from the REST design POV.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target

Review Comment:
   Why not `DELETE /polaris/v1/{prefix}/tags/{tag-name}/assignments/namespaceA/tableB/columnC`?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4040243564


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"

Review Comment:
   Thanks for the pointer. I'll make it explicit that namespace levels must satisfy the existing naming rules. Percent-encoding does not make a forbidden character valid. The literal `%1F` example still applies because it contains a percent sign and two ordinary characters, not the U+001F separator.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4043925461


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1

Review Comment:
   I’d keep it to express the non-empty token contract in the schema. required ensures the field is present, but still allows an empty string. minLength: 1 rules that out without constraining the token’s format.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4067121158


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted

Review Comment:
   And yes, the spec now includes optional Idempotency-Key support for create/update too, following Polaris’s existing contract.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4087504535


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching

Review Comment:
   The encoding is probably controlled by the HTTP request headers. The JSON payload has to be encoded according to that, I think. Once received and decoded the payload is represented by java strings and UTF-8 is no longer relevant.
   
   In other words, I do not think we should discuss encoding in this Open API spec.
   
   Could we define the limit in terms of characters?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'

Review Comment:
   POST (line 196) is generally non-idempotent in HTTP 🤔 
   
   Should `renameTag` be a PUT perhaps?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.

Review Comment:
   Configuration response of the IRC config endpoint? If so, I'm not sure it is a good idea to create this kind of inter-API dependency.
   
   Does the client need to know `idempotency-key-lifetime` at all? What can it do with that knowledge?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry

Review Comment:
   Should the ID be part of the rename request then?
   
   Otherwise, renames are ambiguous: the client cannot reasonably know that the name still represents the intended entity.
   
   `current-tag-version` can be an alternative method of ensuring target's identity, but then we must call out that the same version value should not be reused in different entities (e.g. it cannot be a simple counter).



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds

Review Comment:
   This implies that idempotency keys are stored in the entity definition, right? Do we have to imply that in the API spec? It is certainly fine to implement the API this way, but requiring all implementations to take this approach sounds like an overkill... Maybe pedantic, but it's an important distinctions I think. The API spec should only define the client / server interactions and observable API-level behaviours.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:

Review Comment:
   Suggestion: `PUT .../tags/{tag-name}/rename`. The version is a URL parameter. Payload is the new name.
   
   I think this scheme is more aligned with tag being a REST resource.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on

Review Comment:
   Does it matter (the first sentence) v? Why do we need to call this out in the spec? It is evident from the endpoint definition  🤔 



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the

Review Comment:
   `off by default` - an API specification cannot know what defaults an implementation has, nor should it force implementations into specific defaults. The API defines how client / server interactions happen, not how the server makes decisions about requests.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape

Review Comment:
   I propose keeping specific privilege names out of this spec, even if they are just illustrative.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   Sorry about this confusion 😅 In my earlier comment I meant using URI path segments. 
   
   Examples:
   * `PUT` `.../tags/{tag-name}/assignments/{namespace}`
   *  `PUT` `.../tags/{tag-name}/assignments/{namespace}/{name}`
   *  `PUT` `.../tags/{tag-name}/assignments/{namespace}/{name}/{col-name}`
   
   Name is normally a sufficient identifier, so type becomes more of a validation parameter (optional):
   
   `.../tags/{tag-name}/assignments/{namespace}/{name}?type=TABLE`
   `.../tags/{tag-name}/assignments/{namespace}/{name}?type=TABLE`
   `.../tags/{tag-name}/assignments/{namespace}/{name}/{col-name}?type=TABLE`
   
   Note that we only need to identity the type of the entity as column/namespace/catalog is apparent from the URL.
   
   WDYT?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'

Review Comment:
   It is fine to keep specific error responses for a sub-set of possible errors, but I do not much value in it. The error payload shape is the same... Can we share the same type for all error cases?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds
+        that operation's privilege. A recognized createTag or updateTag retry answers 200 with the
+        definition's current state: not the original response, and not the state the original request wrote
+        if the definition has changed since. A recognized renameTag retry answers 204 without renaming
+        again, even after later renames, and the server never renames a definition back to satisfy a retry.
+        Recognition happens before the supplied `current-tag-version` is compared with the definition's
+        current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        The server records the key, not the request, so reusing one key with different arguments is a client
+        error: the outcome is undefined and no conflict response is promised. The server does not replay the
+        original response body.
+
+        Recognition ends when the definition is deleted. A request the server cannot match to a live key on
+        a live definition follows the ordinary path, with the usual name lookup, authorization and version
+        check and the errors those produce.
+
+        A definition holds a bounded number of live keys. When that set is full, a write that would record
+        another key is rejected with 503 ServiceUnavailable and a Retry-After header rather than evicting a
+        live key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none of
+        them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          minimum: 400
+          maximum: 600

Review Comment:
   Does it matter?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still

Review Comment:
   Why do we need to discuss AuthZ specifica (like `TAG_CREATE`)  in the API spec? I suppose the API should work the same way regardless of how the server performs authorization.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds
+        that operation's privilege. A recognized createTag or updateTag retry answers 200 with the
+        definition's current state: not the original response, and not the state the original request wrote
+        if the definition has changed since. A recognized renameTag retry answers 204 without renaming
+        again, even after later renames, and the server never renames a definition back to satisfy a retry.
+        Recognition happens before the supplied `current-tag-version` is compared with the definition's
+        current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        The server records the key, not the request, so reusing one key with different arguments is a client
+        error: the outcome is undefined and no conflict response is promised. The server does not replay the
+        original response body.
+
+        Recognition ends when the definition is deleted. A request the server cannot match to a live key on
+        a live definition follows the ordinary path, with the usual name lookup, authorization and version
+        check and the errors those produce.
+
+        A definition holds a bounded number of live keys. When that set is full, a write that would record
+        another key is rejected with 503 ServiceUnavailable and a Retry-After header rather than evicting a
+        live key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none of
+        them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          minimum: 400
+          maximum: 600
+          description: HTTP response code
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes when encoded as UTF-8. A longer value returns
+            400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement. A new no-op update still has to match the current
+            token. Where an already completed update or rename is recognized from an Idempotency-Key, that
+            recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    RenameTagRequest:
+      type: object
+      description: |
+        A rename of one definition. The source keeps its identity, its `id`, its assignments and its values;
+        only the name changes, and the version token changes on success.
+      required:
+        - source
+        - destination
+        - current-tag-version
+      properties:
+        source:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The current name of the definition to rename. It must exist in the resolved catalog.
+        destination:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The new name. It must match the TagName pattern, must not already name a definition in the
+            catalog, and must differ from `source`.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The source definition's current version token, as returned by a previous create, load, or
+            update. Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'

Review Comment:
   Why wrap `Tag` in `{"tag": {...}}`? Why not return `Tag` at a direct response payload?



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds
+        that operation's privilege. A recognized createTag or updateTag retry answers 200 with the
+        definition's current state: not the original response, and not the state the original request wrote
+        if the definition has changed since. A recognized renameTag retry answers 204 without renaming
+        again, even after later renames, and the server never renames a definition back to satisfy a retry.
+        Recognition happens before the supplied `current-tag-version` is compared with the definition's
+        current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        The server records the key, not the request, so reusing one key with different arguments is a client
+        error: the outcome is undefined and no conflict response is promised. The server does not replay the
+        original response body.
+
+        Recognition ends when the definition is deleted. A request the server cannot match to a live key on
+        a live definition follows the ordinary path, with the usual name lookup, authorization and version
+        check and the errors those produce.
+
+        A definition holds a bounded number of live keys. When that set is full, a write that would record
+        another key is rejected with 503 ServiceUnavailable and a Retry-After header rather than evicting a
+        live key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none of
+        them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          minimum: 400
+          maximum: 600
+          description: HTTP response code
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes when encoded as UTF-8. A longer value returns
+            400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement. A new no-op update still has to match the current
+            token. Where an already completed update or rename is recognized from an Idempotency-Key, that
+            recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest.
+        current-tag-version:

Review Comment:
   Apologies if I'm repeating myself (I do not recall, and did not find my previous comments on this).
   
   `current-tag-version` looks like a contextual / auxiliary piece of information for the entity. In a "serial" world, one only needs to deal with normal entity properties (name, value, etc...).
   
   WDYT about keeping `current-tag-version` as URL query parameter?
   
   Payloads then become ordinary `Tag` objects. They will not have the `current-tag-version` property. `LoadTagResponse` will have `current-tag-version` parallel to the `Tag` object.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4042240871


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null

Review Comment:
   That makes sense. I’ll make update replace the complete editable definition: comment and allowed-values. Both fields must be present. An explicit null clears comment, and allowed-values must be a valid, non-empty list. Omitting either field will return 400, so clients explicitly describe the desired state.
   
   current-tag-version will remain required, with a stale token returning 409. A no-op will still check the token and return the current version without advancing it. Rename will be handled separately, and target-types will remain create-only.
   
   This gives clients a read/modify/write flow with an explicit way to clear the optional description, without the current per-field omitted/null rules.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098253639


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry

Review Comment:
   Agreed that the version must distinguish both the definition and its revision. I’d keep that protection in the required opaque token rather than add a separate ID field. I’ll explicitly cover both delete/recreate and another tag being renamed into the source name, with the check applied atomically with the rename.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "orca-review-bot (via GitHub) via issues" <is...@polaris.apache.org>.
orca-review-bot commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4557771883


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1835 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog. A definition gives a classification a name and
+        a set of allowed values. Assignments select exactly one allowed value for a catalog,
+        namespace, table, view, or column.
+
+        The request supplies a catalog-unique `name`, a non-empty `allowed-values` list, and an
+        optional `description`. Value matching is exact and case-sensitive. CreateTagRequest
+        describes the field constraints.
+
+        Where idempotency is enabled, a retry uses the requested name to locate the original
+        definition. If that definition has been renamed, a free name creates a new definition and an
+        occupied name returns 409 AlreadyExists. Renaming the original definition back within the
+        recognition window allows its key to be recognized again. The Idempotency-Key parameter
+        defines retry behavior.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema validation failures. InvalidJson covers malformed JSON.
+            InvalidIdempotencyKey covers a malformed non-blank header when idempotency support is
+            enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            AlreadyExists means the requested name already belongs to a definition in this catalog.
+
+            Possible error types: AlreadyExists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition identifiers in the catalog
+      operationId: listTags
+      description: |
+        Returns tag definition identifiers in the catalog.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete

Review Comment:
   Upstream Iceberg lists return everything with a null next-page-token when no pageToken is sent. Tag lists return only the first page. A generic client that loops on next-page-token is fine, but one that sends a single request will silently get a partial list. Since the shared pagination contract is still open on the dev list, are we OK freezing page-by-default here? Same applies to listObjectsByTag and getObjectTags.
   
   <sub>🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.</sub>



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1835 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog. A definition gives a classification a name and
+        a set of allowed values. Assignments select exactly one allowed value for a catalog,
+        namespace, table, view, or column.
+
+        The request supplies a catalog-unique `name`, a non-empty `allowed-values` list, and an
+        optional `description`. Value matching is exact and case-sensitive. CreateTagRequest
+        describes the field constraints.
+
+        Where idempotency is enabled, a retry uses the requested name to locate the original
+        definition. If that definition has been renamed, a free name creates a new definition and an
+        occupied name returns 409 AlreadyExists. Renaming the original definition back within the
+        recognition window allows its key to be recognized again. The Idempotency-Key parameter
+        defines retry behavior.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema validation failures. InvalidJson covers malformed JSON.
+            InvalidIdempotencyKey covers a malformed non-blank header when idempotency support is
+            enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            AlreadyExists means the requested name already belongs to a definition in this catalog.
+
+            Possible error types: AlreadyExists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition identifiers in the catalog
+      operationId: listTags
+      description: |
+        Returns tag definition identifiers in the catalog.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames a tag definition without changing its id, description, allowed values, or
+        assignments. The version token changes when the rename succeeds.
+
+        `current-tag-version` must match the source definition's current token. Comparison and
+        rename are atomic. A stale token or one identifying a different definition returns 409
+        TagVersionMismatch, including after a same-name replacement. Tag.version defines the token's
+        identity and concurrency guarantees.
+
+        A successful rename and a recognized retry both return 204 without a body. A recognized
+        retry does not rename the definition again, even after later renames or other changes. This
+        also applies to a concurrent duplicate that recognizes the completed write. The
+        Idempotency-Key parameter defines recognition. An ordinary request using the old name may
+        return 404 NoSuchTag. Clients needing the current version can load the definition
+        separately.
+
+        Requires permission to delete the source definition and to create a definition in the
+        catalog. Permission to modify the source alone is insufficient. No permission to read the
+        definition is required for rename.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: |
+            The definition was renamed, or the request was recognized as an earlier successful
+            rename. No content is returned. A recognized retry does not rename the definition again.
+        400:
+          description: |
+            BadRequest covers an invalid destination name or a destination equal to the source.
+            ValidationError covers missing required fields, schema-type violations, and a missing,
+            null, empty, or non-string current-tag-version. InvalidJson covers malformed
+            JSON. InvalidIdempotencyKey covers a malformed non-blank header when idempotency support
+            is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the source
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            AlreadyExists means the destination name is occupied. TagVersionMismatch means the
+            supplied token does not match the source definition. Reload the definition before
+            retrying with a new token. CommitConflict means a concurrent change prevented the
+            rename; the request may be retried.
+
+            Possible error types: AlreadyExists, TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Loads the tag definition, including its stable id, current name, description, allowed
+        values, and version token.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the definition's description and allowed-values list. Both fields are required;
+        send the current value to keep it. An explicit JSON null or empty description clears it.
+        Renaming uses renameTag.
+
+        Changing allowed values does not rewrite existing assignments. An assignment whose value is
+        removed remains readable until replaced or unassigned. Later assignments must use a value
+        from the updated list.
+
+        `current-tag-version` must match the definition's current token, including when no fields
+        would change. A mismatch returns 409 TagVersionMismatch. The comparison and update are
+        atomic. Tag.version defines the token's identity and concurrency guarantees.
+
+        A successful update returns the resulting definition and token. A no-op update leaves both
+        unchanged. A concurrent write may invalidate the returned token before the caller receives
+        it.
+
+        A no-op update may or may not register an idempotency key; registration does not advance its
+        version. If its key is not recognized after the definition changes, retrying the no-op
+        returns 409 TagVersionMismatch. A recognized retry returns the current definition without
+        applying the update again, as described by Idempotency-Key.
+
+        Requires permission to modify the definition.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema violations, including a missing, null, empty, or non-string
+            current-tag-version. An explicit null update description is valid. InvalidJson covers
+            malformed JSON. InvalidIdempotencyKey covers a malformed
+            non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            TagVersionMismatch means the supplied token does not match the definition, including a
+            no-op update. CommitConflict means a concurrent change prevented the update. Reload the
+            definition and retry with its current token.
+
+            Possible error types: TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Permanently deletes the tag definition and releases its name.
+
+        Without `detach-all=true`, an assignment on a live target prevents deletion with 400
+        TagInUse. Assignments confirmed orphaned or belonging to soft-dropped targets do not prevent
+        deletion. Deleting the definition makes these assignments permanently ineffective, including
+        if a soft-dropped target is restored later.
+
+        With `detach-all=true`, deletion removes the definition and all its assignments atomically
+        from Tag API reads and reverse lookups. A read beginning after success cannot return any
+        assignment of the deleted definition. A failure before deletion completes leaves visible
+        state unchanged; a later cleanup failure cannot restore the deleted definition or
+        assignments.
+
+        A failure to load a required entity or schema metadata is an error, not evidence of absence.
+        It leaves visible state unchanged. Transient execution failures use the server-error
+        responses.
+
+        Requires permission to delete the definition. `detach-all=true` also requires
+        definition-side permission to detach assignments, even if none exist. No per-target
+        permission is required. This operation does not recognize completed requests through
+        Idempotency-Key.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When true, dropTag also deletes every assignment of this definition across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            TagInUse means an assignment on a live target prevents deletion without
+            `detach-all=true`. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Sets the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces its selected value.
+
+        The JSON body supplies a `target` and `values` containing exactly one value from the
+        definition's current allowed-values list. TagAttachmentTarget defines the supported kinds,
+        address fields, and identity rules. Names are original JSON strings without URI encoding.
+        The target must belong to the catalog addressed by {prefix}.
+
+        An absent, null, or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. Changes to unrelated target properties do not cause a
+        conflict. This operation does not recognize completed requests through Idempotency-Key.
+
+        Requires permission to attach on the definition and to attach a tag on the target. A column
+        target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, null
+            or empty values, empty or duplicate members, more than one selected value, a value
+            exceeding 2000 decoded UTF-8 bytes, or a value absent from the definition's
+            allowed-values list.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, missing `values`, non-null `values` that is not an array, and other
+            schema-type violations. The BadRequest cases above take precedence, including unknown
+            target kinds and null values. InvalidJson covers malformed JSON. InvalidIdempotencyKey
+            covers a malformed non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Removes the direct assignment of this tag definition from one target. Removing a direct
+        assignment may reveal an inherited value. The definition's allowed-values list is not
+        checked.
+
+        The JSON body supplies only a `target`; a `values` field is invalid, including null or an
+        empty array. TagAttachmentTarget defines the supported kinds, address fields, and identity
+        rules. Names are original JSON strings without URI encoding. The target must belong to the
+        catalog addressed by {prefix}.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. Completed requests
+        are not recognized through Idempotency-Key, so retrying a successful removal returns 404
+        while the assignment remains absent. A rejected request changes no assignment. Changes to
+        unrelated target properties do not cause a conflict.
+
+        Requires permission to detach on the definition and to detach a tag from the target. A
+        column target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, or a
+            supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, and other schema-type violations. The BadRequest cases above take
+            precedence, including unknown target kinds and a supplied values field. InvalidJson
+            covers malformed JSON. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column), NoSuchAssignment (the direct assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        Returns targets with a direct assignment of the named tag definition. Targets that only
+        inherit the tag are excluded. Without `value`, all direct assignments are eligible; with it,
+        only assignments selecting that exact, case-sensitive value are eligible.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`. Filtering and
+        work limits may produce a short or empty page with a continuation token.
+
+        Requires read permission on the definition and each reported target. Columns are authorized
+        through their containing tables. Catalog permission does not replace per-target
+        authorization. Targets the caller cannot read are omitted. Authorization-system failures
+        fail the request.
+
+        Dropped, soft-dropped, or missing targets and removed columns are omitted. A failure to load
+        metadata is an error, not evidence that a target is absent.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments selecting this exact, case-sensitive value.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves tags for one target identified by `target-type` and the query parameters that kind
+        requires. The `target-type` parameter defines valid combinations. The optional `view`
+        selects:
+
+        - `direct` (default): assignments stored on the queried target.
+        - `effective`: one winning assignment per tag definition from the target and its parents.
+          The closest assignment wins: column, table or view, nearest namespace, then catalog.
+          Values from different levels are never combined.
+
+        Both views paginate by default. Send `pagination=false` alone to request all tags of the
+        target, subject to the response-size and work limits described by `pageSize`.
+
+        The hierarchy, definitions, and assignments used for one response are consistent with a
+        single logical point in time. No snapshot consistency is guaranteed across separate pages.
+        An effective read considers the complete hierarchy, even when paginated. If it cannot do so,
+        the request
+        fails; it never returns a partial hierarchy or falls back to a direct read.
+
+        Results omit soft-dropped targets and assignments whose definition, target entity, or field
+        is permanently absent.
+
+        Requires read permission on the queried target, or its containing table for a column. This
+        permission covers all effective tags, without per-parent or per-definition authorization.
+
+        Query parameters address the same objects as TagAttachmentTarget: `namespace` carries the
+        namespace levels, `target-name` the table or view name, and `column` the literal column
+        name. For example, sales.eu.customers.email is addressed by:
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        The catalog is addressed by `?target-type=CATALOG`, with no namespace, target-name, or
+        column. Each address parameter and `view` may occur only once. Present empty values and
+        empty namespace levels are invalid. Missing `target-type` returns 400 ValidationError.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            ValidationError covers a missing required `target-type` or other schema validation
+            failures. BadRequest covers unsupported kinds, invalid address combinations, repeated
+            address parameters, empty address values or namespace levels, and empty or unknown
+            `view` or `target-type` values. The BadRequest cases take precedence over schema
+            validation.
+
+            BadRequest also covers invalid or repeated pagination parameters, invalid or expired
+            tokens, conflicting pagination modes, full-result requests exceeding response-size or
+            work limits, and paged requests unable to make safe progress within their work budget.
+
+            Malformed URI escapes may receive an HTTP-layer 400 response without a Tag error
+            payload.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTarget (the target or
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The required target kind. The other address parameters must match it:
+
+        - `CATALOG`: namespace, target-name, and column absent.
+        - `NAMESPACE`: namespace required; target-name and column absent.
+        - `TABLE` or `VIEW`: namespace and target-name required; column absent.
+        - `COLUMN`: namespace, target-name, and column required.
+
+        A missing kind returns 400 ValidationError. An empty or unknown kind, a repeated parameter,
+        or an invalid combination returns 400 BadRequest. A missing kind never selects the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        Namespace levels encoded as one query string using Iceberg namespace query encoding. Join
+        the original names with U+001F, then URI-encode the result once. Each level must be
+        non-empty and must not contain U+001F. Clients must check levels before joining them,
+        because a separator inside a name cannot be distinguished from one between names.
+
+        The server URI-decodes the value once, then splits it on U+001F. Surviving percent sequences
+        remain literal text. A raw `+` decodes to a space; send a literal plus as `%2B`.
+
+        Examples of namespace query values:
+
+        - `["sales", "eu"]` becomes `sales%1Feu`.
+        - `["sales.eu"]` stays `sales.eu`, a single level.
+        - `["R&D", "tax=2026"]` becomes `R%26D%1Ftax%3D2026`.
+        - `["tax%20rate", "%1F"]` becomes `tax%2520rate%1F%251F`.
+        - `["with space", "café"]` becomes `with%20space%1Fcaf%C3%A9`.
+        - `["销售", "日本語"]` becomes `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E`.
+
+        `sales%251Feu` names one literal level, `sales%1Feu`, rather than two levels. Encoding does
+        not relax namespace naming rules: Polaris rejects `/ \ : * ? " < > | # +`, backticks,
+        control characters, and leading or trailing whitespace in namespace, table, and view names.
+
+        Omit this parameter for a catalog target. An empty value, an empty decoded level, or a
+        repeated parameter returns 400 BadRequest. Invalid examples include:
+
+        - `namespace=`: empty value.
+        - `namespace=%1Fsales` or `namespace=sales%1F`: empty first or last level.
+        - `namespace=sales%1F%1Feu`: empty middle level.
+        - `namespace=sales&namespace=eu`: repeated parameter.
+
+        Malformed escapes such as `namespace=%` or `namespace=%GG` may receive an HTTP-layer 400
+        response without a Tag error payload.
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        The table or view name selected by `target-type`. For a column target, this is the
+        containing Iceberg table's name. Existing catalog naming rules apply.
+
+        This is one literal query value, without namespace joining or splitting. URI-encode it once;
+        the server decodes it once. For example, `orders%20&total` becomes `orders%2520%26total`,
+        and `Q1 orders` becomes `Q1%20orders`. A raw `+` decodes to a space; a literal plus requires
+        `%2B`.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        The literal name of one top-level column in the Iceberg table named by target-name. Dots do
+        not select nested fields. The value is not split or parsed as JSON.
+
+        URI-encode the name once; the server decodes it once. For example, `cost+tax` becomes
+        `cost%2Btax`, `a &?=+%` becomes `a%20%26%3F%3D%2B%25`, and `customer.name` stays unchanged.
+        A raw `+` decodes to a space; `%252B` decodes to literal `%2B` without a second decode.
+        Existing schema naming rules apply.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects one page (omitted or `true`) or the complete result in one response (`false`). Both
+        modes use the same filters, authorization, and read guarantees. Response-size and work
+        limits apply in both modes, as described by `pageSize`.
+
+        `pagination=false` must be sent without `pageToken` or `pageSize`, even empty ones. Neither
+        an empty token nor any page size selects full-result mode.
+
+        Only literal `true` and `false` are valid. Empty, other, or repeated values return 400
+        BadRequest, as do conflicting mode parameters. Repetition is invalid even when values agree.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a listing in the default paged mode:
+
+        - Omitted or empty: request the first page.
+        - Non-empty: continue from the supplied token.
+
+        Send the token back unchanged; do not parse or construct it. It is bound to the catalog,
+        definition or target, view, and filters of the request that produced it. Each request is
+        authorized again; a token grants no permission.
+
+        An invalid or expired token, a repeated parameter, or any pageToken combined with
+        `pagination=false` returns 400 BadRequest. Repetition is invalid even when values agree.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on results per page. The value must be a positive integer. Zero, negative,
+        empty, non-integer, or repeated values return 400 BadRequest, with or without a pageToken.
+        Any pageSize combined with `pagination=false` is also invalid.
+
+        When omitted, the server's finite default applies, including on continuation requests.
+        Continuations do not inherit the previous request's size. Values above the server maximum
+        are capped. Pages may contain fewer results than the requested bound.
+
+        Both paged and full-result requests have finite response-size and work limits by default.
+        Deployments may adjust these limits; an absent override does not remove them. A full-result
+        request exceeding a limit returns 400 BadRequest directing the caller to use paged mode with
+        the same target and filters. It never returns a partial success, silently truncates results,
+        or switches delivery modes.
+
+        A paged request reaching its work limit may return a short or empty page with a continuation
+        token. Every eligible result not yet returned must remain reachable through continuation. If
+        the request cannot make safe progress within its work limit, it returns 400 BadRequest.
+        Metadata, storage, or authorization failures return their service error, not an empty page
+        or a work-limit error.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional key for recognizing a completed write after a lost response. Enabled deployments
+        advertise the recognition window as `idempotency-key-lifetime` in the catalog configuration.
+        Expiration ends recognition without indicating whether the original write succeeded.
+
+        Only createTag, updateTag, and renameTag recognize completed writes. Request validation and
+        current authorization for the original operation are still required. Recognition precedes
+        comparison of current-tag-version with the definition's current token.
+
+        A recognized create or update returns 200 with the definition's current state, which may
+        differ from both the original response and the original write. A recognized rename returns
+        204 without another rename, even after later renames. Original responses are not replayed.
+
+        Use one key per logical operation and repeat both key and request unchanged. Reusing a key
+        with different arguments has undefined behavior; no conflict response is promised.
+
+        Recognition ends when the definition is deleted. A same-name replacement inherits no keys.
+        An unrecognized request follows ordinary name lookup, authorization, and version checks.
+
+        The number of keys recognized for one definition at a time is bounded. A write that would
+        add a key beyond this bound returns 503 ServiceUnavailable with Retry-After and is not
+        applied. Capacity exhaustion must not end recognition of an existing key early.
+
+        dropTag, assignTag, and unassignTag accept the header but do not recognize completed writes.
+
+        A missing or blank header supplies no key. With support enabled, a non-blank value must be a
+        UUID or the request returns 400 InvalidIdempotencyKey. Any UUID version is accepted. With
+        support disabled, the header is ignored and the operation follows its ordinary path.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog containing the tag definitions and assignments addressed by this
+        request. Polaris maps the prefix to a catalog name; the default mapping uses the name
+        itself.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition's name, subject to TagName constraints. Namespace, table, view, and
+        column names follow their own naming rules.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque continuation token. A non-empty value means there is more to read, including after
+        a short or empty page. Absent or null means completion; the server never returns an empty
+        string. A full-result response carries no continuation token. Send it back unchanged as
+        `pageToken`.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        The error response body for Polaris-specific APIs, containing the error's HTTP status code,
+        type, and message.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description: |
+        A catalog-unique tag definition name of at most 256 characters, containing only ASCII
+        letters, digits, hyphens, and underscores. Leading hyphens are allowed.
+      maxLength: 256
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned opaque identity for comparisons within one realm and catalog. It survives
+        updates and renames. Deletion and recreation under the same name produces a different id. Do
+        not parse it or infer ordering. Operations address tags by name and use current-tag-version
+        for concurrency checks.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+
+        - `CATALOG`: the catalog addressed by {prefix}.
+        - `NAMESPACE`: a namespace.
+        - `TABLE`: a whole Iceberg table or supported generic table.
+        - `VIEW`: a whole Iceberg view.
+        - `COLUMN`: one top-level column of an Iceberg table. Generic-table columns, view columns,
+          and nested fields are unsupported.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - allowed-values
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name. Renaming changes this value while preserving its id.
+        description:
+          type: string
+          description: |
+            Optional classification description; it does not affect matching or inheritance.
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The allowed assignment values: distinct, non-empty strings matched exactly and
+            case-sensitively. The list must be non-empty. Each value is limited to 2000 bytes of
+            decoded UTF-8 text, excluding JSON escaping. Invalid contents return 400 BadRequest.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty concurrency token. Send it unchanged as current-tag-version; do not
+            parse, order, or increment it. A definition-changing write advances the token. A no-op
+            update returns the current token without advancing it.
+
+            The fields and token in one response describe the same revision. Token comparison and
+            definition mutation are atomic across all supported definition-write paths, including
+            native writes outside this API.
+
+            A definition change invalidates earlier tokens even if its fields later return to their
+            previous values. A token cannot authorize an update or rename of a same-name replacement
+            or a different definition renamed into that name. No-op updates also require a matching
+            token. Idempotency recognition precedes token comparison, as described by
+            Idempotency-Key.
+
+            Unrelated catalog changes may invalidate the token even when this definition is

Review Comment:
   This lets unrelated catalog writes invalidate a tag's version token. On a busy catalog, update and rename can then fail with TagVersionMismatch even though nobody touched the tag. Is that a backend limitation we want frozen into the contract, or can the token stay tied to the definition?
   
   <sub>🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.</sub>



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1835 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog. A definition gives a classification a name and
+        a set of allowed values. Assignments select exactly one allowed value for a catalog,
+        namespace, table, view, or column.
+
+        The request supplies a catalog-unique `name`, a non-empty `allowed-values` list, and an
+        optional `description`. Value matching is exact and case-sensitive. CreateTagRequest
+        describes the field constraints.
+
+        Where idempotency is enabled, a retry uses the requested name to locate the original
+        definition. If that definition has been renamed, a free name creates a new definition and an
+        occupied name returns 409 AlreadyExists. Renaming the original definition back within the
+        recognition window allows its key to be recognized again. The Idempotency-Key parameter
+        defines retry behavior.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema validation failures. InvalidJson covers malformed JSON.
+            InvalidIdempotencyKey covers a malformed non-blank header when idempotency support is
+            enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            AlreadyExists means the requested name already belongs to a definition in this catalog.
+
+            Possible error types: AlreadyExists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition identifiers in the catalog
+      operationId: listTags
+      description: |
+        Returns tag definition identifiers in the catalog.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames a tag definition without changing its id, description, allowed values, or
+        assignments. The version token changes when the rename succeeds.
+
+        `current-tag-version` must match the source definition's current token. Comparison and
+        rename are atomic. A stale token or one identifying a different definition returns 409
+        TagVersionMismatch, including after a same-name replacement. Tag.version defines the token's
+        identity and concurrency guarantees.
+
+        A successful rename and a recognized retry both return 204 without a body. A recognized
+        retry does not rename the definition again, even after later renames or other changes. This
+        also applies to a concurrent duplicate that recognizes the completed write. The
+        Idempotency-Key parameter defines recognition. An ordinary request using the old name may
+        return 404 NoSuchTag. Clients needing the current version can load the definition
+        separately.
+
+        Requires permission to delete the source definition and to create a definition in the
+        catalog. Permission to modify the source alone is insufficient. No permission to read the
+        definition is required for rename.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: |
+            The definition was renamed, or the request was recognized as an earlier successful
+            rename. No content is returned. A recognized retry does not rename the definition again.
+        400:
+          description: |
+            BadRequest covers an invalid destination name or a destination equal to the source.
+            ValidationError covers missing required fields, schema-type violations, and a missing,
+            null, empty, or non-string current-tag-version. InvalidJson covers malformed
+            JSON. InvalidIdempotencyKey covers a malformed non-blank header when idempotency support
+            is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the source
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            AlreadyExists means the destination name is occupied. TagVersionMismatch means the
+            supplied token does not match the source definition. Reload the definition before
+            retrying with a new token. CommitConflict means a concurrent change prevented the
+            rename; the request may be retried.
+
+            Possible error types: AlreadyExists, TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Loads the tag definition, including its stable id, current name, description, allowed
+        values, and version token.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the definition's description and allowed-values list. Both fields are required;
+        send the current value to keep it. An explicit JSON null or empty description clears it.
+        Renaming uses renameTag.
+
+        Changing allowed values does not rewrite existing assignments. An assignment whose value is
+        removed remains readable until replaced or unassigned. Later assignments must use a value
+        from the updated list.
+
+        `current-tag-version` must match the definition's current token, including when no fields
+        would change. A mismatch returns 409 TagVersionMismatch. The comparison and update are
+        atomic. Tag.version defines the token's identity and concurrency guarantees.
+
+        A successful update returns the resulting definition and token. A no-op update leaves both
+        unchanged. A concurrent write may invalidate the returned token before the caller receives
+        it.
+
+        A no-op update may or may not register an idempotency key; registration does not advance its
+        version. If its key is not recognized after the definition changes, retrying the no-op
+        returns 409 TagVersionMismatch. A recognized retry returns the current definition without
+        applying the update again, as described by Idempotency-Key.
+
+        Requires permission to modify the definition.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema violations, including a missing, null, empty, or non-string
+            current-tag-version. An explicit null update description is valid. InvalidJson covers
+            malformed JSON. InvalidIdempotencyKey covers a malformed
+            non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            TagVersionMismatch means the supplied token does not match the definition, including a
+            no-op update. CommitConflict means a concurrent change prevented the update. Reload the
+            definition and retry with its current token.
+
+            Possible error types: TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Permanently deletes the tag definition and releases its name.
+
+        Without `detach-all=true`, an assignment on a live target prevents deletion with 400
+        TagInUse. Assignments confirmed orphaned or belonging to soft-dropped targets do not prevent
+        deletion. Deleting the definition makes these assignments permanently ineffective, including
+        if a soft-dropped target is restored later.
+
+        With `detach-all=true`, deletion removes the definition and all its assignments atomically
+        from Tag API reads and reverse lookups. A read beginning after success cannot return any
+        assignment of the deleted definition. A failure before deletion completes leaves visible
+        state unchanged; a later cleanup failure cannot restore the deleted definition or
+        assignments.
+
+        A failure to load a required entity or schema metadata is an error, not evidence of absence.
+        It leaves visible state unchanged. Transient execution failures use the server-error
+        responses.
+
+        Requires permission to delete the definition. `detach-all=true` also requires
+        definition-side permission to detach assignments, even if none exist. No per-target
+        permission is required. This operation does not recognize completed requests through
+        Idempotency-Key.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When true, dropTag also deletes every assignment of this definition across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            TagInUse means an assignment on a live target prevents deletion without
+            `detach-all=true`. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Sets the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces its selected value.
+
+        The JSON body supplies a `target` and `values` containing exactly one value from the
+        definition's current allowed-values list. TagAttachmentTarget defines the supported kinds,
+        address fields, and identity rules. Names are original JSON strings without URI encoding.
+        The target must belong to the catalog addressed by {prefix}.
+
+        An absent, null, or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. Changes to unrelated target properties do not cause a
+        conflict. This operation does not recognize completed requests through Idempotency-Key.
+
+        Requires permission to attach on the definition and to attach a tag on the target. A column
+        target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, null
+            or empty values, empty or duplicate members, more than one selected value, a value
+            exceeding 2000 decoded UTF-8 bytes, or a value absent from the definition's
+            allowed-values list.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, missing `values`, non-null `values` that is not an array, and other
+            schema-type violations. The BadRequest cases above take precedence, including unknown
+            target kinds and null values. InvalidJson covers malformed JSON. InvalidIdempotencyKey
+            covers a malformed non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Removes the direct assignment of this tag definition from one target. Removing a direct
+        assignment may reveal an inherited value. The definition's allowed-values list is not
+        checked.
+
+        The JSON body supplies only a `target`; a `values` field is invalid, including null or an
+        empty array. TagAttachmentTarget defines the supported kinds, address fields, and identity
+        rules. Names are original JSON strings without URI encoding. The target must belong to the
+        catalog addressed by {prefix}.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. Completed requests
+        are not recognized through Idempotency-Key, so retrying a successful removal returns 404
+        while the assignment remains absent. A rejected request changes no assignment. Changes to
+        unrelated target properties do not cause a conflict.
+
+        Requires permission to detach on the definition and to detach a tag from the target. A
+        column target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, or a
+            supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, and other schema-type violations. The BadRequest cases above take
+            precedence, including unknown target kinds and a supplied values field. InvalidJson
+            covers malformed JSON. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column), NoSuchAssignment (the direct assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        Returns targets with a direct assignment of the named tag definition. Targets that only
+        inherit the tag are excluded. Without `value`, all direct assignments are eligible; with it,
+        only assignments selecting that exact, case-sensitive value are eligible.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`. Filtering and
+        work limits may produce a short or empty page with a continuation token.
+
+        Requires read permission on the definition and each reported target. Columns are authorized
+        through their containing tables. Catalog permission does not replace per-target
+        authorization. Targets the caller cannot read are omitted. Authorization-system failures
+        fail the request.
+
+        Dropped, soft-dropped, or missing targets and removed columns are omitted. A failure to load
+        metadata is an error, not evidence that a target is absent.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments selecting this exact, case-sensitive value.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves tags for one target identified by `target-type` and the query parameters that kind
+        requires. The `target-type` parameter defines valid combinations. The optional `view`
+        selects:
+
+        - `direct` (default): assignments stored on the queried target.
+        - `effective`: one winning assignment per tag definition from the target and its parents.
+          The closest assignment wins: column, table or view, nearest namespace, then catalog.
+          Values from different levels are never combined.
+
+        Both views paginate by default. Send `pagination=false` alone to request all tags of the
+        target, subject to the response-size and work limits described by `pageSize`.
+
+        The hierarchy, definitions, and assignments used for one response are consistent with a
+        single logical point in time. No snapshot consistency is guaranteed across separate pages.
+        An effective read considers the complete hierarchy, even when paginated. If it cannot do so,
+        the request
+        fails; it never returns a partial hierarchy or falls back to a direct read.
+
+        Results omit soft-dropped targets and assignments whose definition, target entity, or field
+        is permanently absent.
+
+        Requires read permission on the queried target, or its containing table for a column. This
+        permission covers all effective tags, without per-parent or per-definition authorization.
+
+        Query parameters address the same objects as TagAttachmentTarget: `namespace` carries the
+        namespace levels, `target-name` the table or view name, and `column` the literal column
+        name. For example, sales.eu.customers.email is addressed by:
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        The catalog is addressed by `?target-type=CATALOG`, with no namespace, target-name, or
+        column. Each address parameter and `view` may occur only once. Present empty values and
+        empty namespace levels are invalid. Missing `target-type` returns 400 ValidationError.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            ValidationError covers a missing required `target-type` or other schema validation
+            failures. BadRequest covers unsupported kinds, invalid address combinations, repeated
+            address parameters, empty address values or namespace levels, and empty or unknown
+            `view` or `target-type` values. The BadRequest cases take precedence over schema
+            validation.
+
+            BadRequest also covers invalid or repeated pagination parameters, invalid or expired
+            tokens, conflicting pagination modes, full-result requests exceeding response-size or
+            work limits, and paged requests unable to make safe progress within their work budget.
+
+            Malformed URI escapes may receive an HTTP-layer 400 response without a Tag error
+            payload.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTarget (the target or
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The required target kind. The other address parameters must match it:
+
+        - `CATALOG`: namespace, target-name, and column absent.
+        - `NAMESPACE`: namespace required; target-name and column absent.
+        - `TABLE` or `VIEW`: namespace and target-name required; column absent.
+        - `COLUMN`: namespace, target-name, and column required.
+
+        A missing kind returns 400 ValidationError. An empty or unknown kind, a repeated parameter,
+        or an invalid combination returns 400 BadRequest. A missing kind never selects the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        Namespace levels encoded as one query string using Iceberg namespace query encoding. Join
+        the original names with U+001F, then URI-encode the result once. Each level must be
+        non-empty and must not contain U+001F. Clients must check levels before joining them,
+        because a separator inside a name cannot be distinguished from one between names.
+
+        The server URI-decodes the value once, then splits it on U+001F. Surviving percent sequences
+        remain literal text. A raw `+` decodes to a space; send a literal plus as `%2B`.
+
+        Examples of namespace query values:
+
+        - `["sales", "eu"]` becomes `sales%1Feu`.
+        - `["sales.eu"]` stays `sales.eu`, a single level.
+        - `["R&D", "tax=2026"]` becomes `R%26D%1Ftax%3D2026`.
+        - `["tax%20rate", "%1F"]` becomes `tax%2520rate%1F%251F`.
+        - `["with space", "café"]` becomes `with%20space%1Fcaf%C3%A9`.
+        - `["销售", "日本語"]` becomes `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E`.
+
+        `sales%251Feu` names one literal level, `sales%1Feu`, rather than two levels. Encoding does
+        not relax namespace naming rules: Polaris rejects `/ \ : * ? " < > | # +`, backticks,
+        control characters, and leading or trailing whitespace in namespace, table, and view names.
+
+        Omit this parameter for a catalog target. An empty value, an empty decoded level, or a
+        repeated parameter returns 400 BadRequest. Invalid examples include:
+
+        - `namespace=`: empty value.
+        - `namespace=%1Fsales` or `namespace=sales%1F`: empty first or last level.
+        - `namespace=sales%1F%1Feu`: empty middle level.
+        - `namespace=sales&namespace=eu`: repeated parameter.
+
+        Malformed escapes such as `namespace=%` or `namespace=%GG` may receive an HTTP-layer 400
+        response without a Tag error payload.
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        The table or view name selected by `target-type`. For a column target, this is the
+        containing Iceberg table's name. Existing catalog naming rules apply.
+
+        This is one literal query value, without namespace joining or splitting. URI-encode it once;
+        the server decodes it once. For example, `orders%20&total` becomes `orders%2520%26total`,
+        and `Q1 orders` becomes `Q1%20orders`. A raw `+` decodes to a space; a literal plus requires
+        `%2B`.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        The literal name of one top-level column in the Iceberg table named by target-name. Dots do
+        not select nested fields. The value is not split or parsed as JSON.
+
+        URI-encode the name once; the server decodes it once. For example, `cost+tax` becomes
+        `cost%2Btax`, `a &?=+%` becomes `a%20%26%3F%3D%2B%25`, and `customer.name` stays unchanged.
+        A raw `+` decodes to a space; `%252B` decodes to literal `%2B` without a second decode.
+        Existing schema naming rules apply.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects one page (omitted or `true`) or the complete result in one response (`false`). Both
+        modes use the same filters, authorization, and read guarantees. Response-size and work
+        limits apply in both modes, as described by `pageSize`.
+
+        `pagination=false` must be sent without `pageToken` or `pageSize`, even empty ones. Neither
+        an empty token nor any page size selects full-result mode.
+
+        Only literal `true` and `false` are valid. Empty, other, or repeated values return 400
+        BadRequest, as do conflicting mode parameters. Repetition is invalid even when values agree.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a listing in the default paged mode:
+
+        - Omitted or empty: request the first page.
+        - Non-empty: continue from the supplied token.
+
+        Send the token back unchanged; do not parse or construct it. It is bound to the catalog,
+        definition or target, view, and filters of the request that produced it. Each request is
+        authorized again; a token grants no permission.
+
+        An invalid or expired token, a repeated parameter, or any pageToken combined with
+        `pagination=false` returns 400 BadRequest. Repetition is invalid even when values agree.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on results per page. The value must be a positive integer. Zero, negative,
+        empty, non-integer, or repeated values return 400 BadRequest, with or without a pageToken.
+        Any pageSize combined with `pagination=false` is also invalid.
+
+        When omitted, the server's finite default applies, including on continuation requests.
+        Continuations do not inherit the previous request's size. Values above the server maximum
+        are capped. Pages may contain fewer results than the requested bound.
+
+        Both paged and full-result requests have finite response-size and work limits by default.
+        Deployments may adjust these limits; an absent override does not remove them. A full-result
+        request exceeding a limit returns 400 BadRequest directing the caller to use paged mode with
+        the same target and filters. It never returns a partial success, silently truncates results,
+        or switches delivery modes.
+
+        A paged request reaching its work limit may return a short or empty page with a continuation
+        token. Every eligible result not yet returned must remain reachable through continuation. If
+        the request cannot make safe progress within its work limit, it returns 400 BadRequest.
+        Metadata, storage, or authorization failures return their service error, not an empty page
+        or a work-limit error.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional key for recognizing a completed write after a lost response. Enabled deployments
+        advertise the recognition window as `idempotency-key-lifetime` in the catalog configuration.
+        Expiration ends recognition without indicating whether the original write succeeded.
+
+        Only createTag, updateTag, and renameTag recognize completed writes. Request validation and
+        current authorization for the original operation are still required. Recognition precedes
+        comparison of current-tag-version with the definition's current token.
+
+        A recognized create or update returns 200 with the definition's current state, which may
+        differ from both the original response and the original write. A recognized rename returns
+        204 without another rename, even after later renames. Original responses are not replayed.
+
+        Use one key per logical operation and repeat both key and request unchanged. Reusing a key
+        with different arguments has undefined behavior; no conflict response is promised.
+
+        Recognition ends when the definition is deleted. A same-name replacement inherits no keys.
+        An unrecognized request follows ordinary name lookup, authorization, and version checks.
+
+        The number of keys recognized for one definition at a time is bounded. A write that would
+        add a key beyond this bound returns 503 ServiceUnavailable with Retry-After and is not
+        applied. Capacity exhaustion must not end recognition of an existing key early.
+
+        dropTag, assignTag, and unassignTag accept the header but do not recognize completed writes.

Review Comment:
   These three ops accept the Idempotency-Key header but ignore it. A client that learned Iceberg's idempotency rules will think a retried unassign is safe, but it gets a 404 NoSuchAssignment. The catalog config also advertises the same `idempotency-key-lifetime` for both contracts. Can we reject the header on dropTag/assignTag/unassignTag, or advertise a separate lifetime key for Tag?
   
   <sub>🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.</sub>



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1835 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog. A definition gives a classification a name and
+        a set of allowed values. Assignments select exactly one allowed value for a catalog,
+        namespace, table, view, or column.
+
+        The request supplies a catalog-unique `name`, a non-empty `allowed-values` list, and an
+        optional `description`. Value matching is exact and case-sensitive. CreateTagRequest
+        describes the field constraints.
+
+        Where idempotency is enabled, a retry uses the requested name to locate the original
+        definition. If that definition has been renamed, a free name creates a new definition and an
+        occupied name returns 409 AlreadyExists. Renaming the original definition back within the
+        recognition window allows its key to be recognized again. The Idempotency-Key parameter
+        defines retry behavior.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema validation failures. InvalidJson covers malformed JSON.
+            InvalidIdempotencyKey covers a malformed non-blank header when idempotency support is
+            enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            AlreadyExists means the requested name already belongs to a definition in this catalog.
+
+            Possible error types: AlreadyExists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition identifiers in the catalog
+      operationId: listTags
+      description: |
+        Returns tag definition identifiers in the catalog.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames a tag definition without changing its id, description, allowed values, or
+        assignments. The version token changes when the rename succeeds.
+
+        `current-tag-version` must match the source definition's current token. Comparison and
+        rename are atomic. A stale token or one identifying a different definition returns 409
+        TagVersionMismatch, including after a same-name replacement. Tag.version defines the token's
+        identity and concurrency guarantees.
+
+        A successful rename and a recognized retry both return 204 without a body. A recognized
+        retry does not rename the definition again, even after later renames or other changes. This
+        also applies to a concurrent duplicate that recognizes the completed write. The
+        Idempotency-Key parameter defines recognition. An ordinary request using the old name may
+        return 404 NoSuchTag. Clients needing the current version can load the definition
+        separately.
+
+        Requires permission to delete the source definition and to create a definition in the
+        catalog. Permission to modify the source alone is insufficient. No permission to read the
+        definition is required for rename.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: |
+            The definition was renamed, or the request was recognized as an earlier successful
+            rename. No content is returned. A recognized retry does not rename the definition again.
+        400:
+          description: |
+            BadRequest covers an invalid destination name or a destination equal to the source.
+            ValidationError covers missing required fields, schema-type violations, and a missing,
+            null, empty, or non-string current-tag-version. InvalidJson covers malformed
+            JSON. InvalidIdempotencyKey covers a malformed non-blank header when idempotency support
+            is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the source
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            AlreadyExists means the destination name is occupied. TagVersionMismatch means the
+            supplied token does not match the source definition. Reload the definition before
+            retrying with a new token. CommitConflict means a concurrent change prevented the
+            rename; the request may be retried.
+
+            Possible error types: AlreadyExists, TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Loads the tag definition, including its stable id, current name, description, allowed
+        values, and version token.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the definition's description and allowed-values list. Both fields are required;
+        send the current value to keep it. An explicit JSON null or empty description clears it.
+        Renaming uses renameTag.
+
+        Changing allowed values does not rewrite existing assignments. An assignment whose value is
+        removed remains readable until replaced or unassigned. Later assignments must use a value
+        from the updated list.
+
+        `current-tag-version` must match the definition's current token, including when no fields
+        would change. A mismatch returns 409 TagVersionMismatch. The comparison and update are
+        atomic. Tag.version defines the token's identity and concurrency guarantees.
+
+        A successful update returns the resulting definition and token. A no-op update leaves both
+        unchanged. A concurrent write may invalidate the returned token before the caller receives
+        it.
+
+        A no-op update may or may not register an idempotency key; registration does not advance its
+        version. If its key is not recognized after the definition changes, retrying the no-op
+        returns 409 TagVersionMismatch. A recognized retry returns the current definition without
+        applying the update again, as described by Idempotency-Key.
+
+        Requires permission to modify the definition.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema violations, including a missing, null, empty, or non-string
+            current-tag-version. An explicit null update description is valid. InvalidJson covers
+            malformed JSON. InvalidIdempotencyKey covers a malformed
+            non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            TagVersionMismatch means the supplied token does not match the definition, including a
+            no-op update. CommitConflict means a concurrent change prevented the update. Reload the
+            definition and retry with its current token.
+
+            Possible error types: TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Permanently deletes the tag definition and releases its name.
+
+        Without `detach-all=true`, an assignment on a live target prevents deletion with 400
+        TagInUse. Assignments confirmed orphaned or belonging to soft-dropped targets do not prevent
+        deletion. Deleting the definition makes these assignments permanently ineffective, including
+        if a soft-dropped target is restored later.
+
+        With `detach-all=true`, deletion removes the definition and all its assignments atomically
+        from Tag API reads and reverse lookups. A read beginning after success cannot return any
+        assignment of the deleted definition. A failure before deletion completes leaves visible
+        state unchanged; a later cleanup failure cannot restore the deleted definition or
+        assignments.
+
+        A failure to load a required entity or schema metadata is an error, not evidence of absence.
+        It leaves visible state unchanged. Transient execution failures use the server-error
+        responses.
+
+        Requires permission to delete the definition. `detach-all=true` also requires
+        definition-side permission to detach assignments, even if none exist. No per-target
+        permission is required. This operation does not recognize completed requests through
+        Idempotency-Key.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When true, dropTag also deletes every assignment of this definition across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            TagInUse means an assignment on a live target prevents deletion without
+            `detach-all=true`. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Sets the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces its selected value.
+
+        The JSON body supplies a `target` and `values` containing exactly one value from the
+        definition's current allowed-values list. TagAttachmentTarget defines the supported kinds,
+        address fields, and identity rules. Names are original JSON strings without URI encoding.
+        The target must belong to the catalog addressed by {prefix}.
+
+        An absent, null, or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. Changes to unrelated target properties do not cause a
+        conflict. This operation does not recognize completed requests through Idempotency-Key.
+
+        Requires permission to attach on the definition and to attach a tag on the target. A column
+        target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, null
+            or empty values, empty or duplicate members, more than one selected value, a value
+            exceeding 2000 decoded UTF-8 bytes, or a value absent from the definition's
+            allowed-values list.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, missing `values`, non-null `values` that is not an array, and other
+            schema-type violations. The BadRequest cases above take precedence, including unknown
+            target kinds and null values. InvalidJson covers malformed JSON. InvalidIdempotencyKey
+            covers a malformed non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Removes the direct assignment of this tag definition from one target. Removing a direct
+        assignment may reveal an inherited value. The definition's allowed-values list is not
+        checked.
+
+        The JSON body supplies only a `target`; a `values` field is invalid, including null or an
+        empty array. TagAttachmentTarget defines the supported kinds, address fields, and identity
+        rules. Names are original JSON strings without URI encoding. The target must belong to the
+        catalog addressed by {prefix}.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. Completed requests
+        are not recognized through Idempotency-Key, so retrying a successful removal returns 404
+        while the assignment remains absent. A rejected request changes no assignment. Changes to
+        unrelated target properties do not cause a conflict.
+
+        Requires permission to detach on the definition and to detach a tag from the target. A
+        column target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, or a
+            supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, and other schema-type violations. The BadRequest cases above take
+            precedence, including unknown target kinds and a supplied values field. InvalidJson
+            covers malformed JSON. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column), NoSuchAssignment (the direct assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        Returns targets with a direct assignment of the named tag definition. Targets that only
+        inherit the tag are excluded. Without `value`, all direct assignments are eligible; with it,
+        only assignments selecting that exact, case-sensitive value are eligible.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`. Filtering and
+        work limits may produce a short or empty page with a continuation token.
+
+        Requires read permission on the definition and each reported target. Columns are authorized
+        through their containing tables. Catalog permission does not replace per-target
+        authorization. Targets the caller cannot read are omitted. Authorization-system failures
+        fail the request.
+
+        Dropped, soft-dropped, or missing targets and removed columns are omitted. A failure to load
+        metadata is an error, not evidence that a target is absent.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments selecting this exact, case-sensitive value.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves tags for one target identified by `target-type` and the query parameters that kind
+        requires. The `target-type` parameter defines valid combinations. The optional `view`
+        selects:
+
+        - `direct` (default): assignments stored on the queried target.
+        - `effective`: one winning assignment per tag definition from the target and its parents.
+          The closest assignment wins: column, table or view, nearest namespace, then catalog.
+          Values from different levels are never combined.
+
+        Both views paginate by default. Send `pagination=false` alone to request all tags of the
+        target, subject to the response-size and work limits described by `pageSize`.
+
+        The hierarchy, definitions, and assignments used for one response are consistent with a
+        single logical point in time. No snapshot consistency is guaranteed across separate pages.
+        An effective read considers the complete hierarchy, even when paginated. If it cannot do so,
+        the request
+        fails; it never returns a partial hierarchy or falls back to a direct read.
+
+        Results omit soft-dropped targets and assignments whose definition, target entity, or field
+        is permanently absent.
+
+        Requires read permission on the queried target, or its containing table for a column. This
+        permission covers all effective tags, without per-parent or per-definition authorization.
+
+        Query parameters address the same objects as TagAttachmentTarget: `namespace` carries the
+        namespace levels, `target-name` the table or view name, and `column` the literal column
+        name. For example, sales.eu.customers.email is addressed by:
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        The catalog is addressed by `?target-type=CATALOG`, with no namespace, target-name, or
+        column. Each address parameter and `view` may occur only once. Present empty values and
+        empty namespace levels are invalid. Missing `target-type` returns 400 ValidationError.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            ValidationError covers a missing required `target-type` or other schema validation
+            failures. BadRequest covers unsupported kinds, invalid address combinations, repeated
+            address parameters, empty address values or namespace levels, and empty or unknown
+            `view` or `target-type` values. The BadRequest cases take precedence over schema
+            validation.
+
+            BadRequest also covers invalid or repeated pagination parameters, invalid or expired
+            tokens, conflicting pagination modes, full-result requests exceeding response-size or
+            work limits, and paged requests unable to make safe progress within their work budget.
+
+            Malformed URI escapes may receive an HTTP-layer 400 response without a Tag error
+            payload.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTarget (the target or
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The required target kind. The other address parameters must match it:
+
+        - `CATALOG`: namespace, target-name, and column absent.
+        - `NAMESPACE`: namespace required; target-name and column absent.
+        - `TABLE` or `VIEW`: namespace and target-name required; column absent.
+        - `COLUMN`: namespace, target-name, and column required.
+
+        A missing kind returns 400 ValidationError. An empty or unknown kind, a repeated parameter,
+        or an invalid combination returns 400 BadRequest. A missing kind never selects the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        Namespace levels encoded as one query string using Iceberg namespace query encoding. Join
+        the original names with U+001F, then URI-encode the result once. Each level must be
+        non-empty and must not contain U+001F. Clients must check levels before joining them,
+        because a separator inside a name cannot be distinguished from one between names.
+
+        The server URI-decodes the value once, then splits it on U+001F. Surviving percent sequences
+        remain literal text. A raw `+` decodes to a space; send a literal plus as `%2B`.
+
+        Examples of namespace query values:
+
+        - `["sales", "eu"]` becomes `sales%1Feu`.
+        - `["sales.eu"]` stays `sales.eu`, a single level.
+        - `["R&D", "tax=2026"]` becomes `R%26D%1Ftax%3D2026`.
+        - `["tax%20rate", "%1F"]` becomes `tax%2520rate%1F%251F`.
+        - `["with space", "café"]` becomes `with%20space%1Fcaf%C3%A9`.
+        - `["销售", "日本語"]` becomes `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E`.
+
+        `sales%251Feu` names one literal level, `sales%1Feu`, rather than two levels. Encoding does
+        not relax namespace naming rules: Polaris rejects `/ \ : * ? " < > | # +`, backticks,
+        control characters, and leading or trailing whitespace in namespace, table, and view names.
+
+        Omit this parameter for a catalog target. An empty value, an empty decoded level, or a
+        repeated parameter returns 400 BadRequest. Invalid examples include:
+
+        - `namespace=`: empty value.
+        - `namespace=%1Fsales` or `namespace=sales%1F`: empty first or last level.
+        - `namespace=sales%1F%1Feu`: empty middle level.
+        - `namespace=sales&namespace=eu`: repeated parameter.
+
+        Malformed escapes such as `namespace=%` or `namespace=%GG` may receive an HTTP-layer 400
+        response without a Tag error payload.
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        The table or view name selected by `target-type`. For a column target, this is the
+        containing Iceberg table's name. Existing catalog naming rules apply.
+
+        This is one literal query value, without namespace joining or splitting. URI-encode it once;
+        the server decodes it once. For example, `orders%20&total` becomes `orders%2520%26total`,
+        and `Q1 orders` becomes `Q1%20orders`. A raw `+` decodes to a space; a literal plus requires
+        `%2B`.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        The literal name of one top-level column in the Iceberg table named by target-name. Dots do
+        not select nested fields. The value is not split or parsed as JSON.
+
+        URI-encode the name once; the server decodes it once. For example, `cost+tax` becomes
+        `cost%2Btax`, `a &?=+%` becomes `a%20%26%3F%3D%2B%25`, and `customer.name` stays unchanged.
+        A raw `+` decodes to a space; `%252B` decodes to literal `%2B` without a second decode.
+        Existing schema naming rules apply.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects one page (omitted or `true`) or the complete result in one response (`false`). Both
+        modes use the same filters, authorization, and read guarantees. Response-size and work
+        limits apply in both modes, as described by `pageSize`.
+
+        `pagination=false` must be sent without `pageToken` or `pageSize`, even empty ones. Neither
+        an empty token nor any page size selects full-result mode.
+
+        Only literal `true` and `false` are valid. Empty, other, or repeated values return 400
+        BadRequest, as do conflicting mode parameters. Repetition is invalid even when values agree.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a listing in the default paged mode:
+
+        - Omitted or empty: request the first page.
+        - Non-empty: continue from the supplied token.
+
+        Send the token back unchanged; do not parse or construct it. It is bound to the catalog,
+        definition or target, view, and filters of the request that produced it. Each request is
+        authorized again; a token grants no permission.
+
+        An invalid or expired token, a repeated parameter, or any pageToken combined with
+        `pagination=false` returns 400 BadRequest. Repetition is invalid even when values agree.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on results per page. The value must be a positive integer. Zero, negative,
+        empty, non-integer, or repeated values return 400 BadRequest, with or without a pageToken.
+        Any pageSize combined with `pagination=false` is also invalid.
+
+        When omitted, the server's finite default applies, including on continuation requests.
+        Continuations do not inherit the previous request's size. Values above the server maximum
+        are capped. Pages may contain fewer results than the requested bound.
+
+        Both paged and full-result requests have finite response-size and work limits by default.
+        Deployments may adjust these limits; an absent override does not remove them. A full-result
+        request exceeding a limit returns 400 BadRequest directing the caller to use paged mode with
+        the same target and filters. It never returns a partial success, silently truncates results,
+        or switches delivery modes.
+
+        A paged request reaching its work limit may return a short or empty page with a continuation
+        token. Every eligible result not yet returned must remain reachable through continuation. If
+        the request cannot make safe progress within its work limit, it returns 400 BadRequest.
+        Metadata, storage, or authorization failures return their service error, not an empty page
+        or a work-limit error.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional key for recognizing a completed write after a lost response. Enabled deployments
+        advertise the recognition window as `idempotency-key-lifetime` in the catalog configuration.
+        Expiration ends recognition without indicating whether the original write succeeded.
+
+        Only createTag, updateTag, and renameTag recognize completed writes. Request validation and
+        current authorization for the original operation are still required. Recognition precedes
+        comparison of current-tag-version with the definition's current token.
+
+        A recognized create or update returns 200 with the definition's current state, which may
+        differ from both the original response and the original write. A recognized rename returns
+        204 without another rename, even after later renames. Original responses are not replayed.
+
+        Use one key per logical operation and repeat both key and request unchanged. Reusing a key
+        with different arguments has undefined behavior; no conflict response is promised.
+
+        Recognition ends when the definition is deleted. A same-name replacement inherits no keys.
+        An unrecognized request follows ordinary name lookup, authorization, and version checks.
+
+        The number of keys recognized for one definition at a time is bounded. A write that would
+        add a key beyond this bound returns 503 ServiceUnavailable with Retry-After and is not
+        applied. Capacity exhaustion must not end recognition of an existing key early.
+
+        dropTag, assignTag, and unassignTag accept the header but do not recognize completed writes.
+
+        A missing or blank header supplies no key. With support enabled, a non-blank value must be a
+        UUID or the request returns 400 InvalidIdempotencyKey. Any UUID version is accepted. With

Review Comment:
   Upstream Iceberg requires UUIDv7 keys and replays deterministic 4xx as well as successes. Here any UUID version is accepted, only successful writes are recognized, and responses are never replayed. Is that divergence intentional? If so, can we say so explicitly here so implementers don't try to share the Iceberg idempotency store?
   
   <sub>🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.</sub>



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1835 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog. A definition gives a classification a name and
+        a set of allowed values. Assignments select exactly one allowed value for a catalog,
+        namespace, table, view, or column.
+
+        The request supplies a catalog-unique `name`, a non-empty `allowed-values` list, and an
+        optional `description`. Value matching is exact and case-sensitive. CreateTagRequest
+        describes the field constraints.
+
+        Where idempotency is enabled, a retry uses the requested name to locate the original
+        definition. If that definition has been renamed, a free name creates a new definition and an
+        occupied name returns 409 AlreadyExists. Renaming the original definition back within the
+        recognition window allows its key to be recognized again. The Idempotency-Key parameter
+        defines retry behavior.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema validation failures. InvalidJson covers malformed JSON.
+            InvalidIdempotencyKey covers a malformed non-blank header when idempotency support is
+            enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            AlreadyExists means the requested name already belongs to a definition in this catalog.
+
+            Possible error types: AlreadyExists.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition identifiers in the catalog
+      operationId: listTags
+      description: |
+        Returns tag definition identifiers in the catalog.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames a tag definition without changing its id, description, allowed values, or
+        assignments. The version token changes when the rename succeeds.
+
+        `current-tag-version` must match the source definition's current token. Comparison and
+        rename are atomic. A stale token or one identifying a different definition returns 409
+        TagVersionMismatch, including after a same-name replacement. Tag.version defines the token's
+        identity and concurrency guarantees.
+
+        A successful rename and a recognized retry both return 204 without a body. A recognized
+        retry does not rename the definition again, even after later renames or other changes. This
+        also applies to a concurrent duplicate that recognizes the completed write. The
+        Idempotency-Key parameter defines recognition. An ordinary request using the old name may
+        return 404 NoSuchTag. Clients needing the current version can load the definition
+        separately.
+
+        Requires permission to delete the source definition and to create a definition in the
+        catalog. Permission to modify the source alone is insufficient. No permission to read the
+        definition is required for rename.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: |
+            The definition was renamed, or the request was recognized as an earlier successful
+            rename. No content is returned. A recognized retry does not rename the definition again.
+        400:
+          description: |
+            BadRequest covers an invalid destination name or a destination equal to the source.
+            ValidationError covers missing required fields, schema-type violations, and a missing,
+            null, empty, or non-string current-tag-version. InvalidJson covers malformed
+            JSON. InvalidIdempotencyKey covers a malformed non-blank header when idempotency support
+            is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the source
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            AlreadyExists means the destination name is occupied. TagVersionMismatch means the
+            supplied token does not match the source definition. Reload the definition before
+            retrying with a new token. CommitConflict means a concurrent change prevented the
+            rename; the request may be retried.
+
+            Possible error types: AlreadyExists, TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Loads the tag definition, including its stable id, current name, description, allowed
+        values, and version token.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the definition's description and allowed-values list. Both fields are required;
+        send the current value to keep it. An explicit JSON null or empty description clears it.
+        Renaming uses renameTag.
+
+        Changing allowed values does not rewrite existing assignments. An assignment whose value is
+        removed remains readable until replaced or unassigned. Later assignments must use a value
+        from the updated list.
+
+        `current-tag-version` must match the definition's current token, including when no fields
+        would change. A mismatch returns 409 TagVersionMismatch. The comparison and update are
+        atomic. Tag.version defines the token's identity and concurrency guarantees.
+
+        A successful update returns the resulting definition and token. A no-op update leaves both
+        unchanged. A concurrent write may invalidate the returned token before the caller receives
+        it.
+
+        A no-op update may or may not register an idempotency key; registration does not advance its
+        version. If its key is not recognized after the definition changes, retrying the no-op
+        returns 409 TagVersionMismatch. A recognized retry returns the current definition without
+        applying the update again, as described by Idempotency-Key.
+
+        Requires permission to modify the definition.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            BadRequest covers an empty allowed-values list, duplicate or empty members, or a member
+            exceeding 2000 decoded UTF-8 bytes. ValidationError covers missing required fields, null
+            allowed-values, and schema violations, including a missing, null, empty, or non-string
+            current-tag-version. An explicit null update description is valid. InvalidJson covers
+            malformed JSON. InvalidIdempotencyKey covers a malformed
+            non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            TagVersionMismatch means the supplied token does not match the definition, including a
+            no-op update. CommitConflict means a concurrent change prevented the update. Reload the
+            definition and retry with its current token.
+
+            Possible error types: TagVersionMismatch, CommitConflict.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Permanently deletes the tag definition and releases its name.
+
+        Without `detach-all=true`, an assignment on a live target prevents deletion with 400
+        TagInUse. Assignments confirmed orphaned or belonging to soft-dropped targets do not prevent
+        deletion. Deleting the definition makes these assignments permanently ineffective, including
+        if a soft-dropped target is restored later.
+
+        With `detach-all=true`, deletion removes the definition and all its assignments atomically
+        from Tag API reads and reverse lookups. A read beginning after success cannot return any
+        assignment of the deleted definition. A failure before deletion completes leaves visible
+        state unchanged; a later cleanup failure cannot restore the deleted definition or
+        assignments.
+
+        A failure to load a required entity or schema metadata is an error, not evidence of absence.
+        It leaves visible state unchanged. Transient execution failures use the server-error
+        responses.
+
+        Requires permission to delete the definition. `detach-all=true` also requires
+        definition-side permission to detach assignments, even if none exist. No per-target
+        permission is required. This operation does not recognize completed requests through
+        Idempotency-Key.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When true, dropTag also deletes every assignment of this definition across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            TagInUse means an assignment on a live target prevents deletion without
+            `detach-all=true`. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Sets the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces its selected value.
+
+        The JSON body supplies a `target` and `values` containing exactly one value from the
+        definition's current allowed-values list. TagAttachmentTarget defines the supported kinds,
+        address fields, and identity rules. Names are original JSON strings without URI encoding.
+        The target must belong to the catalog addressed by {prefix}.
+
+        An absent, null, or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. Changes to unrelated target properties do not cause a
+        conflict. This operation does not recognize completed requests through Idempotency-Key.
+
+        Requires permission to attach on the definition and to attach a tag on the target. A column
+        target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, null
+            or empty values, empty or duplicate members, more than one selected value, a value
+            exceeding 2000 decoded UTF-8 bytes, or a value absent from the definition's
+            allowed-values list.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, missing `values`, non-null `values` that is not an array, and other
+            schema-type violations. The BadRequest cases above take precedence, including unknown
+            target kinds and null values. InvalidJson covers malformed JSON. InvalidIdempotencyKey
+            covers a malformed non-blank header when idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Removes the direct assignment of this tag definition from one target. Removing a direct
+        assignment may reveal an inherited value. The definition's allowed-values list is not
+        checked.
+
+        The JSON body supplies only a `target`; a `values` field is invalid, including null or an
+        empty array. TagAttachmentTarget defines the supported kinds, address fields, and identity
+        rules. Names are original JSON strings without URI encoding. The target must belong to the
+        catalog addressed by {prefix}.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. Completed requests
+        are not recognized through Idempotency-Key, so retrying a successful removal returns 404
+        while the assignment remains absent. A rejected request changes no assignment. Changes to
+        unrelated target properties do not cause a conflict.
+
+        Requires permission to detach on the definition and to detach a tag from the target. A
+        column target is authorized through its containing table.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, an incomplete or malformed address, or a
+            supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null, or non-object `target`, missing or null
+            `target.type`, and other schema-type violations. The BadRequest cases above take
+            precedence, including unknown target kinds and a supplied values field. InvalidJson
+            covers malformed JSON. InvalidIdempotencyKey covers a malformed non-blank header when
+            idempotency support is enabled.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the definition),
+            NoSuchTarget (the target or column), NoSuchAssignment (the direct assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        Returns targets with a direct assignment of the named tag definition. Targets that only
+        inherit the tag are excluded. Without `value`, all direct assignments are eligible; with it,
+        only assignments selecting that exact, case-sensitive value are eligible.
+
+        Pagination is enabled by default. Send `pagination=false` alone to request the complete
+        result, subject to the response-size and work limits described by `pageSize`. Filtering and
+        work limits may produce a short or empty page with a continuation token.
+
+        Requires read permission on the definition and each reported target. Columns are authorized
+        through their containing tables. Catalog permission does not replace per-target
+        authorization. Targets the caller cannot read are omitted. Authorization-system failures
+        fail the request.
+
+        Dropped, soft-dropped, or missing targets and removed columns are omitted. A failure to load
+        metadata is an error, not evidence that a target is absent.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments selecting this exact, case-sensitive value.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            ValidationError covers schema validation failures. BadRequest covers invalid or repeated
+            pagination parameters, invalid or expired tokens, conflicting pagination modes,
+            full-result requests exceeding response-size or work limits, and paged requests unable
+            to make safe progress within their work budget. The pagination parameters define these
+            cases.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTag (the tag
+            definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves tags for one target identified by `target-type` and the query parameters that kind
+        requires. The `target-type` parameter defines valid combinations. The optional `view`
+        selects:
+
+        - `direct` (default): assignments stored on the queried target.
+        - `effective`: one winning assignment per tag definition from the target and its parents.
+          The closest assignment wins: column, table or view, nearest namespace, then catalog.
+          Values from different levels are never combined.
+
+        Both views paginate by default. Send `pagination=false` alone to request all tags of the
+        target, subject to the response-size and work limits described by `pageSize`.
+
+        The hierarchy, definitions, and assignments used for one response are consistent with a
+        single logical point in time. No snapshot consistency is guaranteed across separate pages.
+        An effective read considers the complete hierarchy, even when paginated. If it cannot do so,
+        the request
+        fails; it never returns a partial hierarchy or falls back to a direct read.
+
+        Results omit soft-dropped targets and assignments whose definition, target entity, or field
+        is permanently absent.
+
+        Requires read permission on the queried target, or its containing table for a column. This
+        permission covers all effective tags, without per-parent or per-definition authorization.
+
+        Query parameters address the same objects as TagAttachmentTarget: `namespace` carries the
+        namespace levels, `target-name` the table or view name, and `column` the literal column
+        name. For example, sales.eu.customers.email is addressed by:
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        The catalog is addressed by `?target-type=CATALOG`, with no namespace, target-name, or
+        column. Each address parameter and `view` may occur only once. Present empty values and
+        empty namespace levels are invalid. Missing `target-type` returns 400 ValidationError.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            ValidationError covers a missing required `target-type` or other schema validation
+            failures. BadRequest covers unsupported kinds, invalid address combinations, repeated
+            address parameters, empty address values or namespace levels, and empty or unknown
+            `view` or `target-type` values. The BadRequest cases take precedence over schema
+            validation.
+
+            BadRequest also covers invalid or repeated pagination parameters, invalid or expired
+            tokens, conflicting pagination modes, full-result requests exceeding response-size or
+            work limits, and paged requests unable to make safe progress within their work budget.
+
+            Malformed URI escapes may receive an HTTP-layer 400 response without a Tag error
+            payload.
+
+            Possible error types: ValidationError, BadRequest.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Possible error types: NoSuchCatalog (the addressed catalog), NoSuchTarget (the target or
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The required target kind. The other address parameters must match it:
+
+        - `CATALOG`: namespace, target-name, and column absent.
+        - `NAMESPACE`: namespace required; target-name and column absent.
+        - `TABLE` or `VIEW`: namespace and target-name required; column absent.
+        - `COLUMN`: namespace, target-name, and column required.
+
+        A missing kind returns 400 ValidationError. An empty or unknown kind, a repeated parameter,
+        or an invalid combination returns 400 BadRequest. A missing kind never selects the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        Namespace levels encoded as one query string using Iceberg namespace query encoding. Join
+        the original names with U+001F, then URI-encode the result once. Each level must be
+        non-empty and must not contain U+001F. Clients must check levels before joining them,
+        because a separator inside a name cannot be distinguished from one between names.
+
+        The server URI-decodes the value once, then splits it on U+001F. Surviving percent sequences
+        remain literal text. A raw `+` decodes to a space; send a literal plus as `%2B`.
+
+        Examples of namespace query values:
+
+        - `["sales", "eu"]` becomes `sales%1Feu`.
+        - `["sales.eu"]` stays `sales.eu`, a single level.
+        - `["R&D", "tax=2026"]` becomes `R%26D%1Ftax%3D2026`.
+        - `["tax%20rate", "%1F"]` becomes `tax%2520rate%1F%251F`.
+        - `["with space", "café"]` becomes `with%20space%1Fcaf%C3%A9`.
+        - `["销售", "日本語"]` becomes `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E`.
+
+        `sales%251Feu` names one literal level, `sales%1Feu`, rather than two levels. Encoding does
+        not relax namespace naming rules: Polaris rejects `/ \ : * ? " < > | # +`, backticks,
+        control characters, and leading or trailing whitespace in namespace, table, and view names.
+
+        Omit this parameter for a catalog target. An empty value, an empty decoded level, or a
+        repeated parameter returns 400 BadRequest. Invalid examples include:
+
+        - `namespace=`: empty value.
+        - `namespace=%1Fsales` or `namespace=sales%1F`: empty first or last level.
+        - `namespace=sales%1F%1Feu`: empty middle level.
+        - `namespace=sales&namespace=eu`: repeated parameter.
+
+        Malformed escapes such as `namespace=%` or `namespace=%GG` may receive an HTTP-layer 400
+        response without a Tag error payload.
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        The table or view name selected by `target-type`. For a column target, this is the
+        containing Iceberg table's name. Existing catalog naming rules apply.
+
+        This is one literal query value, without namespace joining or splitting. URI-encode it once;
+        the server decodes it once. For example, `orders%20&total` becomes `orders%2520%26total`,
+        and `Q1 orders` becomes `Q1%20orders`. A raw `+` decodes to a space; a literal plus requires
+        `%2B`.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        The literal name of one top-level column in the Iceberg table named by target-name. Dots do
+        not select nested fields. The value is not split or parsed as JSON.
+
+        URI-encode the name once; the server decodes it once. For example, `cost+tax` becomes
+        `cost%2Btax`, `a &?=+%` becomes `a%20%26%3F%3D%2B%25`, and `customer.name` stays unchanged.
+        A raw `+` decodes to a space; `%252B` decodes to literal `%2B` without a second decode.
+        Existing schema naming rules apply.
+
+        A present empty value or repeated parameter returns 400 BadRequest.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects one page (omitted or `true`) or the complete result in one response (`false`). Both
+        modes use the same filters, authorization, and read guarantees. Response-size and work
+        limits apply in both modes, as described by `pageSize`.
+
+        `pagination=false` must be sent without `pageToken` or `pageSize`, even empty ones. Neither
+        an empty token nor any page size selects full-result mode.
+
+        Only literal `true` and `false` are valid. Empty, other, or repeated values return 400
+        BadRequest, as do conflicting mode parameters. Repetition is invalid even when values agree.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a listing in the default paged mode:
+
+        - Omitted or empty: request the first page.
+        - Non-empty: continue from the supplied token.
+
+        Send the token back unchanged; do not parse or construct it. It is bound to the catalog,
+        definition or target, view, and filters of the request that produced it. Each request is
+        authorized again; a token grants no permission.
+
+        An invalid or expired token, a repeated parameter, or any pageToken combined with
+        `pagination=false` returns 400 BadRequest. Repetition is invalid even when values agree.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on results per page. The value must be a positive integer. Zero, negative,
+        empty, non-integer, or repeated values return 400 BadRequest, with or without a pageToken.
+        Any pageSize combined with `pagination=false` is also invalid.
+
+        When omitted, the server's finite default applies, including on continuation requests.
+        Continuations do not inherit the previous request's size. Values above the server maximum
+        are capped. Pages may contain fewer results than the requested bound.
+
+        Both paged and full-result requests have finite response-size and work limits by default.
+        Deployments may adjust these limits; an absent override does not remove them. A full-result
+        request exceeding a limit returns 400 BadRequest directing the caller to use paged mode with
+        the same target and filters. It never returns a partial success, silently truncates results,
+        or switches delivery modes.
+
+        A paged request reaching its work limit may return a short or empty page with a continuation
+        token. Every eligible result not yet returned must remain reachable through continuation. If
+        the request cannot make safe progress within its work limit, it returns 400 BadRequest.
+        Metadata, storage, or authorization failures return their service error, not an empty page
+        or a work-limit error.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional key for recognizing a completed write after a lost response. Enabled deployments
+        advertise the recognition window as `idempotency-key-lifetime` in the catalog configuration.
+        Expiration ends recognition without indicating whether the original write succeeded.
+
+        Only createTag, updateTag, and renameTag recognize completed writes. Request validation and
+        current authorization for the original operation are still required. Recognition precedes
+        comparison of current-tag-version with the definition's current token.
+
+        A recognized create or update returns 200 with the definition's current state, which may
+        differ from both the original response and the original write. A recognized rename returns
+        204 without another rename, even after later renames. Original responses are not replayed.
+
+        Use one key per logical operation and repeat both key and request unchanged. Reusing a key
+        with different arguments has undefined behavior; no conflict response is promised.
+
+        Recognition ends when the definition is deleted. A same-name replacement inherits no keys.
+        An unrecognized request follows ordinary name lookup, authorization, and version checks.
+
+        The number of keys recognized for one definition at a time is bounded. A write that would
+        add a key beyond this bound returns 503 ServiceUnavailable with Retry-After and is not
+        applied. Capacity exhaustion must not end recognition of an existing key early.
+
+        dropTag, assignTag, and unassignTag accept the header but do not recognize completed writes.
+
+        A missing or blank header supplies no key. With support enabled, a non-blank value must be a
+        UUID or the request returns 400 InvalidIdempotencyKey. Any UUID version is accepted. With
+        support disabled, the header is ignored and the operation follows its ordinary path.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog containing the tag definitions and assignments addressed by this
+        request. Polaris maps the prefix to a catalog name; the default mapping uses the name
+        itself.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition's name, subject to TagName constraints. Namespace, table, view, and
+        column names follow their own naming rules.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque continuation token. A non-empty value means there is more to read, including after
+        a short or empty page. Absent or null means completion; the server never returns an empty
+        string. A full-result response carries no continuation token. Send it back unchanged as
+        `pageToken`.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        The error response body for Polaris-specific APIs, containing the error's HTTP status code,
+        type, and message.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description: |
+        A catalog-unique tag definition name of at most 256 characters, containing only ASCII
+        letters, digits, hyphens, and underscores. Leading hyphens are allowed.
+      maxLength: 256
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned opaque identity for comparisons within one realm and catalog. It survives
+        updates and renames. Deletion and recreation under the same name produces a different id. Do
+        not parse it or infer ordering. Operations address tags by name and use current-tag-version
+        for concurrency checks.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+
+        - `CATALOG`: the catalog addressed by {prefix}.
+        - `NAMESPACE`: a namespace.
+        - `TABLE`: a whole Iceberg table or supported generic table.
+        - `VIEW`: a whole Iceberg view.
+        - `COLUMN`: one top-level column of an Iceberg table. Generic-table columns, view columns,
+          and nested fields are unsupported.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - allowed-values
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name. Renaming changes this value while preserving its id.
+        description:
+          type: string
+          description: |
+            Optional classification description; it does not affect matching or inheritance.
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The allowed assignment values: distinct, non-empty strings matched exactly and
+            case-sensitively. The list must be non-empty. Each value is limited to 2000 bytes of
+            decoded UTF-8 text, excluding JSON escaping. Invalid contents return 400 BadRequest.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty concurrency token. Send it unchanged as current-tag-version; do not
+            parse, order, or increment it. A definition-changing write advances the token. A no-op
+            update returns the current token without advancing it.
+
+            The fields and token in one response describe the same revision. Token comparison and
+            definition mutation are atomic across all supported definition-write paths, including
+            native writes outside this API.
+
+            A definition change invalidates earlier tokens even if its fields later return to their
+            previous values. A token cannot authorize an update or rename of a same-name replacement
+            or a different definition renamed into that name. No-op updates also require a matching
+            token. Idempotency recognition precedes token comparison, as described by
+            Idempotency-Key.
+
+            Unrelated catalog changes may invalidate the token even when this definition is
+            unchanged.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full
+        definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current catalog-unique name, used to address requests.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The new definition's catalog-unique name, subject to TagName constraints.
+        description:
+          type: string
+          description: |
+            Optional classification description; it does not affect matching or inheritance.
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The allowed assignment values: distinct, non-empty strings matched exactly and
+            case-sensitively. The list must be non-empty. Each value is limited to 2000 bytes of
+            decoded UTF-8 text, excluding JSON escaping. Invalid contents return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition and the version token required to update it.
+      required:
+        - description
+        - allowed-values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The required replacement description. Explicit null or an empty string clears it.
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The allowed assignment values: distinct, non-empty strings matched exactly and
+            case-sensitively. The list must be non-empty. Each value is limited to 2000 bytes of
+            decoded UTF-8 text, excluding JSON escaping. Invalid contents return 400 BadRequest.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current token from create, load, or update. Send it unchanged.
+            Tag.version defines identity and concurrency semantics.
+
+    RenameTagRequest:
+      type: object
+      description: |
+        The source name, destination name, and current version token for a rename.
+      required:
+        - source
+        - destination
+        - current-tag-version
+      properties:
+        source:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The source definition's current name in the addressed catalog.
+        destination:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            A valid TagName that differs from source and is unused in the catalog.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current token from create, load, or update. Send it unchanged.
+            Tag.version defines identity and concurrency semantics.
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '#/components/schemas/NextPageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        A catalog object or top-level Iceberg column, used in assignment writes and read results.
+        The required `type` determines the fields:
+
+        - `CATALOG`: path and column absent or empty.
+        - `NAMESPACE`: path contains one or more namespace levels; column absent or empty.
+        - `TABLE` or `VIEW`: path contains namespace levels followed by the entity name; column
+          absent or empty.
+        - `COLUMN`: path contains namespace levels followed by the Iceberg table name; column
+          contains exactly one non-empty top-level column name.
+
+        Supplied path and column fields must be arrays of strings, never null. Each path member must
+        be non-empty; namespace levels must not contain U+001F. Names are original strings without
+        URI encoding, percent decoding, dot splitting, or path normalization. For example, ["."] and
+        [".."] address literal top-level column names. Catalog and schema naming rules apply.
+
+        Assignments follow the identity of the definition and target, and the Iceberg field id for a
+        column. Identity-preserving renames retain assignments. Dropping and recreating an object
+        under the same name does not transfer its previous assignments.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            Namespace levels followed by the table or view name when applicable, ordered from parent
+            to child. Omit or use an empty array for a catalog. Members must be non-empty; a
+            namespace level containing U+001F returns 400 BadRequest.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For a column target, exactly one non-empty, literal top-level column name.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      description: |
+        The target and selected value for a direct assignment.
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            Exactly one value from the definition's current allowed-values list. It must be
+            non-empty and at most 2000 decoded UTF-8 bytes, excluding JSON escaping. Invalid
+            contents return 400 BadRequest.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      description: |
+        The target whose direct assignment is removed. A values field must not be supplied,
+        including null or an empty array; it returns 400 BadRequest.
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag returned by getObjectTags:
+
+        - `tag`: the definition's stable id and current name.
+        - `values`: exactly one selected value.
+        - `apply-method`: `DIRECT` when stored on the queried target, or `INHERITED` when the
+          winning assignment is stored on a parent. The server returns only these values; clients
+          must tolerate unknown values.
+        - `assigned-at`: the target storing the winning assignment, either the queried target or a
+          parent.
+      required:
+        - tag
+        - values
+        - apply-method
+        - assigned-at
+      properties:
+        tag:
+          $ref: '#/components/schemas/TagIdentifier'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "DIRECT"
+        assigned-at:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    GetObjectTagsResponse:
+      type: object
+      required:
+        - object-tags
+      properties:
+        next-page-token:
+          $ref: '#/components/schemas/NextPageToken'
+        object-tags:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/ObjectTag'
+
+    TaggedObject:
+      type: object
+      description: |
+        One direct assignment returned by listObjectsByTag. Its apply-method is never INHERITED.
+      required:
+        - target
+        - values
+        - apply-method
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          uniqueItems: true
+          items:
+            type: string
+        apply-method:
+          type: string
+          example: "DIRECT"
+
+    ListObjectsByTagResponse:
+      type: object
+      required:
+        - objects
+      properties:
+        next-page-token:
+          $ref: '#/components/schemas/NextPageToken'
+        objects:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TaggedObject'
+
+  responses:
+    TagBadRequestResponse:
+      description: |
+        ValidationError covers a missing required value or a schema-type violation. BadRequest
+        covers other invalid input. Operation-specific error classifications take precedence.
+
+        Possible error types: ValidationError, BadRequest.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PolarisErrorResponse'
+          examples:
+            ValidationError:
+              summary: A path or query value does not satisfy its schema
+              value: {
+                "error": {
+                  "message": "tag-name must match ^[A-Za-z0-9\\-_]+$",
+                  "type": "ValidationError",
+                  "code": 400
+                }
+              }
+
+    TagUnauthorizedResponse:
+      description: |
+        Unauthorized - the request carries no credentials, or credentials the server cannot
+        authenticate.
+
+        Possible error types: Unauthorized.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PolarisErrorResponse'
+          example: {
+            "error": {
+              "message": "Not authorized",
+              "type": "Unauthorized",
+              "code": 401
+            }
+          }
+
+    TagForbiddenResponse:
+      description: |
+        Forbidden - the caller is authenticated but lacks the permission this operation requires.
+
+        Possible error types: Forbidden.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PolarisErrorResponse'
+          example: {
+            "error": {
+              "message": "Not authorized to perform this operation",
+              "type": "Forbidden",
+              "code": 403
+            }
+          }
+
+    TagServiceUnavailableResponse:
+      description: |
+        The server cannot handle the request now; the caller may retry.
+
+        For createTag, updateTag, and renameTag, exhausted idempotency recognition capacity also
+        returns this response with Retry-After. The write is not applied and existing recognition is
+        preserved.
+
+        Possible error types: ServiceUnavailable.
+      headers:
+        Retry-After:
+          description: |
+            How long to wait before retrying, as seconds or an HTTP-date. Present when the server
+            can state a delay, and always for exhausted idempotency recognition capacity.
+          schema:
+            type: string
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PolarisErrorResponse'
+          example: {
+            "error": {
+              "message": "Service is unavailable, please retry",
+              "type": "ServiceUnavailable",
+              "code": 503
+            }
+          }
+
+    TagServerErrorResponse:
+      description: |
+        An unexpected server failure or a required dependency failure not covered by another
+        response. The response uses type InternalServerError and code 500.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/PolarisErrorResponse'
+          example: {
+            "error": {
+              "message": "Internal Server Error",
+              "type": "InternalServerError",
+              "code": 500
+            }
+          }
+
+    CreateTagResponse:
+      description: The created definition, returned directly
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Tag'
+
+    LoadTagResponse:
+      description: The definition, returned directly
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Tag'
+
+    UpdateTagResponse:
+      description: The updated definition, returned directly
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      description: |
+        One page of tag definition identifiers, or the complete list for a full-result request.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListTagsResponse'
+          examples:
+            ListTagsResponseNonEmpty:
+              $ref: '#/components/examples/ListTagsNonEmptyExample'
+            ListTagsResponseEmpty:
+              $ref: '#/components/examples/ListTagsEmptyExample'
+
+    GetObjectTagsResponse:
+      description: |
+        One page of the queried target's direct or effective tags, or all tags for a full-result
+        request.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/GetObjectTagsResponse'
+          examples:
+            GetObjectTagsResponseEffective:
+              $ref: '#/components/examples/GetObjectTagsEffectiveExample'
+
+    ListObjectsByTagResponse:
+      description: |
+        One page of targets with a direct assignment, or the complete list for a full-result
+        request.
+
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ListObjectsByTagResponse'
+          examples:
+            ListObjectsByTagResponseNonEmpty:
+              $ref: '#/components/examples/ListObjectsByTagNonEmptyExample'
+
+  examples:
+    NoSuchTagError:
+      summary: The requested tag definition does not exist
+      value: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    TagAlreadyExistsError:
+      summary: A tag definition with the requested name already exists
+      value: {
+        "error": {
+          "message": "A tag definition with the given name already exists in the catalog",
+          "type": "AlreadyExists",
+          "code": 409
+        }
+      }
+
+    TagVersionMismatchError:
+      summary: The supplied current-tag-version is not the definition's current token
+      value: {
+        "error": {
+          "message": "current-tag-version does not match the definition's current token",
+          "type": "TagVersionMismatch",
+          "code": 409
+        }
+      }
+
+    TagCommitConflictError:
+      summary: The definition was concurrently modified; retry
+      value: {
+        "error": {
+          "message": "Concurrent modification on tag 'sensitivity'; retry later",
+          "type": "CommitConflict",
+          "code": 409
+        }
+      }
+    TagInUseError:
+      summary: Assignments of the tag definition remain
+      value: {
+        "error": {
+          "message": "The tag is assigned to live targets; set detach-all=true to delete it",
+          "type": "TagInUse",
+          "code": 400
+        }
+      }
+
+    NoSuchTargetError:

Review Comment:
   This collides with `NoSuchTargetError` in policy-apis.yaml, so the bundler renames it to `examples-NoSuchTargetError` in the generated spec. Can we call it `TagNoSuchTargetError` to match the other Tag* examples?
   
   <sub>🤖 AI-generated review comment — agents make mistakes, so please verify before acting on it.</sub>



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4021103721


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target

Review Comment:
   I'll move the target into the URI using the same query parameters as DELETE, with only `values` in the PUT body. This keeps target addressing consistent across both operations.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4021043496


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'

Review Comment:
   I'll define the parameter locally as `catalog-name` and make its catalog scope explicit in the OpenAPI spec and design doc.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4041947717


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:

Review Comment:
   OK, I’ll define it as a read-only, opaque string for identity comparison within the same realm and catalog. It will remain unchanged across renames and updates, and deleting and recreating a tag will produce a different ID. Clients can use it to recognize the same tag under a new name or distinguish a same-name replacement.
   
   Operations will continue to address tags by name, with `current-tag-version` handling concurrency checks. The ID identifies the tag, not its current definition state, and clients should not parse it or infer ordering or other semantics from its representation.
   
   For the implementation, I’d reuse the existing Polaris entity ID, serialized as a string, rather than introduce a separate UUID. That provides the identity comparison described here without maintaining a second identifier. Cross-catalog synchronization can maintain source-to-destination mappings without requiring globally unique or preserved IDs.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4067190116


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1,3 +1,22 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one

Review Comment:
   Split out into #5559. RAT recognizes the bundle’s info.license.url as an Apache license, so the license check passes even without the header.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098265476


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape

Review Comment:
   Hmmm, yea, the bodyless response isn’t the cause of the uncertainty. I’ll shorten this to the useful retry behavior: after a successful rename, the old name may return 404, while a recognized retry returns 204 without renaming again.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098416048


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds
+        that operation's privilege. A recognized createTag or updateTag retry answers 200 with the
+        definition's current state: not the original response, and not the state the original request wrote
+        if the definition has changed since. A recognized renameTag retry answers 204 without renaming
+        again, even after later renames, and the server never renames a definition back to satisfy a retry.
+        Recognition happens before the supplied `current-tag-version` is compared with the definition's
+        current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        The server records the key, not the request, so reusing one key with different arguments is a client
+        error: the outcome is undefined and no conflict response is promised. The server does not replay the
+        original response body.
+
+        Recognition ends when the definition is deleted. A request the server cannot match to a live key on
+        a live definition follows the ordinary path, with the usual name lookup, authorization and version
+        check and the errors those produce.
+
+        A definition holds a bounded number of live keys. When that set is full, a write that would record
+        another key is rejected with 503 ServiceUnavailable and a Retry-After header rather than evicting a
+        live key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none of
+        them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          minimum: 400
+          maximum: 600
+          description: HTTP response code
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes when encoded as UTF-8. A longer value returns
+            400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement. A new no-op update still has to match the current
+            token. Where an already completed update or rename is recognized from an Idempotency-Key, that
+            recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest.
+        current-tag-version:

Review Comment:
   Separating the precondition from the fields being updated makes sense. I slightly prefer keeping current-tag-version in the request body, but a required query parameter would work too.
   
   On the response side, I’d keep version on Tag because it identifies the returned snapshot. That would also let us return Tag directly, as you suggested in the other thread. Would that work for you?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4124906558


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still
+        needs TAG_DROP on the source definition together with TAG_CREATE on the catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled, the key is still live on
+        the definition the original request created, updated or renamed, and the caller currently holds
+        that operation's privilege. A recognized createTag or updateTag retry answers 200 with the
+        definition's current state: not the original response, and not the state the original request wrote
+        if the definition has changed since. A recognized renameTag retry answers 204 without renaming
+        again, even after later renames, and the server never renames a definition back to satisfy a retry.
+        Recognition happens before the supplied `current-tag-version` is compared with the definition's
+        current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        The server records the key, not the request, so reusing one key with different arguments is a client
+        error: the outcome is undefined and no conflict response is promised. The server does not replay the
+        original response body.
+
+        Recognition ends when the definition is deleted. A request the server cannot match to a live key on
+        a live definition follows the ordinary path, with the usual name lookup, authorization and version
+        check and the errors those produce.
+
+        A definition holds a bounded number of live keys. When that set is full, a write that would record
+        another key is rejected with 503 ServiceUnavailable and a Retry-After header rather than evicting a
+        live key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none of
+        them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          minimum: 400
+          maximum: 600
+          description: HTTP response code
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TagId:
+      type: string
+      readOnly: true
+      description: |
+        A server-assigned, opaque identifier for the tag definition, for comparison within the same realm and
+        catalog. It is stable for the life of the definition, so a client can recognize the same definition
+        under a new name after a rename. A definition that is deleted and recreated under the same name receives a
+        different id, which lets a client distinguish a same-name replacement. Clients must not parse it or
+        infer ordering or any other meaning from its representation.
+
+        The id identifies the tag, not its current definition state: operations continue to address
+        definitions by name, and `current-tag-version` remains the concurrency check.
+      example: 'tag-8f31c2'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. CATALOG: the catalog identified by {prefix}.
+        2. NAMESPACE: a namespace.
+        3. TABLE: a whole table. This covers Iceberg tables and the generic tables this implementation
+           supports.
+        4. VIEW: a whole Iceberg view.
+        5. COLUMN: one top-level column of an Iceberg table. Column targets are limited to Iceberg tables:
+           generic tables and views define no stable column identifier in v1, so their columns cannot be
+           addressed. That limit applies to columns only and does not restrict VIEW targets.
+      enum:
+        - CATALOG
+        - NAMESPACE
+        - TABLE
+        - VIEW
+        - COLUMN
+      example: TABLE
+
+    Tag:
+      type: object
+      description: |
+        A tag definition.
+      required:
+        - id
+        - name
+        - values
+        - target-types
+        - version
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's name, unique within the catalog. It matches the TagName pattern, so it never
+            contains a slash and needs no path encoding. Renaming a definition changes this value while
+            `id` stays the same.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance. An update replaces it, and either an explicit JSON null or an empty string on
+            update clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member,
+            and each value is limited to 2000 bytes when encoded as UTF-8. A longer value returns
+            400 BadRequest.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify, directly or through inheritance. The response
+            always carries the explicit set stored for the definition, including when creation defaulted it
+            to every v1 kind. The set is create-only and also scopes inheritance: an excluded intermediate
+            kind does not stop inheritance to an allowed descendant.
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+          description: |
+            An opaque, non-empty, server-managed token for optimistic concurrency. Send it back unchanged
+            as `current-tag-version`; do not parse, order or increment it. Every successful write changes
+            it, while a request that changes nothing returns the current token without advancing it.
+
+            The fields and the token in one response describe the same revision of the definition. The
+            token check and the definition change are atomic, and every supported definition-write path
+            takes part, including native writes made outside this API.
+
+            A definition change invalidates earlier tokens even if the fields later return to their
+            previous values, and a token issued for a definition that was since deleted cannot authorize an
+            update or rename of a same-name replacement. A new no-op update still has to match the current
+            token. Where an already completed update or rename is recognized from an Idempotency-Key, that
+            recognition happens before the token comparison.
+
+            An implementation may use a catalog-wide revision, so an unrelated change elsewhere in the
+            catalog may invalidate a token although this definition did not change.
+
+    TagIdentifier:
+      type: object
+      description: |
+        A tag definition named in a list result or an object-tag response, without its full definition.
+      required:
+        - id
+        - name
+      properties:
+        id:
+          $ref: '#/components/schemas/TagId'
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The definition's current name, unique within the catalog. Requests address definitions by this
+            name; this object introduces no id-based addressing.
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - values
+      properties:
+        name:
+          allOf:
+            - $ref: '#/components/schemas/TagName'
+          description: |
+            The name for the new definition. It must be unique within the catalog and must match the
+            TagName pattern.
+        description:
+          type: string
+          description: |
+            Optional text explaining the classification. It carries no meaning for matching or
+            inheritance.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The choices a later assignment may select. The list is required and must hold at least one
+            member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            The target kinds this definition may classify. **Optional.** Omitting the field selects every
+            v1 target kind, and the response returns the explicit set stored for the definition either way.
+            Supply a narrower set to scope inheritance as well as direct assignment: a definition limited to
+            NAMESPACE and COLUMN can be assigned to a namespace and inherited by descendant columns without
+            appearing on the intermediate tables, because an excluded intermediate kind does not stop
+            inheritance to an allowed descendant.
+
+            The set is immutable after creation, whether supplied or defaulted, and target kinds added in a
+            later version do not expand an existing definition. An explicit null, an empty list, duplicates
+            and unknown kinds each return 400 BadRequest.
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        The complete editable definition. An update is a read/modify/write: the request describes the state
+        the definition should end in rather than the fields that changed, so `description` and `values` are
+        both required. Omitting either returns 400, and clients that want to keep a value send it back.
+
+        An explicit JSON null for `description` clears it. `values` must be a valid, non-empty list of
+        distinct, non-empty strings, the same rules createTag applies.
+
+        `name` is not a field of this request: renaming goes through renameTag. `target-types` is
+        create-only and is likewise not a field here, so a request that carries it at all, including as an
+        explicit null or an empty list, returns 400 BadRequest.
+
+        `current-tag-version` is required and the update succeeds only when it matches the definition's
+        current token; a stale token returns 409 TagVersionMismatch. A request that changes nothing still
+        checks the token and returns the current definition and version without advancing it. Changing the
+        values list never rewrites existing assignments.
+      required:
+        - description
+        - values
+        - current-tag-version
+      properties:
+        description:
+          type: string
+          nullable: true
+          description: |
+            The definition's description in the state it should end in. It is required, and either an
+            explicit JSON null or an empty string clears it.
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The complete values list the definition should end with. It is required and must hold at least
+            one member; every member must be a distinct, non-empty string of at most 2000 bytes encoded as
+            UTF-8. A longer value returns 400 BadRequest.
+        current-tag-version:

Review Comment:
   The difference is more high-level I guess. Embedding `current-tag-version` makes it part of the data model, while keeping it away from entity data, makes it an API concern. I personally believe the latter approach is preferable.
   
   The proposed shape of `current-tag-version` is more general that the numeric entity version in the Management API, so I thought it might be worth generalizing to the API level.
   
   That said, I am fine with keeping `current-tag-version` at the entity level.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4124938345


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'

Review Comment:
   Will this create extra language-specific entities (classes), e.g. for `TagUnauthorizedResponse` in auto-generated clients?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253196978


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -5296,6 +7111,306 @@ components:
       required: true
       schema:
         $ref: '#/components/schemas/SemanticModelName'
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.

Review Comment:
   I’ll keep the namespace query parameter as a single string. Iceberg already provides namespaceToQueryParam and namespaceFromQueryParam for this representation, and Polaris advertises %1F as its namespace separator. Keeping that format lets clients reuse Iceberg’s namespace query encoding.
   
   An array query parameter would avoid the separator, but introduce a different wire format for the same namespace. The JSON target in assign/unassign already uses an array, where no query encoding is needed.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4018511025


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   ~In that case, I'm fine with it.~
   
   ~I plan to move the API to /api/tags/v1/{prefix}/ in this PR: tags gets its own spec document and generated module, and its paths leave the catalog-service bundle.~ 
   
   ~Under the new root the resources are /api/tags/v1/{prefix}/definitions/{tag-name} for definitions, …/definitions/{tag-name}/assignments for assignments, and /api/tags/v1/{prefix}/object-tags for the effective read, so a definition name can never collide with a fixed segment. I'll push the respin once the other threads settle and note it here.~
   
   Edit: I've reconsidered moving the base URI in this PR. I still agree that a separate root would give tags independent versioning and routing, but for v1 I'd prefer to keep the existing /api/catalog/polaris/v1/{prefix}/ base alongside policies and generic tables. The benefit of introducing another root pattern now seems limited relative to the extra spec and generator wiring.
   
   I agree that separating tags would not require moving the other APIs in this PR. The broader question is whether independent extension roots are the direction we want, given the existing layout and migration costs. I'll raise that on the dev list and hold off on the base-URI change here pending that discussion.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4040220077


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'

Review Comment:
   ok. I'll keep `prefix` and its existing catalog-scoping semantics, instead of renaming it to `catalog-name`. I'll still define the parameter locally with a clearer description so the Tag spec is self-contained.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4042229196


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and

Review Comment:
   I’d keep allowed-values required for v1, where each assignment selects one value from a non-empty controlled list. Accepting its omission would need a defined meaning: arbitrary string values, a key-only tag, or a definition that cannot be assigned until values are added. Those are different behaviors, and I’d prefer to decide which we support before accepting the request.
   
   Making a required creation field optional later does not inherently require a v2 endpoint, since existing requests remain valid. We would still need to address response compatibility and old-client assumptions when introducing those new tag forms. Removing required now would not resolve that part.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4041966151


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through

Review Comment:
   hmmm ok, on second thought, I’ll make `target-types` optional on creation. Omitting it will select all v1 target kinds, and the response will return the explicit set stored for that definition.
   
   I’d keep the option to supply a narrower set because it also controls inheritance. For example, a tag restricted to namespaces and columns can be assigned to a namespace and inherited by descendant columns without appearing on the intermediate tables. An excluded intermediate kind does not stop inheritance to an allowed descendant.
   
   The set will remain immutable after creation, whether supplied explicitly or defaulted. Adding new target kinds later will not silently expand existing definitions. Explicit null, empty lists, duplicates, and unknown kinds will remain invalid.
   



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on PR #5366:
URL: https://github.com/apache/polaris/pull/5366#issuecomment-6002186647

   @flyrain @jbonofre could you please take a look?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253161174


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.

Review Comment:
   I’ll remove target-types from the initial version, including this sentence. That removes the per-definition restriction this wording was describing, so we don’t need to introduce a versioning rule here.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "jbonofre (via GitHub)" <gi...@apache.org>.
jbonofre commented on PR #5366:
URL: https://github.com/apache/polaris/pull/5366#issuecomment-5790260702

   I'm doing a new pass on this PR. Thanks @flyingImer !


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4097973695


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching

Review Comment:
   I meant the size of the decoded value, rather than its encoding in the HTTP request. DynamoDB uses the same measurement⁠: UTF-8 bytes, since characters have variable encoded sizes. Here the goal is to bound value size for storage and indexing. I’d keep the byte limit and clarify that JSON escaping does not affect it, and that it does not prescribe the server’s internal string representation.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4067158048


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1

Review Comment:
   Same rationale as above.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4427115100


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1835 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog. A definition gives a classification a name and

Review Comment:
   Makes sense to mark it as `beta`. 



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on PR #5366:
URL: https://github.com/apache/polaris/pull/5366#issuecomment-6005523356

   Thanks for working on it, @flyingImer !  Sorry for the delay. Will check it soon.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r3984280060


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   Thanks for the base URI correction, @flyingImer !
   
   My preference is `/api/tags/v1/{prefix}/`.
   
   I do not think we should automatically move policies and generic tables APIs, but I'd be +1 to separating them into distinct REST prefixes eventually.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4018511025


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   In that case, I'm fine with it. 
   
   I plan to move the API to /api/tags/v1/{prefix}/ in this PR: tags gets its own spec document and generated module, and its paths leave the catalog-service bundle. 
   
   Under the new root the resources are /api/tags/v1/{prefix}/definitions/{tag-name} for definitions, …/definitions/{tag-name}/assignments for assignments, and /api/tags/v1/{prefix}/object-tags for the effective read, so a definition name can never collide with a fixed segment. I'll push the respin once the other threads settle and note it here.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4124864049


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   Thanks for you diligence @flyingImer !
   
   Re: simplification, my point was not to simplify implementation, but to simplify user experience (e.g. make it more usable in manual curl-based situations). With your points about implicit effects in the Web App container, I do not think this proposal is worth the trouble, though.



##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   Thanks for your diligence @flyingImer !
   
   Re: simplification, my point was not to simplify implementation, but to simplify user experience (e.g. make it more usable in manual curl-based situations). With your points about implicit effects in the Web App container, I do not think this proposal is worth the trouble, though.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4124864049


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   Thanks for your diligence @flyingImer !
   
   Re: simplification, my point was not to simplify implementation, but to simplify user experience (e.g. make it more usable in manual curl-based situations). With your points about implicit effects in the Web App container, I do not think my proposal is worth the trouble, though.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098225706


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'

Review Comment:
   POST doesn’t preclude application-level idempotency. PUT could also be designed here, but changing the method alone would not let a client recognize a successful rename after losing the response. I’d prefer to retain POST with the source/destination request, consistent with table/view rename, and keep retry recognition explicit through Idempotency-Key.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098954273


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   After the encoding check, I’d prefer to keep the query parameters and explicit target-type.
   
   We successfully created and tagged Iceberg columns named . and .. through Polaris REST. But on the same server’s existing Iceberg routes, those names as whole path segments were normalized before routing, even when percent-encoded. Supporting them in paths would need additional handling.
   
   With the proposed segment-count shape, omitting a column also produces a valid table address. We could guard against that with explicit kind markers or required type, but the current query contract already rejects incomplete addresses across assign, unassign and per-target reads.
   
   Given those tradeoffs, I don’t think the path shape simplifies this API enough to justify the change.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4043963418


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, named by an assignment request. The server never
+        guesses a target kind: a field combination that does not match `type` is rejected.
+
+        The fields per target type are:
+
+        | type | path | column |
+        |------|------|--------|
+        | catalog | absent or empty | absent or empty |
+        | namespace | one or more namespace levels | absent or empty |
+        | table-like | namespace levels followed by the table name | absent or empty |
+        | column | namespace levels followed by the containing table name | one top-level column name |
+
+        Each namespace level must be non-empty and must not contain U+001F, the character the
+        getObjectTags query uses to separate levels. A JSON body sends the original names as separate
+        strings without URI encoding, and U+001F inside a level returns 400 BadRequestException. The
+        rule covers every namespace level, including the levels that locate a table or a column.
+      required:
+        - type
+      properties:
+        type:
+          $ref: '#/components/schemas/TargetType'
+        path:
+          type: array
+          items:
+            type: string
+          description: |
+            A list representing the hierarchical path to the target, ordered from the namespace level down
+            to the entity.
+
+            If the target is catalog, the path should be either empty or not set.
+
+            Each namespace level must be non-empty and must not contain U+001F; a violation returns
+            400 BadRequestException.
+          example: ["NS1", "NS2", "test_table_1"]
+        column:
+          type: array
+          items:
+            type: string
+          description: |
+            For column targets only, the name of one top-level column in the table named by path. More than
+            one column segment is invalid in v1.
+          example: ["email"]
+
+    AssignTagRequest:
+      type: object
+      required:
+        - target
+        - values
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+        values:
+          type: array
+          items:
+            type: string
+          description: |
+            The selected values. The v1 server requires exactly one member, and it must appear in the
+            definition's current allowed-values list. The list shape leaves room for later value forms.
+          example: ["confidential"]
+
+    UnassignTagRequest:
+      type: object
+      required:
+        - target
+      properties:
+        target:
+          $ref: '#/components/schemas/TagAttachmentTarget'
+
+    ObjectTag:
+      type: object
+      description: |
+        One tag of the queried target, as returned by getObjectTags.
+
+        - **tag:** The tag definition name.
+        - **values:** The selected values. v1 returns exactly one item.
+        - **apply-method:** How the classification applies to the target being read. v1 defines two
+          well-known values: `MANUAL` (the ordinary assignment operation created this direct assignment) and
+          `INHERITED` (the winning assignment is stored on a parent target). The field is an open string:
+          implementations may return other documented direct methods, and clients must accept unknown

Review Comment:
   I’d keep the distinction because it affects how callers manage the result. A table’s effective tag may come from its own assignment or from a parent namespace. Unassigning it from the table only removes a local assignment, not an inherited one, and removing a local override may reveal the parent’s value.
   
   assigned-at identifies where the winning assignment is stored. Callers could derive direct/inherited from that, but apply-method makes the distinction explicit without requiring them to compare target addresses. Polaris’s applicable-policy response already exposes an inherited flag.
   
   I’ll also change MANUAL to DIRECT here to clarify that this describes where the assignment is stored, not whether a person or automation created it.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098278260


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:

Review Comment:
   Putting the source name in the path is reasonable. My preference is to keep POST /tags/rename with source, destination and the version precondition together in the body, following the table/view rename APIs. I don’t see a correctness difference from moving those fields between the path, query and body. Would you be comfortable keeping the existing shape for consistency?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253019084


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:

Review Comment:
   I’ll use 204 with no body for both a successful rename and a recognized retry. Returning the version was intended to save a GET before a subsequent update, but I agree that a single response shape is simpler for the initial version. Callers that need the current version can load the definition separately, and rename permissions will stay unchanged.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253159056


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'

Review Comment:
   I’d prefer to keep pagination in PR1 so clients can enumerate collections that exceed the single-response limits. The local definitions followed [Dmitri’s earlier feedback](https://github.com/apache/polaris/pull/5366#discussion_r3980253936) to avoid reusing IRC’s pagination contract. The current proposal uses pagination by default, with an explicit full-result option.
   
   I agree we should avoid unnecessary divergence. Can we keep pagination here and address cross-API consistency as a coordinated follow-up? @dimas-b, would that work for you?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r3984280060


##########
spec/generated/bundled-polaris-catalog-service.yaml:
##########
@@ -1982,30 +2001,656 @@ paths:
           description: Name of the target table/view
           schema:
             type: string
-          example: test_table
-        - $ref: '#/components/parameters/policy-type'
+          example: test_table
+        - $ref: '#/components/parameters/policy-type'
+      responses:
+        '200':
+          $ref: '#/components/responses/GetApplicablePoliciesResponse'
+        '400':
+          $ref: '#/components/responses/BadRequestErrorResponse'
+        '401':
+          $ref: '#/components/responses/UnauthorizedResponse'
+        '403':
+          $ref: '#/components/responses/ForbiddenResponse'
+        '404':
+          description: Not Found - NoSuchTableException, target table does not exist - NoSuchViewException, target view does not exist - NoSuchNamespaceException, target namespace does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTableDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTableError'
+                TargetViewDoesNotExist:
+                  $ref: '#/components/examples/NoSuchViewError'
+                TargetNamespaceDoesNotExist:
+                  $ref: '#/components/examples/NoSuchNamespaceError'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/ServerErrorResponse'
+  /polaris/v1/{prefix}/tags:

Review Comment:
   Thank for the base URI correction, @flyingImer !
   
   My preference is `/api/tags/v1/{prefix}/`.
   
   I do not think we should automatically move policies and generic tables APIs, but I'd be +1 to separating them into distinct REST prefixes eventually.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4040696039


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted

Review Comment:
   OK. I’ll move rename to POST /tags/rename with explicit source and destination names and retain current-tag-version for concurrency control. Updating the other definition fields will be a separate operation.
   
   On idempotency, Polaris already has opt-in support for table create/update through EntityIdempotency. The Tag endpoints aren’t wired to it yet. I’ll reuse that mechanism for rename so a same-key retry can recognize an earlier success without repeating the change. This will follow the configured key lifetime and require the original tag to remain present and authorization to pass. It won’t preserve the original response or recover results after deletion. I’ll cover lookup and authorization after rename, including concurrent retries, in the implementation tests.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4043949172


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, comment, allowed values, target types, and current
+        version token. For more details, refer to the definition of the `Tag` model.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        A definition's name, comment, and allowed-values list can be updated. Omitted
+        mutable fields are unchanged. A present, non-null allowed-values list replaces
+        the complete list; an explicit JSON null for allowed-values is treated as
+        omitted. target-types is create-only; a non-null value is rejected, while an
+        explicit JSON null is treated as omitted.
+
+        Changing allowed-values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response. A stale or non-matching token returns 409
+        TagVersionMismatchException, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token. The token check and any definition change are
+        atomic.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: a non-null target-types was supplied on update (it is create-only), or an
+            allowed-values list is invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the supplied current-tag-version does not match the definition's current
+            token (TagVersionMismatchException), including a request that would change nothing; the
+            conditional update conflicted after validation (CommitConflictException, retryable); or
+            the new name collides with an existing definition (AlreadyExistsException). For a stale
+            token or a conflicting update, reload the definition and retry with the returned token;
+            for a name collision, pick another name.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignments use it. To remove the
+        definition along with all of its assignments, set detach-all to true; callers then see every
+        assignment and the definition removed, or no change.
+
+        After a successful detach-all=true, no later Tag API read or reverse lookup can expose an
+        assignment of the deleted definition. Physical cleanup may finish later, and a cleanup failure
+        must not undo completed deletion or expose retained rows.
+
+        An implementation that cannot provide that result for detach-all=true checks the required
+        permissions first and then returns 501, changing no visible state. Returning 204 after a
+        partial visible deletion is invalid. 501 denotes an unsupported guarantee; a transient
+        execution failure uses the shared server-error responses and is not reported as unsupported.
+
+        The definition is permanently deleted and its name is released.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: Bad Request - assignments of this tag definition remain and detach-all is not set to true
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        501:
+          description: |
+            Not Implemented - this implementation cannot guarantee the detach-all=true result, so no
+            visible change was made
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                DetachAllUnsupported:
+                  $ref: '#/components/examples/DetachAllUnsupportedError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/mappings:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The request body carries a structured target and the selected values. In v1 the values list must
+        contain exactly one value, and that value must appear in the definition's current allowed-values
+        list. The target kind must appear in the definition's target-types list. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        Tags can be assigned to different levels:
+        1. **Column level:** one top-level column of an Iceberg table.
+        2. **Table-like level:** an Iceberg table or a generic table. Iceberg views are not supported in v1;
+           view support can be added later without API changes.
+        3. **Namespace level:** a namespace.
+        4. **Catalog level:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names to
+        durable identifiers before storing an assignment, so a rename that preserves the underlying entity
+        keeps the assignment, while dropping and recreating the same name does not.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed, the target kind
+            is excluded by the definition's target-types, the values list is
+            malformed, more than one value was selected, or the selected
+            value is not currently allowed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the tag definition, the target, or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The request body carries the same structured target used by assignTag. The operation removes an
+        existing assignment; it does not re-check the definition's target-types. The target must be inside
+        the catalog identified by {prefix} and must resolve from the request.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - BadRequestException: the target is unsupported or malformed
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: |
+            Not Found - the tag definition, the target, the named column, or the assignment itself does not
+            exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/objects:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment, with pagination.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+      parameters:
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/BadRequestErrorResponse'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The tag definition does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with query parameters; the required
+        combination depends on the target kind:
+
+        - Catalog:
+          - Neither `namespace`, `target-name`, nor `column` should be set.
+        - Namespace:
+          - The `namespace` parameter is required to specify the identifier.
+        - Table-like:
+          - The `namespace` and `target-name` parameters are required.
+        - Column:
+          - The `namespace`, `target-name`, and `column` parameters are required.
+
+        Every other parameter combination is rejected; the server never guesses a target kind.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The server derives the target kind from the parameter combination; there is no separate
+        target-type parameter. The structured `TagAttachmentTarget` stays canonical, and these query
+        parameters carry a reversible encoding of the same names. A complete request for the column
+        sales.eu.customers.email is
+
+        `?namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        Each of `namespace`, `target-name`, `column`, and `view` appears at most once. A present but
+        empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - name: namespace
+          in: query
+          required: false
+          description: |
+            A namespace identifier as a single string.
+            Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+            The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+            original level names with U+001F, then URI-encode the joined text once. Every level must
+            be non-empty and must not contain U+001F, so a client checks the names before joining
+            them; once joined, a separator inside a name looks exactly like the separator between
+            names.
+
+            Encode a space as `%20` and a literal plus as `%2B`; a raw `+` decodes to a space. A name
+            containing the literal text `%1F` is encoded as `%251F`, and one decode restores the text
+            `%1F` rather than the separator.
+
+            Omit the parameter for a catalog target. A present but empty parameter, an empty level
+            after splitting, and a repeated parameter each return 400 BadRequestException.
+          schema:
+            type: string
+          examples:
+            singlepart_namespace:
+              value: "accounting"
+            multipart_namespace:
+              value: "accounting%1Ftax"
+            namespace_with_space_and_non_ascii:
+              summary: 'The levels ["with space", "café"]'
+              value: "with%20space%1Fcaf%C3%A9"
+            namespace_with_literal_percent_escape:
+              summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+              value: "tax%2520rate%1F%251F"
+        - name: target-name
+          in: query
+          required: false
+          description: |
+            Name of the target table. In v1 this is an Iceberg table or a generic table; Iceberg views are
+            not supported.
+
+            The value is an ordinary string query value; it is not namespace-joined and is not split.
+            A present value must be non-empty, and the parameter appears at most once. A raw `+`
+            decodes to a space, so send a literal plus as `%2B`.
+          schema:
+            type: string
+          example: "test_table"
+        - name: column
+          in: query
+          required: false
+          description: |
+            Name of one top-level column in the table named by target-name. Column targets are supported on
+            Iceberg tables only in v1.
+
+            The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+            dot belongs to one top-level column name and does not address a nested field. A present
+            value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+            `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+          schema:
+            type: string
+          example: "email"
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequestException, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the query parameter combination does not name one of the supported target kinds,
+            it names an unsupported target such as an Iceberg view or a generic-table column, a present
+            `namespace`, `target-name`, or `column` is empty, a namespace level is empty after
+            splitting, `view` is present but empty or unknown, or a target-address parameter is
+            repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler and
+            uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequestException.
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - the target path or the named column does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+components:
+  parameters:
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'
+      example: 'sensitivity'
+
+    TargetType:
+      type: string
+      description: |
+        The kind of target a tag applies to:
+        1. catalog: the catalog identified by {prefix}.
+        2. namespace: a namespace.
+        3. table-like: an individual table. In v1 this is an Iceberg table or a generic table; Iceberg views
+           are not supported and can be added later without API changes.
+        4. column: one top-level column of an Iceberg table. Generic-table columns are not supported because
+           v1 defines no stable column identifier for them.
+      enum:
+        - catalog
+        - namespace
+        - table-like
+        - column
+      example: table-like
+
+    Tag:
+      type: object
+      description: |
+        A tag definition in Apache Polaris gives a classification a name, a set of allowed values, and the
+        target kinds it may classify. Tag assignments select one value from the definition and attach it to
+        a catalog, namespace, table-like, or column target; reads can then return direct or inherited
+        classifications for a target.
+
+        The tag object includes
+        - **name:** The classification name, unique within the catalog.
+        - **comment:** Optional text that explains the classification.
+        - **allowed-values:** The values an assignment may select. Matching is exact and case-sensitive.
+          Changing this list never rewrites existing assignments; an assignment whose stored value was
+          removed from the list remains readable until it is replaced or unassigned.
+        - **target-types:** The target kinds this definition may classify, directly or through inheritance.
+          This list is immutable after creation.
+        - **version:** A non-empty, server-managed opaque string that prevents a stale update from
+          overwriting a newer one. Clients return it unchanged in `current-tag-version` and must not
+          parse, order, or increment it. The API specifies no initial token, numeric sequence, or
+          history. A change to the definition invalidates earlier tokens, even if its fields later
+          return to their previous values, and a token from a deleted definition cannot authorize an
+          update to a same-name replacement. An update that changes nothing leaves the definition
+          fields unchanged and returns the current token. An implementation may use a catalog-wide
+          revision, in which case an unrelated catalog change can invalidate a token even when this
+          definition is unchanged.
+      required:
+        - name
+        - allowed-values
+        - target-types
+        - version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+          description: |
+            The values an assignment may select. The v1 server requires at least one non-empty member.
+        target-types:
+          type: array
+          minItems: 1
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+        version:
+          type: string
+          minLength: 1
+          example: "rev-a"
+
+    TagIdentifier:
+      type: object
+      required:
+        - name
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+
+    CreateTagRequest:
+      type: object
+      required:
+        - name
+        - allowed-values
+        - target-types
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          items:
+            type: string
+        target-types:
+          type: array
+          items:
+            $ref: '#/components/schemas/TargetType'
+
+    UpdateTagRequest:
+      type: object
+      description: |
+        An update request. Omitted mutable fields are unchanged. A present, non-null
+        allowed-values list replaces the complete list; an explicit JSON null for
+        allowed-values is treated as omitted. target-types is create-only; a non-null
+        value is rejected, while an explicit JSON null is treated as omitted.
+        current-tag-version is required and must be a non-empty opaque string returned by a
+        previous read. The update succeeds only when it matches the definition's current token.
+      required:
+        - current-tag-version
+      properties:
+        name:
+          $ref: '#/components/schemas/TagName'
+        comment:
+          type: string
+        allowed-values:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: |
+            A present, non-null list replaces the complete allowed-values list. An explicit JSON null
+            is treated as omitted.
+        target-types:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TargetType'
+          description: |
+            Create-only. A non-null value is rejected with 400 BadRequestException. An explicit JSON
+            null is treated as omitted.
+        current-tag-version:
+          type: string
+          minLength: 1
+          example: "rev-b"
+          description: |
+            The definition's current version token, as returned by a previous create, load, or update.
+            Send it back unchanged; do not parse, order, or increment it.
+
+    LoadTagResponse:
+      type: object
+      required:
+        - tag
+      properties:
+        tag:
+          $ref: '#/components/schemas/Tag'
+
+    ListTagsResponse:
+      type: object
+      required:
+        - identifiers
+      properties:
+        next-page-token:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/PageToken'
+        identifiers:
+          type: array
+          uniqueItems: true
+          items:
+            $ref: '#/components/schemas/TagIdentifier'
+
+    TagAttachmentTarget:
+      type: object
+      description: |
+        One catalog object or top-level Iceberg column, named by an assignment request. The server never
+        guesses a target kind: a field combination that does not match `type` is rejected.
+
+        The fields per target type are:
+
+        | type | path | column |
+        |------|------|--------|
+        | catalog | absent or empty | absent or empty |
+        | namespace | one or more namespace levels | absent or empty |
+        | table-like | namespace levels followed by the table name | absent or empty |
+        | column | namespace levels followed by the containing table name | one top-level column name |

Review Comment:
   Good point! I’ll replace the table with a short list by target type, preserving the field-combination rules. That should make the description easier to read across OpenAPI renderers.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4048655348


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through
+          inheritance. The list is a set; it must be non-empty and free of duplicates. It cannot be changed
+          after creation.
+        - `comment` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - BadRequestException: the allowed-values list is invalid or the
+            target-types list is missing or invalid
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+        401:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/UnauthorizedResponse'
+        403:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ForbiddenResponse'
+        404:
+          description: Not Found - The catalog identified by {prefix} does not exist
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+        409:
+          description: Conflict - A tag definition with the same name already exists in the catalog
+          content:
+            application/json:
+              schema:
+                $ref: '../iceberg-rest-catalog-open-api.yaml#/components/schemas/IcebergErrorResponse'
+              examples:
+                TagAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServiceUnavailableResponse'
+        5XX:
+          $ref: '../iceberg-rest-catalog-open-api.yaml#/components/responses/ServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: Return the tag definition names in the catalog identified by {prefix}, with pagination.
+      parameters:
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
+        - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-size'

Review Comment:
   Thanks Dmitri. I raised this on [[dev@](https://lists.apache.org/thread/jlcrn3l4htm3fwdkqfcqbd0pgxghpcth)](https://lists.apache.org/thread/jlcrn3l4htm3fwdkqfcqbd0pgxghpcth), including your always-on proposal.
   
   The open question is whether opt-in pagination with a documented error for oversized unpaginated requests, never silently truncating results, would be acceptable, or whether Tags should use always-on pagination from the start. I’d appreciate your thoughts there before we settle the contract here.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyrain (via GitHub)" <gi...@apache.org>.
flyrain commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4031478175


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'

Review Comment:
   Allowing this API to evolve independently of IRC is a good idea. However, Polaris already uses IRC’s `prefix` concept across the board, including in the generic table, notification, policy, and semantic model. I’d prefer to keep prefix handling consistent across all APIs scoped to a catalog. If we want to change this pattern, we should discuss it separately and apply the change consistently across all Polaris REST API specs.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098032042


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.

Review Comment:
   Yes, this uses the catalog config endpoint, so there is a discovery dependency. The lifetime tells clients when to stop relying on same-key retries after an uncertain outcome. Since support and retention are configurable, I reused Polaris’s existing discovery contract rather than introduce a second one for Tags. A fixed, documented retry window would be another option, but would change that contract. My preference is to retain the existing discovery path for now.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098044628


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed, the target kind is excluded by the
+            definition's target-types, the values list is an explicit null, is empty, or contains an
+            empty or duplicate member, more than one value was selected, or the selected value is not
+            currently allowed.
+
+            This operation names BadRequest for those cases and that type takes precedence for them.
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            values field that is absent or, when not null, not a JSON array, neither of which is a
+            selected value this operation can judge; an explicit null is invalid and answers 400
+            BadRequest, and a rejected request neither creates nor replaces an assignment.
+            InvalidIdempotencyKey covers a present but malformed
+            Idempotency-Key header: the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToAssignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Remove the assignment of a tag from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing assignment of this tag definition from one target.
+
+        The query parameters name the target, exactly as they do on assignTag, and there is no request
+        body. The operation removes an existing assignment; it does not re-check the definition's
+        target-types. The target must be inside the catalog identified by {prefix} and must resolve
+        from the request.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DETACH on the definition and the target-side detach privilege for the kind
+        (CATALOG_DETACH_TAG, NAMESPACE_DETACH_TAG, TABLE_DETACH_TAG or VIEW_DETACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - the target is unsupported or malformed.
+
+            This operation names BadRequest for that case and that type takes precedence for it.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the shared handler
+            inspects the header on any write it sees, and rejecting a malformed one does not make this
+            operation recognize a retry.
+
+            Possible error types: BadRequest, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (the assignment).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetToUnassignDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        The caller needs TAG_READ on the named definition, and then READ_PROPERTIES on each target the
+        response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a privilege on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with the same query parameters assignTag
+        and unassignTag use: a required `target-type` plus the parameters that kind needs. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires READ_PROPERTIES on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` remains the response shape that reports
+        which target a result belongs to, and these query parameters carry a reversible encoding of the
+        same names. A complete request for the column sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is missing or
+            unknown, or a target-address parameter is repeated.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: BadRequest, and for the pagination parameters
+            ValidationError, or BadRequest for invalid pagination input, a repeated pagination
+            parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it is rejected, and is never treated as addressing the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Idempotency is opt-in per deployment and off by default; where a deployment enables it, the
+        reuse window is the value it advertises as `idempotency-key-lifetime` in the configuration response.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first, and a key never bypasses either: createTag still needs
+        TAG_CREATE on the catalog, updateTag still needs TAG_WRITE on the definition, and renameTag still

Review Comment:
   That's a good point, I’ll remove the concrete privilege names from the API spec and keep the Polaris RBAC mapping in the design doc. The API should still state that a key grants no permission and that recognized retries require the caller’s current authorization for the original operation.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4098452642


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   Thanks for clarifying. The path shape makes sense, and optional type works as an assertion when callers want it. When omitted, authorization and target-type checks would still follow the resolved object.
   
   I’d like to verify the encoding before committing to the shape, particularly column names containing / or literal percent sequences. The current contract uses query encoding, so moving these into path segments needs more than relocating the parameters. I’ll also check the catalog-target route and the corresponding read/delete operations.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4127706547


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_WRITE on the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may record no idempotency key; where none was recorded, a retry of
+        it sent after the definition has changed returns 409 TagVersionMismatch rather than the earlier
+        success. Recording one is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 bytes encoded as UTF-8.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_DROP on the definition, and detach-all=true additionally requires TAG_DETACH on it.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    put:
+      tags:
+        - Tag API
+      summary: Assign a tag value to a target
+      operationId: assignTag
+      description: |
+        Create or replace the assignment of this tag definition on one target.
+
+        The query parameters name the target and the request body carries only the selected values. The
+        values list must contain exactly one value, and that value must appear in the definition's
+        current values list. The target kind must appear in the definition's target-types list.
+        Reassigning the same tag on the same target replaces the stored value.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before storing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_ATTACH on the definition and the target-side attach privilege for the kind
+        (CATALOG_ATTACH_TAG, NAMESPACE_ATTACH_TAG, TABLE_ATTACH_TAG or VIEW_ATTACH_TAG); a column target is
+        checked through the table that contains it.
+      parameters:
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'

Review Comment:
   If we go with query parameters here, TBH, I do not see much benefit compared to using payload JSON data. On the other hand, JSON is much easier to parse and handle encoding (which query parameters are still exposed to).
   
   IIRC, payload was the original design. Apologies about back-and-forth on this. I'll leave it up to you whether to switch to payload or keep query params.
   
   We could model assign and unassign via a flag in the payload under the same `PUT` endpoint (no `DELETE`). I think that would match well with resource state updates and idempotency guarantees.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "dimas-b (via GitHub)" <gi...@apache.org>.
dimas-b commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4124938345


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2171 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes encoded as UTF-8. A longer value returns 400 BadRequest. Matching
+          is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name while its key is still live is recognized again.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_CREATE on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is invalid,
+            meaning it is an explicit null, empty, or holds a duplicate or unknown kind. Omitting
+            target-types is valid and selects every v1 target kind.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_LIST on the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        The version token changes on success.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        Because the response carries no body, a client that loses it cannot tell a completed rename from one
+        that never ran: a retry against the old name returns 404 NoSuchTag. Supplying an Idempotency-Key on
+        the original request makes the retry recognizable instead, answering 204 for the request that already
+        succeeded even if the definition has since been renamed again, on the terms that parameter describes.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        A rename is authorized on both sides: TAG_DROP on the source definition, because the name it holds
+        stops resolving, plus TAG_CREATE on the catalog for the destination name, the same check createTag
+        performs. Editing a definition in place is a different, weaker check, so a caller who may edit a
+        definition but may not drop it, or may not create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        204:
+          description: Success - the definition was renamed. No content is returned.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. ValidationError covers a body that is not valid JSON against this schema, including a
+            missing source or destination and a missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Authorization uses the proposed privilege names below; the names are illustrative while the shape
+        of the checks is the contract.
+
+        Requires TAG_READ on the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'

Review Comment:
   Will this create extra language-specific entities (classes), e.g. for `TagUnauthorizedResponse`?



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253053160


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Assign a tag to a target
+      operationId: assignTag
+      description: |
+        Set the direct assignment of this tag definition on one target. Reassigning the same tag on
+        the same target replaces the stored value.
+
+        The JSON body carries a `target` and `values` containing exactly one value from the
+        definition's current values list. The target kind must appear in the definition's target-types.
+        Target names are original strings in JSON, without URI encoding. Per-target reads continue to
+        use the query parameters on getObjectTags.
+
+        An absent, null or empty values list is invalid and never removes an assignment. A rejected
+        request changes no assignment. This operation does not recognize completed requests through
+        Idempotency-Key.
+
+        A tag can be assigned at any of the target kinds:
+        1. **COLUMN:** one top-level column of an Iceberg table. Column targets are limited to Iceberg
+           tables, because generic tables and views define no stable column identifier in v1.
+        2. **TABLE:** a whole table, meaning an Iceberg table or a generic table this implementation
+           supports.
+        3. **VIEW:** a whole Iceberg view.
+        4. **NAMESPACE:** a namespace.
+        5. **CATALOG:** the catalog identified by {prefix}.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to attach on the definition and the corresponding permission to attach a
+        tag on the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/AssignTagRequest'
+            examples:
+              AssignColumn:
+                summary: Assign a value to the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+                  values: ["confidential"]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, a kind excluded by the definition's target-types, explicit null or empty
+            values, empty or duplicate members, more than one selected value, a value exceeding
+            2000 decoded UTF-8 bytes, or a value not currently allowed.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, a missing values field, a non-null values field that is not a JSON array,
+            and other schema-type violations. The operation-specific BadRequest cases above take
+            precedence over shared schema validation, including an unknown target kind or null values.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                TargetTypeNotAllowed:
+                  $ref: '#/components/examples/TargetTypeNotAllowedError'
+                InvalidValues:
+                  $ref: '#/components/examples/ValuesInvalidError'
+                MultipleValuesNotSupported:
+                  $ref: '#/components/examples/MultipleValuesNotSupportedError'
+                ValueNotAllowed:
+                  $ref: '#/components/examples/ValueInvalidError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/unassign:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    post:
+      tags:
+        - Tag API
+      summary: Remove a direct tag assignment from a target
+      operationId: unassignTag
+      description: |
+        Remove the existing direct assignment of this tag definition on one target. The JSON body
+        carries only a `target`; `values` must not be supplied. Removing a direct assignment may
+        reveal an inherited value. This operation does not re-check the definition's target-types or
+        values.
+
+        If no direct assignment exists, the request returns 404 NoSuchAssignment. This operation does
+        not recognize completed requests through Idempotency-Key. Retrying after a successful removal
+        therefore returns 404 NoSuchAssignment if the assignment is still absent. A rejected request
+        changes no assignment.
+
+        Target kinds and address fields follow TagAttachmentTarget. Column targets are limited to
+        top-level columns of Iceberg tables, because generic tables and views define no stable column
+        identifier in v1. Target names are original strings in JSON, without URI encoding. Per-target
+        reads continue to use the query parameters on getObjectTags.
+
+        The target must be inside the catalog identified by {prefix}. Polaris resolves request names
+        to durable identifiers before changing an assignment: a tag definition has a stable id, a target has
+        a stable entity id, and a column is identified by its containing table's id together with its
+        Iceberg field id. A rename that preserves the underlying entity keeps the assignment, while
+        dropping and recreating the same name produces a different identity and inherits nothing.
+
+        The write depends on those facts and no others: that the target exists, which identity the name
+        resolves to, and the parent and schema facts the kind requires. A change to an unrelated property
+        of the target is not a conflict.
+
+        Requires permission to detach on the definition and the corresponding permission to detach a
+        tag from the target. A column target is checked through the table that contains it.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UnassignTagRequest'
+            examples:
+              UnassignColumn:
+                summary: Remove the direct assignment from the literal top-level column named '.'
+                value:
+                  target:
+                    type: COLUMN
+                    path: ["sales", "eu", "customers"]
+                    column: ["."]
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            BadRequest covers an unsupported target kind, a malformed or incomplete address for the
+            stated kind, or a supplied `values` field, including null or an empty array.
+
+            ValidationError covers a missing, null or non-object `target`, a missing or null
+            `target.type`, and other schema-type violations. The operation-specific BadRequest cases
+            above take precedence over shared schema validation, including an unknown target kind or
+            a supplied values field.
+            InvalidJson covers a body that is not syntactically valid JSON.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header:
+            the shared handler inspects the header on any write it sees, and
+            rejecting a malformed one does not make this operation recognize a retry.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition), NoSuchTarget (the target or the named
+            column), NoSuchAssignment (when no direct assignment exists).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+                TargetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+                AssignmentToRemoveDoesNotExist:
+                  $ref: '#/components/examples/NoSuchAssignmentError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assignments:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: List targets that carry a direct assignment of a tag
+      operationId: listObjectsByTag
+      description: |
+        A reverse lookup that starts from one tag definition and returns targets with their own direct
+        assignment. The listing is paginated by default: a request with no pagination parameters returns
+        the first page, and `pagination=false` on its own asks for the complete result in one response,
+        subject to the full-result limits.
+
+        Without `value`, every direct assignment of the tag is returned. With `value`, only direct
+        assignments containing that exact, case-sensitive string are returned. Targets that only inherit the
+        tag are not returned, so `apply-method` in this response is never `INHERITED`.
+
+        The caller needs permission to read the named definition, and then read permission on each target
+        the response would report; a column is checked through the table that contains it. There is no
+        catalog-wide shortcut: holding a permission on the catalog does not stand in for the per-target
+        check, and a target the caller may not read is left out rather than reported. A
+        failure of the authorization system itself is not a denial: the request fails rather than silently
+        returning fewer targets.
+
+        A result is also left out when its target has been dropped, has been soft-dropped, or cannot be
+        found, and when the named field no longer exists. Being unable to determine whether a target
+        exists is not the same as confirming it is gone: a metadata read that fails is an error, not an
+        absence. Because results are filtered after candidates are fetched, and because a paged request may
+        reach its work budget partway through, a page may come back short or empty and still carry a
+        next-page-token.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - name: value
+          in: query
+          required: false
+          description: |
+            Return only direct assignments whose selected values contain this exact, case-sensitive string.
+          schema:
+            type: string
+          example: "confidential"
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListObjectsByTagResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToListDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/object-tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    get:
+      tags:
+        - Tag API
+      summary: Get the tags of a catalog, namespace, table, view, or column
+      operationId: getObjectTags
+      description: |
+        Retrieves the tags of one target. The target is named with a required `target-type` query
+        parameter plus the parameters that kind needs. Assignment writes use a JSON target. The per-kind
+        combination table lives on the `target-type` parameter, and a combination that does not match
+        `target-type` is rejected.
+
+        The optional `view` parameter selects the read:
+
+        - `direct` (the default when `view` is omitted) returns only assignments stored on the queried
+          target.
+        - `effective` reads the target and its parents, then returns the final result for each tag
+          definition. Among the assignments a definition allows, the closest one wins: column, then table,
+          then the nearest namespace, then the catalog. Values from different levels are never combined.
+
+        Both views are paginated by default: a request with no pagination parameters returns the first
+        page, and `pagination=false` on its own returns all tags of the queried target in one response,
+        subject to the full-result limits. The `pagination`, `pageToken` and `pageSize` parameters follow
+        the same rules here as they do on the two listings.
+
+        A tag definition appears in the result only when the queried target kind is listed in its
+        target-types, and that test applies to the target being read rather than to the target the
+        assignment sits on. A definition listing NAMESPACE and COLUMN but not TABLE therefore reaches a
+        column through its namespace while never appearing on the table in between.
+
+        The hierarchy, definitions, and assignments behind one response are consistent with a single
+        logical point in time. Separate pages of a paged response make no such promise between them.
+
+        The effective computation always considers the complete hierarchy: paging bounds the tags a
+        response returns and never truncates the hierarchy or falls back to a direct read, and a read
+        that cannot consider the whole hierarchy is an error. One page is one coherent response. Results
+        leave out soft-dropped targets, and assignments whose definition, target entity, or named field
+        is permanently absent.
+
+        Requires read permission on the queried target; a column is checked through the table that
+        contains it. Authorizing the queried target is enough to read all of its effective tags: there is
+        no per-parent and no per-definition authorization, so an effective read never depends on the
+        caller's access to the ancestors an assignment came from. An effective read returns the complete result or fails; it never returns a partial
+        hierarchy or falls back to a direct read.
+
+        The kind is always stated, never inferred: a request without `target-type` is rejected and is
+        never treated as a catalog read. `TagAttachmentTarget` is the structured target used by writes
+        and returned by reads. These query parameters address the same targets: `namespace` contains
+        the namespace levels of `path`, `target-name` is its final table or view name when applicable,
+        and `column` is the single column name. A complete request for sales.eu.customers.email is
+
+        `?target-type=COLUMN&namespace=sales%1Feu&target-name=customers&column=email&view=effective`
+
+        and the catalog itself is `?target-type=CATALOG`, with none of the other three set.
+
+        Each of `target-type`, `namespace`, `target-name`, `column`, and `view` appears at most once. A
+        present but empty parameter and an empty namespace level are both invalid.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/target-type'
+        - $ref: '#/components/parameters/target-namespace'
+        - $ref: '#/components/parameters/target-name'
+        - $ref: '#/components/parameters/target-column'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+        - name: view
+          in: query
+          required: false
+          description: |
+            Which read to perform. Omitting this parameter is the same as `direct`. A present but
+            empty or unknown value returns 400 BadRequest, and the parameter appears at
+            most once.
+          schema:
+            type: string
+            default: direct
+            enum:
+              - direct
+              - effective
+          example: "effective"
+      responses:
+        200:
+          $ref: '#/components/responses/GetObjectTagsResponse'
+        400:
+          description: |
+            Bad Request - the parameters do not match the `target-type` given, they name a target this
+            implementation does not support, such as a column of a view or of a generic table, a
+            present `target-name`, `namespace`, or `column` is empty, a namespace level is empty
+            after splitting, `view` is present but empty or unknown, `target-type` is present but empty
+            or unknown, or a target-address parameter is repeated. These cases use BadRequest.
+
+            A missing required `target-type` uses ValidationError.
+
+            A malformed percent escape or another malformed URI is rejected before the Tag handler
+            and uses the HTTP layer's shared 400 response; validation in the Tag handler uses
+            BadRequest.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (the target-address cases above,
+            invalid pagination input, a repeated pagination parameter, `pagination=false` combined with
+            `pageToken` or `pageSize`, an invalid or expired
+            token, a request that would exceed the response-size or work limits, or a paged request that
+            cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                UnsupportedTarget:
+                  $ref: '#/components/examples/UnsupportedTargetError'
+                InvalidTargetQuery:
+                  $ref: '#/components/examples/InvalidTargetQueryError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTarget (the target path or the named column).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetToReadDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTargetError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+components:
+  parameters:
+    target-type:
+      name: target-type
+      in: query
+      required: true
+      description: |
+        The kind of target the request addresses. It is stated explicitly rather than inferred, and the
+        other target parameters must match it:
+
+        | target-type | namespace | target-name | column |
+        |-------------|-----------|-------------|--------|
+        | `CATALOG` | absent | absent | absent |
+        | `NAMESPACE` | required | absent | absent |
+        | `TABLE` | required | required | absent |
+        | `VIEW` | required | required | absent |
+        | `COLUMN` | required | required | required |
+
+        A combination that does not match target-type returns 400 BadRequest. `target-type` is always
+        required: a request that omits it returns 400 ValidationError, and is never treated as addressing
+        the catalog.
+      schema:
+        $ref: '#/components/schemas/TargetType'
+
+    target-namespace:
+      name: namespace
+      in: query
+      required: false
+      description: |
+        A namespace identifier as a single string.
+        Multipart namespace parts should be separated by the unit separator (`0x1F`) byte.
+
+        The parameter uses Iceberg namespace query encoding, not Iceberg path encoding: join the
+        original level names with U+001F, then URI-encode the joined text once. Every level must
+        be non-empty and must not contain U+001F, so a client checks the names before joining
+        them; once joined, a separator inside a name looks exactly like the separator between
+        names.
+
+        Two rules follow from that and are worth separating. The client pre-join constraint is that
+        every level is non-empty and free of U+001F, and the client is the only party that can enforce
+        it: after the join the server cannot tell whether a U+001F came from inside a name or from
+        between names. The server-observable check is what remains after decoding, namely that no
+        level is empty. And a malformed URI may be rejected by the HTTP
+        layer before the Tag handler runs, so a client should not count on a Tag error payload for
+        every malformed input.
+
+        The server decodes the value once, then splits on U+001F. It does not decode the result
+        again, so percent sequences that survive the first decode are literal text. A raw `+`
+        decodes to a space, here and in `target-name` and `column` alike, so send a literal plus
+        as `%2B`; `%252B` decodes to the literal text `%2B` and is not decoded a second time.
+
+        Conformance examples. Each row gives the contents of one query value, without its
+        parameter name. `US` in the middle column stands for one actual U+001F character, not for
+        the two letters.
+
+        | input | before URI encoding | query value |
+        |---|---|---|
+        | namespace `["sales", "eu"]` | `sales` + US + `eu` | `sales%1Feu` |
+        | namespace `["sales.eu"]` | `sales.eu` | `sales.eu` |
+        | namespace `["R&D", "tax=2026"]` | `R&D` + US + `tax=2026` | `R%26D%1Ftax%3D2026` |
+        | namespace `["tax%20rate", "%1F"]` | `tax%20rate` + US + `%1F` | `tax%2520rate%1F%251F` |
+        | namespace `["with space", "café"]` | `with space` + US + `café` | `with%20space%1Fcaf%C3%A9` |
+        | namespace `["销售", "日本語"]` | `销售` + US + `日本語` | `%E9%94%80%E5%94%AE%1F%E6%97%A5%E6%9C%AC%E8%AA%9E` |
+        | `target-name` `orders%20&total` | `orders%20&total` | `orders%2520%26total` |
+        | `column` `cost+tax` | `cost+tax` | `cost%2Btax` |
+        | `column` `a &?=+%` | `a &?=+%` | `a%20%26%3F%3D%2B%25` |
+        | `column` `customer.name` | `customer.name` | `customer.name` |
+        | `target-name` `Q1 orders` | `Q1 orders` | `Q1%20orders` |
+
+        The examples test encoding only. They do not widen the identifiers a catalog or a schema
+        accepts. The round trip is defined for any string, but Polaris's own name validation rejects
+        `/ \ : * ? " < > | # +` and a backtick, control characters, and leading or trailing whitespace in
+        namespace levels and in table and view names, before any tag request can reference such an entity, so
+        those characters occur only in column names. Namespace levels must satisfy those existing naming
+        rules; percent-encoding does not make a forbidden character valid. The literal `%1F` example above
+        still applies, because that level is a percent sign followed by two ordinary characters rather than
+        the U+001F separator.
+
+        `target-name` and `column` are ordinary query values, not namespace lists: they are never
+        joined and never split, and U+001F carries no meaning in them.
+
+        `namespace=sales%251Feu` names one level whose text is `sales%1Feu`; it does not name
+        `["sales", "eu"]`. Double encoding cannot always be detected, because a literal percent
+        sequence may itself be a valid name.
+
+        Omit the parameter for a catalog target. A present but empty parameter, an empty level
+        after splitting, and a repeated parameter each return 400 BadRequest. These query
+        fragments are invalid even when the rest of the address is well formed, and each returns
+        400:
+
+        | query fragment | reason |
+        |---|---|
+        | `namespace=` | empty parameter |
+        | `namespace=%1Fsales` | empty first level |
+        | `namespace=sales%1F` | empty last level |
+        | `namespace=sales%1F%1Feu` | empty middle level |
+        | `namespace=%` | incomplete percent escape |
+        | `namespace=%GG` | non-hexadecimal percent escape |
+        | `namespace=sales&target-name=` | empty table name |
+        | `namespace=sales&target-name=orders&column=` | empty column name |
+        | `namespace=sales&namespace=eu` | duplicate target-address parameter |
+      schema:
+        type: string
+      examples:
+        singlepart_namespace:
+          value: "accounting"
+        multipart_namespace:
+          value: "accounting%1Ftax"
+        namespace_with_space_and_non_ascii:
+          summary: 'The levels ["with space", "café"]'
+          value: "with%20space%1Fcaf%C3%A9"
+        namespace_with_literal_percent_escape:
+          summary: 'The levels ["tax%20rate", "%1F"], where both are literal text'
+          value: "tax%2520rate%1F%251F"
+
+    target-name:
+      name: target-name
+      in: query
+      required: false
+      description: |
+        Name of the target table or view. Which one it names follows from `target-type`: a `TABLE`
+        target is an Iceberg table or a generic table this implementation supports, and a `VIEW`
+        target is an Iceberg view. For a `COLUMN` target this names the table that contains the
+        column.
+
+        The value is an ordinary string query value; it is not namespace-joined and is not split.
+        A present value must be non-empty, and the parameter appears at most once. A raw `+`
+        decodes to a space, so send a literal plus as `%2B`.
+      schema:
+        type: string
+      example: "test_table"
+
+    target-column:
+      name: column
+      in: query
+      required: false
+      description: |
+        Name of one top-level column in the table named by target-name. Column targets are supported on
+        Iceberg tables only.
+
+        The value is an ordinary string query value; it is not split and is not parsed as JSON. A
+        dot belongs to one top-level column name and does not address a nested field. A present
+        value must be non-empty, and the parameter appears at most once. `a+b` decodes to `a b`,
+        `a%2Bb` decodes to `a+b`, and `%252B` decodes to the literal text `%2B`.
+      schema:
+        type: string
+      example: "email"
+
+    tag-pagination:
+      name: pagination
+      in: query
+      required: false
+      description: |
+        Selects how the result is delivered. Omitting this parameter, or sending `pagination=true`, asks
+        for one page at a time; `pagination=false` asks for the complete result in one response, subject
+        to the limits `pageSize` describes. The choice changes delivery only: the filters, the
+        authorization checks and the read guarantees are the same in both modes.
+
+        A client should normally take the result one page at a time, because it cannot know in advance
+        how large the collection is. Ask for the whole result only when the client can receive and
+        process all of it; a server-side limit is not a promise that the response fits in the client's
+        memory.
+
+        `pagination=false` is the only way to ask for a full result: no `pageSize` value and no empty
+        `pageToken` selects one. It must also arrive alone, so sending it together with `pageToken` or
+        `pageSize` returns 400 BadRequest, even when the other parameter is empty.
+
+        Only the two literals `true` and `false` are accepted. An empty value or any other value returns
+        400 BadRequest, and that check reads the query value as the request sent it rather than relying
+        on a converted parameter type. Each of `pagination`, `pageToken` and `pageSize` appears at most
+        once; a repeated one returns 400 BadRequest even when both copies agree. A shared pagination
+        flag or helper does not change these input or mode rules.
+      schema:
+        type: boolean
+        default: true
+      example: false
+
+    tag-page-token:
+      name: pageToken
+      in: query
+      required: false
+      description: |
+        Continues a paginated listing. Paged mode is the default, and within it:
+
+        | request | server behaviour |
+        |---|---|
+        | `pageToken` omitted | the first page, sized by the server's current default |
+        | `pageToken=` (present and empty) | the first page |
+        | `pageToken=<token>` | continue from that token |
+
+        A client continuing with a token does not need to send `pagination=true` alongside it, because
+        paged mode is already what an omitted `pagination` means.
+
+        Send a token back exactly as received; do not parse or construct one. A token is bound to the
+        catalog, the definition or target being listed, the view, and any filters of the request that
+        produced it, and every request is authorized again: a token grants no access of its own.
+
+        An invalid or expired token returns 400 BadRequest, and so does a repeated `pageToken`, even
+        when both copies carry the same value. A full-result request rejects this parameter:
+        `pagination=false` together with `pageToken`, including an empty one, returns 400 BadRequest.
+      schema:
+        type: string
+
+    tag-page-size:
+      name: pageSize
+      in: query
+      required: false
+      description: |
+        An upper bound on one page. The value must be a positive integer: zero, a negative number, an
+        empty value and a non-integer each return 400 BadRequest, whether or not the request carries a
+        `pageToken`. A request that omits it uses the server's finite default page size, and that
+        applies to a continuation as well, which never inherits the size of the request that produced
+        its token. A request above the server's maximum is capped at that maximum; the server may return
+        fewer results than the bound either way, so a client cannot rely on a page holding exactly this
+        many results.
+
+        A full-result request rejects this parameter: `pagination=false` together with `pageSize`,
+        including an empty one, returns 400 BadRequest. A repeated `pageSize` returns 400 BadRequest
+        even when both copies carry the same value.
+
+        Both modes are protected by finite limits on response size and on the work a request may do, and
+        those limits exist by default. A deployment adjusts them, expressed for example as a result count,
+        encoded bytes, candidates examined, or execution time, and the absence of an override never means
+        an unlimited request. A full-result request that would exceed one returns 400 BadRequest with a
+        message directing the client to retry in paged mode by removing `pagination=false` or setting it
+        to `true`, keeping the same target and filters. The server detects this before committing a
+        success: it must not silently truncate, switch to paged mode, or return a successful partial
+        body.
+
+        A paged request that reaches its work budget may return a short or empty page with a continuation
+        token, and a request that cannot make safe progress within that budget returns 400 BadRequest. A
+        continuation resumes after the last consumed candidate, so a candidate that was fetched but
+        neither returned nor rejected stays reachable. A failing metadata, storage or authorization
+        dependency returns the service error for that failure, never an empty page and never a budget 400.
+      schema:
+        type: integer
+
+    tag-idempotency-key:
+      name: Idempotency-Key
+      in: header
+      required: false
+      description: |
+        An optional client-supplied key that makes a completed write recognizable when its response is
+        lost. Whether a deployment recognizes keys is discoverable: where it does, the reuse window is the
+        value it advertises as `idempotency-key-lifetime` in the catalog configuration response; where it
+        does not, requests take the ordinary path. The lifetime bounds how long a client may rely on
+        recognition; its end says nothing about whether the original write succeeded.
+
+        Three operations recognize a retry: createTag, updateTag and renameTag. Request validation and the
+        operation's own authorization run first. A key grants no permission: createTag still needs
+        permission to create definitions in the catalog, updateTag permission to modify the definition, and
+        renameTag permission to delete the source definition together with permission to create in the
+        catalog.
+
+        A retry is recognized as an earlier success when the mechanism is enabled and the key is still
+        recognized for the definition the original request created, updated or renamed. A recognized retry
+        requires the caller's current authorization for the original operation. A recognized createTag or
+        updateTag retry answers 200 with the definition's current state: not the original response, and not
+        the state the original request wrote if the definition has changed since. A recognized renameTag
+        retry answers 204 without renaming again, even after later renames, and the server never renames a
+        definition back to satisfy a retry. Recognition happens before the supplied `current-tag-version`
+        is compared with the definition's current version.
+
+        A client uses one key per logical operation and repeats the key and the request unchanged on retry.
+        Reusing one key with different arguments is a client error: the outcome is undefined and no conflict
+        response is promised. The server does not replay the original response body.
+
+        Recognition ends when the definition is deleted, and a definition later created under the same name
+        inherits none of it. A request the server does not recognize follows the ordinary path, with the
+        usual name lookup, authorization and version check and the errors those produce.
+
+        The number of keys recognized for one definition at a time is bounded. When that bound is reached, a
+        write that would add another key is rejected with 503 ServiceUnavailable and a Retry-After header
+        rather than ending recognition of an existing key, and the write is not applied.
+
+        dropTag, assignTag and unassignTag accept the header through the shared request layer, and none
+        of them recognizes a retry.
+
+        A missing or blank header supplies no key, and the request follows the ordinary path. When the
+        shared idempotency handler is enabled, a non-blank value that is not a UUID is rejected with 400
+        InvalidIdempotencyKey before the Tag handler runs. When support is disabled the header is not
+        rejected: the operation runs its ordinary path and no success recognition is promised. A UUID is
+        accepted, with no Tag-specific requirement on its version.
+      schema:
+        type: string
+
+    catalog-prefix:
+      name: prefix
+      in: path
+      required: true
+      description: |
+        Identifies the catalog the request addresses. Every tag definition and every assignment belongs to
+        exactly one catalog, and this parameter scopes the whole request to it. Polaris maps the prefix to a
+        catalog name, and the default mapping is the identity: the prefix is the catalog name.
+
+        This is the same prefix the other catalog-scoped Polaris APIs take, and it is defined here rather
+        than referenced so this document stands on its own.
+      schema:
+        type: string
+
+    tag-name:
+      name: tag-name
+      in: path
+      required: true
+      description: |
+        The tag definition the request addresses. A tag name consists only of letters, digits,
+        hyphens, and underscores, as the TagName pattern requires, so it never contains a slash and
+        needs no path encoding. That restriction belongs to tag names alone: namespace levels, table and
+        view names, and column names are not limited to those characters.
+      schema:
+        $ref: '#/components/schemas/TagName'
+
+  schemas:
+
+    NextPageToken:
+      description: |
+        An opaque token that continues this listing. A **non-empty** value means there is more to
+        read, including after a page that came back short or empty because of filtering. The field
+        absent or null means the listing is complete; the server never returns an empty string.
+        A full-result response, the one `pagination=false` asks for, never carries one. Send the value
+        back unchanged as `pageToken`; do not parse or construct one.
+      type: string
+      nullable: true
+
+    PolarisErrorResponse:
+      description: |
+        JSON wrapper for all error responses (non-2xx) of the Polaris-specific APIs. The shape is the
+        same as the Iceberg REST catalog's error response, and this definition is intended to be
+        shared by the Polaris-specific APIs so they can evolve independently of that spec.
+      type: object
+      required:
+        - error
+      properties:
+        error:
+          $ref: '#/components/schemas/PolarisErrorModel'
+      additionalProperties: false
+      example: {
+        "error": {
+          "message": "The given tag definition does not exist",
+          "type": "NoSuchTag",
+          "code": 404
+        }
+      }
+
+    PolarisErrorModel:
+      type: object
+      description: JSON error payload returned in a response with further details on the error
+      required:
+        - message
+        - type
+        - code
+      properties:
+        message:
+          type: string
+          description: Human-readable error message
+        type:
+          type: string
+          description: The error type, which names the specific cause behind the HTTP status code
+          example: NoSuchTag
+        code:
+          type: integer
+          description: The HTTP status code of the response, repeated in the body
+          example: 404
+        stack:
+          type: array
+          items:
+            type: string
+
+    TagName:
+      type: string
+      description:
+        A tag definition name. It is unique within the catalog. A valid tag name should only consist of
+        uppercase and lowercase letters (A-Z, a-z), digits (0-9), hyphens (-), underscores (_).
+      pattern: '^[A-Za-z0-9\-_]+$'

Review Comment:
   Tag name 256 limit I’m thinking. The other two, I will need to think and will reflect them in the commits



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4253070514


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,2256 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of permitted values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current values
+        list and attach it to a catalog, namespace, table, view, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `values` (REQUIRED): The definition's values, meaning the choices a new assignment is
+          permitted to select. The list must be non-empty, and every member must be a unique, non-empty
+          string of at most 2000 bytes. The limit is measured on the decoded value in UTF-8 bytes: JSON
+          escaping does not count toward it, and it does not prescribe how the server represents the
+          string internally. A longer value returns 400 BadRequest. Matching is exact and case-sensitive.
+        - `target-types` (OPTIONAL): The target kinds this definition may classify, directly or through
+          inheritance. Omitting the field selects every v1 target kind, and the response returns the
+          explicit set stored for the definition either way. A supplied list is a set: an explicit null, an
+          empty list, duplicates and unknown kinds each return 400 BadRequest. It cannot be changed after
+          creation, whether supplied or defaulted, and target kinds added in a later version do not expand
+          an existing definition.
+        - `description` (OPTIONAL): Text that explains the classification.
+
+        The response carries the new definition's version token. Clients send it back unchanged in
+        `current-tag-version` when updating the definition.
+
+        Where idempotency is enabled, a retry is recognized by the name the request asks for, on the terms
+        the Idempotency-Key parameter describes. If the definition the original request created has since
+        been renamed, the retry cannot locate it and follows the normal rules: a free name creates a new
+        definition, a name held by another definition returns 409 AlreadyExists, and a definition renamed
+        back to the requested name within the key's recognition window is recognized again.
+
+        Requires permission to create definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/CreateTagResponse'
+        400:
+          description: |
+            Bad Request - the values list is invalid, or a supplied target-types list is null, empty,
+            or contains duplicate or unknown kinds.
+
+            InvalidJson covers a body that is not syntactically valid JSON, and ValidationError covers a
+            missing name or a field sent with the wrong schema type. Where this operation names its own
+            type for a case, as it does for the values and target-types rules above, that type takes
+            precedence. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header,
+            rejected by the shared handler before this operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidTargetTypes:
+                  $ref: '#/components/examples/TargetTypesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the catalog's current state; the error type
+            names the cause.
+
+            Possible error types: AlreadyExists (a tag definition with the requested name
+            already exists in the catalog).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                AlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    get:
+      tags:
+        - Tag API
+      summary: List tag definition names in the catalog
+      operationId: listTags
+      description: |
+        Return the tag definition names in the catalog identified by {prefix}.
+
+        The listing is paginated by default: a request with no pagination parameters returns the first
+        page, and an empty `pageToken` asks for the first page too. Send `pagination=false` on its own to
+        ask for the complete collection in one response, subject to the full-result limits the pagination
+        parameters describe.
+
+        Requires permission to read definitions in the catalog.
+      parameters:
+        - $ref: '#/components/parameters/tag-pagination'
+        - $ref: '#/components/parameters/tag-page-token'
+        - $ref: '#/components/parameters/tag-page-size'
+      responses:
+        200:
+          $ref: '#/components/responses/ListTagsResponse'
+        400:
+          description: |
+            Bad Request - the request is malformed, fails shared validation, or asks for more work or a
+            larger response than the server's limits allow.
+
+            This operation takes no request body, so no JSON parse failure can arise on it. Where it names
+            its own type for a case, as it does for the pagination rules, that type takes precedence.
+
+            Possible error types: ValidationError, BadRequest (invalid pagination input, a repeated
+            pagination parameter, `pagination=false` combined with `pageToken` or `pageSize`, an invalid
+            or expired token, a request that would exceed the response-size or work limits, or a paged
+            request that cannot make safe progress within its work budget).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/rename:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+    post:
+      tags:
+        - Tag API
+      summary: Rename a tag definition
+      operationId: renameTag
+      description: |
+        Renames one tag definition within the catalog. The request names the source and the destination
+        explicitly, so this operation changes the name and nothing else; the other definition fields are
+        changed through updateTag.
+
+        A rename preserves the definition's identity: its id, its assignments and its values list all carry
+        over unchanged, and clients that recorded the id can recognize the definition under its new name.
+        A request that performs the rename returns 200 with the version token produced by that write.
+        It does not return the full definition or require permission to read it. The returned token can
+        be used for a subsequent update or rename, subject to the usual concurrent-change checks.
+
+        current-tag-version is required and must be the source definition's current token. A missing, null,
+        empty, or non-string value returns the shared request-validation 400 response, and a token that no
+        longer matches returns 409 TagVersionMismatch.
+
+        The token binds the definition's identity as well as its revision. A token taken from a definition
+        that was since deleted and recreated under the same name, or from a definition whose name another
+        definition was renamed into, does not match and returns 409 TagVersionMismatch, exactly as a stale
+        revision does; the check is applied atomically with the rename.
+
+        After a successful rename, an ordinary request that still uses the old name may return 404 NoSuchTag,
+        while a recognized retry returns 204 without a body or another rename, on the terms the
+        Idempotency-Key parameter describes. This includes a concurrent duplicate that recognizes the
+        other request's successful write. Recognition returns neither the original write's token nor
+        the definition's current token. A client needing the current state after a 204 must load it.
+
+        A rename is authorized on both sides: it requires permission to delete the source definition,
+        because the name it holds stops resolving, and permission to create a definition in the catalog for
+        the destination name, the same check createTag performs. Editing a definition in place is a
+        different, weaker check, so a caller who may edit a definition but may not delete it, or may not
+        create one, cannot rename it.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RenameTagRequest'
+      responses:
+        200:
+          description: The version produced by this request's committed rename
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RenameTagResponse'
+        204:
+          description: |
+            The request was recognized as an earlier successful rename. No content is returned, and
+            the definition is not renamed again, even if it has since changed or been renamed again.
+        400:
+          description: |
+            Bad Request - the request cannot be applied as written; the error type names the cause.
+
+            BadRequest covers a destination that fails TagName validation and a destination equal to the
+            source. InvalidJson covers a body that is not syntactically valid JSON. ValidationError
+            covers a body that fails schema validation, including a missing source or destination and a
+            missing, null, empty or non-string current-tag-version.
+            InvalidIdempotencyKey covers a present but malformed Idempotency-Key header, rejected by the
+            shared handler before this operation runs. Where this operation names its own type for a case,
+            as it does for the destination rules above, that type takes precedence.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                InvalidDestination:
+                  $ref: '#/components/examples/RenameDestinationInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a source definition missing
+            inside a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the source definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                SourceToRenameDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the current state; the error type names the cause.
+            For a stale token, reload the definition and retry with the current one.
+
+            Possible error types: AlreadyExists (the destination already names a definition in this
+            catalog), TagVersionMismatch (the supplied token is not the source definition's current one),
+            CommitConflict (a concurrent change; the request may be retried).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                DestinationAlreadyExists:
+                  $ref: '#/components/examples/TagAlreadyExistsError'
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}:
+    parameters:
+      - $ref: '#/components/parameters/catalog-prefix'
+      - $ref: '#/components/parameters/tag-name'
+
+    get:
+      tags:
+        - Tag API
+      summary: Load a tag definition
+      operationId: loadTag
+      description: |
+        Load a tag definition from the catalog.
+
+        The response contains the definition's name, description, values, target types, and
+        version token. For more details, refer to the definition of the `Tag` model.
+
+        Requires permission to read the definition.
+      responses:
+        200:
+          $ref: '#/components/responses/LoadTagResponse'
+        400:
+          $ref: '#/components/responses/TagBadRequestResponse'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToGetDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    put:
+      tags:
+        - Tag API
+      summary: Update a tag definition
+      operationId: updateTag
+      description: |
+        Replaces the complete editable definition: its description and its values list. The request
+        describes the state the definition should end in rather than the fields that changed, so both
+        fields are required and a client that wants to keep a value sends it back. An explicit JSON null
+        for description clears it, and so does an empty string. A missing values list, or one sent as an explicit JSON null, returns 400
+        BadRequest, as does a present list that is empty or holds an empty or duplicate member. A missing
+        description returns 400 ValidationError.
+
+        The definition's name is not part of this request; renaming goes through renameTag. target-types
+        is create-only and is likewise not part of it: a request that carries target-types at all,
+        including an explicit JSON null, returns 400 BadRequest.
+
+        Changing values never rewrites existing assignments. An assignment
+        whose stored value was removed from the list remains readable until it is
+        replaced or unassigned; only later writes are checked against the new list.
+
+        current-tag-version is required and must be a non-empty JSON string. A
+        missing, null, empty, or non-string value returns the shared
+        request-validation 400 response.
+
+        Requires permission to modify the definition. A stale or non-matching token returns 409
+        TagVersionMismatch, including a request that would change nothing. A
+        successful update returns the resulting definition and its new token; a
+        request that changes nothing leaves the definition fields unchanged and
+        returns the current token without advancing it. That returned version is the one read while
+        serving the request, and a concurrent write may advance it before the response reaches the caller;
+        the caller's next write then returns 409 TagVersionMismatch. The token check and any definition
+        change are atomic.
+
+        A request that changes nothing may leave its key unrecognized; where it does, a retry of it sent
+        after the definition has changed returns 409 TagVersionMismatch rather than the earlier success.
+        Recognizing it is also allowed, and doing so does not advance the definition's version. A recognized
+        retry of an update that did change the definition returns the definition's current state without
+        applying the update again, on the terms the Idempotency-Key parameter describes.
+      parameters:
+        - $ref: '#/components/parameters/tag-idempotency-key'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UpdateTagRequest'
+      responses:
+        200:
+          $ref: '#/components/responses/UpdateTagResponse'
+        400:
+          description: |
+            Bad Request - target-types was supplied on update, including as an explicit null (it is
+            create-only), or the values list is invalid, meaning it is empty or holds an empty or
+            duplicate member, or a member exceeds 2000 decoded UTF-8 bytes.
+
+            A missing values list, or one present as an explicit JSON null, returns BadRequest: the tag
+            validation row for an invalid definition values list names that type, and it takes precedence.
+            A missing description returns ValidationError, the shared required-field row, because no tag
+            validation row names it.
+
+            InvalidJson covers a body that is not syntactically valid JSON. InvalidIdempotencyKey covers a
+            present but malformed Idempotency-Key header, rejected by the shared handler before this
+            operation runs.
+
+            Possible error types: BadRequest, ValidationError, InvalidJson, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TargetTypesImmutable:
+                  $ref: '#/components/examples/TargetTypesImmutableError'
+                InvalidAllowedValues:
+                  $ref: '#/components/examples/AllowedValuesInvalidError'
+                InvalidIdempotencyKey:
+                  $ref: '#/components/examples/TagInvalidIdempotencyKeyError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToUpdateDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        409:
+          description: |
+            Conflict - the request cannot be applied to the definition's current state; the error
+            type names the cause. For a stale token or a conflicting update, reload the definition
+            and retry with the returned token.
+
+            Possible error types: TagVersionMismatch (the supplied current-tag-version is
+            not the definition's current token, including a request that would change nothing),
+            CommitConflict (the conditional update conflicted after validation, retryable).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagVersionMismatch:
+                  $ref: '#/components/examples/TagVersionMismatchError'
+                TagConcurrentlyModified:
+                  $ref: '#/components/examples/TagCommitConflictError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+    delete:
+      tags:
+        - Tag API
+      summary: Drop a tag definition from the catalog
+      operationId: dropTag
+      description: |
+        Remove a tag definition from the catalog.
+
+        Without detach-all=true, a definition can be deleted only when no assignment on a **live** target
+        uses it. Two kinds of assignment do not block the delete: one confirmed to be orphaned, and one
+        whose target has been soft-dropped. A successful delete makes those relations permanently
+        ineffective, so restoring a soft-dropped target can never restore a deleted definition.
+
+        Failure to load a required entity or its schema metadata is not proof of absence. In that case the
+        server fails the request without making any visible change, rather than treating the assignment as
+        orphaned.
+
+        To remove the definition along with all of its assignments, set detach-all to true; callers then
+        see every assignment and the definition removed, or no change. detach-all=true requires **both**
+        the permission to drop the definition and the definition-side permission to detach its
+        assignments, and it requires them even when the definition currently has no assignments. The
+        server does not check a permission on every attached target.
+
+        After a successful detach-all=true, the definition and every one of its assignments are gone from
+        every Tag API read and reverse lookup together: no later read can expose an assignment of the
+        deleted definition. Physical cleanup of assignment rows may happen later and is never observable,
+        and a cleanup failure must not undo completed deletion or expose retained rows.
+
+        Returning 204 after a partial visible deletion is invalid. A transient execution failure uses the
+        shared server-error responses.
+
+        The definition is permanently deleted and its name is released.
+
+        Requires permission to delete the definition, and detach-all=true additionally requires permission
+        to remove its assignments.
+      parameters:
+        - name: detach-all
+          in: query
+          required: false
+          description: |
+            When set to true, the dropTag operation will also delete every assignment of this tag definition
+            across the catalog.
+          schema:
+            type: boolean
+            default: false
+          example: false
+      responses:
+        204:
+          description: Success, no content
+        400:
+          description: |
+            Bad Request - assignments of this tag definition remain and detach-all is not set to
+            true.
+
+            This operation names TagInUse for that case, and that type takes precedence over any shared
+            type for it. InvalidIdempotencyKey covers a present but malformed Idempotency-Key header: the
+            shared handler inspects the header on any write it sees, and rejecting a malformed one does not
+            make this operation recognize a retry.
+
+            Possible error types: TagInUse, InvalidIdempotencyKey.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagInUse:
+                  $ref: '#/components/examples/TagInUseError'
+        401:
+          $ref: '#/components/responses/TagUnauthorizedResponse'
+        403:
+          $ref: '#/components/responses/TagForbiddenResponse'
+        404:
+          description: |
+            Not Found - the request addresses something that does not exist; the error type names
+            the cause. A catalog that cannot be resolved is NoSuchCatalog; a definition missing inside
+            a catalog that did resolve is NoSuchTag.
+
+            Possible error types: NoSuchCatalog (the catalog identified by {prefix}),
+            NoSuchTag (the tag definition).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PolarisErrorResponse'
+              examples:
+                TagToDeleteDoesNotExist:
+                  $ref: '#/components/examples/NoSuchTagError'
+        503:
+          $ref: '#/components/responses/TagServiceUnavailableResponse'
+        5XX:
+          $ref: '#/components/responses/TagServerErrorResponse'
+
+  /polaris/v1/{prefix}/tags/{tag-name}/assign:

Review Comment:
   I’ll add the rationale to the PR description. I chose separate POST actions to make assign and unassign explicit in the paths. Both take a JSON target, with selected values required only for assign. The policy API’s mapping style would also work, so this is an API design preference rather than a requirement of using JSON bodies.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] Polaris Catalog Spec: Tag Management APIs [polaris]

Posted by "flyingImer (via GitHub)" <gi...@apache.org>.
flyingImer commented on code in PR #5366:
URL: https://github.com/apache/polaris/pull/5366#discussion_r4252978013


##########
spec/polaris-catalog-apis/tag-apis.yaml:
##########
@@ -0,0 +1,1275 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#
+
+---
+paths:
+
+  /polaris/v1/{prefix}/tags:
+    parameters:
+      - $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/prefix'
+
+    post:
+      tags:
+        - Tag API
+      summary: Create a tag definition in the catalog
+      operationId: createTag
+      description: |
+        Creates a tag definition within the catalog identified by {prefix}.
+
+        A tag definition gives a classification a name, a set of allowed values, and the target kinds it may
+        classify. Tag assignments later select exactly one value from the definition's current allowed-values
+        list and attach it to a catalog, namespace, table-like, or column target.
+
+        User provides the following inputs when creating a tag definition
+        - `name` (REQUIRED): The name of the tag definition. It is unique within the catalog.
+        - `allowed-values` (REQUIRED): The values an assignment may select. The list must be non-empty, and
+          every member must be a unique, non-empty string. Matching is exact and case-sensitive.
+        - `target-types` (REQUIRED): The target kinds this definition may classify, directly or through

Review Comment:
   Will save for the future revisions



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: issues-unsubscribe@polaris.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org