#  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.


openapi: 3.0.3
info:
  title: Polaris Management Service
  version: 0.0.1
  description:
    Defines the management APIs for using Polaris to create and manage Iceberg catalogs and their principals
servers:
  - url: "{scheme}://{host}/api/management/v1"
    description: Server URL when the port can be inferred from the scheme
    variables:
      scheme:
        description: The scheme of the URI, either http or https.
        default: https
      host:
        description: The host address for the specified server
        default: localhost
# All routes are currently configured using an Authorization header.
security:
  - OAuth2: []

paths:
  /catalogs:
    get:
      operationId: listCatalogs
      description: List all catalogs in this polaris service
      responses:
        200:
          description: List of catalogs in the polaris service
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Catalogs"
        403:
          description: "The caller does not have permission to list catalog details"
    post:
      operationId: createCatalog
      description: Add a new Catalog
      requestBody:
        description: The Catalog to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCatalogRequest"
      responses:
        201:
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Catalog"
        403:
          description: "The caller does not have permission to create a catalog"
        404:
          description: "The catalog does not exist"
        409:
          description: "A catalog with the specified name already exists"

  /catalogs/{catalogName}:
    parameters:
      - name: catalogName
        in: path
        description: The name of the catalog
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: getCatalog
      description: Get the details of a catalog
      responses:
        200:
          description: The catalog details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Catalog"
        403:
          description: "The caller does not have permission to read catalog details"
        404:
          description: "The catalog does not exist"

    put:
      operationId: updateCatalog
      description: Update an existing catalog
      requestBody:
        description: The catalog details to use in the update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCatalogRequest"
      responses:
        200:
          description: The catalog details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Catalog"
        403:
          description: "The caller does not have permission to update catalog details"
        404:
          description: "The catalog does not exist"
        409:
          description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version"

    delete:
      operationId: deleteCatalog
      description: Delete an existing catalog. The catalog must be empty.
      responses:
        204:
          description: "Success, no content"
        403:
          description: "The caller does not have permission to delete a catalog"
        404:
          description: "The catalog does not exist"

  /principals:
    get:
      operationId: listPrincipals
      description: List the principals for the current catalog
      responses:
        200:
          description: List of principals for this catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Principals"
        403:
          description: "The caller does not have permission to list catalog admins"
        404:
          description: "The catalog does not exist"

    post:
      operationId: createPrincipal
      description: Create a principal
      requestBody:
        description: The principal to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePrincipalRequest"
            example:
              principal:
                name: "alice"
                properties:
                  department: "engineering"
              credentialRotationRequired: false
      responses:
        201:
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalWithCredentials"
        403:
          description: "The caller does not have permission to add a principal"

  /principals/{principalName}:
    parameters:
      - name: principalName
        in: path
        description: The principal name
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: getPrincipal
      description: Get the principal details
      responses:
        200:
          description: The requested principal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Principal"
        403:
          description: "The caller does not have permission to get principal details"
        404:
          description: "The catalog or principal does not exist"

    put:
      operationId: updatePrincipal
      description: Update an existing principal
      requestBody:
        description: The principal details to use in the update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePrincipalRequest"
      responses:
        200:
          description: The updated principal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Principal"
        403:
          description: "The caller does not have permission to update principal details"
        404:
          description: "The principal does not exist"
        409:
          description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version"

    delete:
      operationId: deletePrincipal
      description: Remove a principal from polaris
      responses:
        204:
          description: "Success, no content"
        403:
          description: "The caller does not have permission to delete a principal"
        404:
          description: "The principal does not exist"

  /principals/{principalName}/rotate:
    parameters:
      - name: principalName
        in: path
        description: The user name
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    post:
      operationId: rotateCredentials
      description: Rotate a principal's credentials. The new credentials will be returned in the response. This is the only
        API, aside from createPrincipal, that returns the user's credentials. This API is *not* idempotent.
      responses:
        200:
          description: The principal details along with the newly rotated credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalWithCredentials"
        403:
          description: "The caller does not have permission to rotate credentials"
        404:
          description: "The principal does not exist"

  /principals/{principalName}/reset:
    parameters:
      - name: principalName
        in: path
        description: The principal's name
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    post:
      operationId: resetCredentials
      description: >-
        Reset a principal's credentials to a new set. By default, the system generates random credentials unless
        explicitly allowed to accept user-provided credentials via configuration.  
        This API is *not* idempotent and will return the newly created credentials.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetPrincipalRequest'
      responses:
        200:
          description: The principal details along with the newly reset credentials
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalWithCredentials"
        403:
          description: The caller does not have permission to reset credentials
        404:
          description: The principal does not exist

  /principals/{principalName}/principal-roles:
    parameters:
      - name: principalName
        in: path
        description: The name of the target principal
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: listPrincipalRolesAssigned
      description: List the roles assigned to the principal
      responses:
        200:
          description: List of roles assigned to this principal
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalRoles"
        403:
          description: "The caller does not have permission to list roles"
        404:
          description: "The principal or catalog does not exist"

    put:
      operationId: assignPrincipalRole
      description: Add a role to the principal
      requestBody:
        description: The principal role to assign
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GrantPrincipalRoleRequest"
      responses:
        201:
          description: "Successful response"
        403:
          description: "The caller does not have permission to add assign a role to the principal"
        404:
          description: "The catalog, the principal, or the role does not exist"

  /principals/{principalName}/principal-roles/{principalRoleName}:
    parameters:
      - name: principalName
        in: path
        description: The name of the target principal
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
      - name: principalRoleName
        in: path
        description: The name of the role
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    delete:
      operationId: revokePrincipalRole
      description: Remove a role from a catalog principal
      responses:
        204:
          description: "Success, no content"
        403:
          description: "The caller does not have permission to remove a role from the principal"
        404:
          description: "The catalog or principal does not exist"

  /principal-roles:
    get:
      operationId: listPrincipalRoles
      description: List the principal roles
      responses:
        200:
          description: List of principal roles
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalRoles"
        403:
          description: "The caller does not have permission to list principal roles"
        404:
          description: "The catalog does not exist"

    post:
      operationId: createPrincipalRole
      description: Create a principal role
      requestBody:
        description: The principal to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreatePrincipalRoleRequest"
      responses:
        201:
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalRole"
        403:
          description: "The caller does not have permission to add a principal role"

  /principal-roles/{principalRoleName}:
    parameters:
      - name: principalRoleName
        in: path
        description: The principal role name
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: getPrincipalRole
      description: Get the principal role details
      responses:
        200:
          description: The requested principal role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalRole"
        403:
          description: "The caller does not have permission to get principal role details"
        404:
          description: "The principal role does not exist"

    put:
      operationId: updatePrincipalRole
      description: Update an existing principalRole
      requestBody:
        description: The principalRole details to use in the update
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdatePrincipalRoleRequest"
      responses:
        200:
          description: The updated principal role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalRole"
        403:
          description: "The caller does not have permission to update principal role details"
        404:
          description: "The principal role does not exist"
        409:
          description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version"

    delete:
      operationId: deletePrincipalRole
      description: Remove a principal role from polaris
      responses:
        204:
          description: "Success, no content"
        403:
          description: "The caller does not have permission to delete a principal role"
        404:
          description: "The principal role does not exist"

  /principal-roles/{principalRoleName}/principals:
    parameters:
      - name: principalRoleName
        in: path
        description: The principal role name
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: listAssigneePrincipalsForPrincipalRole
      description: List the Principals to whom the target principal role has been assigned
      responses:
        200:
          description: List the Principals to whom the target principal role has been assigned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Principals"
        403:
          description: "The caller does not have permission to list principals"
        404:
          description: "The principal role does not exist"

  /principal-roles/{principalRoleName}/catalog-roles/{catalogName}:
    parameters:
      - name: principalRoleName
        in: path
        description: The principal role name
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
      - name: catalogName
        in: path
        required: true
        description: The name of the catalog where the catalogRoles reside
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: listCatalogRolesForPrincipalRole
      description: Get the catalog roles mapped to the principal role
      responses:
        200:
          description: The list of catalog roles mapped to the principal role
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogRoles"
        403:
          description: "The caller does not have permission to list catalog roles"
        404:
          description: "The principal role does not exist"

    put:
      operationId: assignCatalogRoleToPrincipalRole
      description: Assign a catalog role to a principal role
      requestBody:
        description: The principal to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/GrantCatalogRoleRequest"
      responses:
        201:
          description: "Successful response"
        403:
          description: "The caller does not have permission to assign a catalog role"

  /principal-roles/{principalRoleName}/catalog-roles/{catalogName}/{catalogRoleName}:
    parameters:
      - name: principalRoleName
        in: path
        description: The principal role name
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
      - name: catalogName
        in: path
        description: The name of the catalog that contains the role to revoke
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
      - name: catalogRoleName
        in: path
        description: The name of the catalog role that should be revoked
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    delete:
      operationId: revokeCatalogRoleFromPrincipalRole
      description: Remove a catalog role from a principal role
      responses:
        204:
          description: "Success, no content"
        403:
          description: "The caller does not have permission to revoke a catalog role"
        404:
          description: "The principal role does not exist"

  /catalogs/{catalogName}/catalog-roles:
    parameters:
      - name: catalogName
        in: path
        description: The catalog for which we are reading/updating roles
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: listCatalogRoles
      description: List existing roles in the catalog
      responses:
        200:
          description: The list of roles that exist in this catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogRoles"
    post:
      operationId: createCatalogRole
      description: Create a new role in the catalog
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateCatalogRoleRequest"
      responses:
        201:
          description: "Successful response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogRole"
        403:
          description: "The principal is not authorized to create roles"
        404:
          description: "The catalog does not exist"

  /catalogs/{catalogName}/catalog-roles/{catalogRoleName}:
    parameters:
      - name: catalogName
        in: path
        description: The catalog for which we are retrieving roles
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
      - name: catalogRoleName
        in: path
        description: The name of the role
        required: true
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: getCatalogRole
      description: Get the details of an existing role
      responses:
        200:
          description: The specified role details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogRole"
        403:
          description: "The principal is not authorized to read role data"
        404:
          description: "The catalog or the role does not exist"

    put:
      operationId: updateCatalogRole
      description: Update an existing role in the catalog
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/UpdateCatalogRoleRequest"
      responses:
        200:
          description: The specified role details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CatalogRole"
        403:
          description: "The principal is not authorized to update roles"
        404:
          description: "The catalog or the role does not exist"
        409:
          description: "The entity version doesn't match the currentEntityVersion; retry after fetching latest version"

    delete:
      operationId: deleteCatalogRole
      description: Delete an existing role from the catalog. All associated grants will also be deleted
      responses:
        204:
          description: "Success, no content"
        403:
          description: "The principal is not authorized to delete roles"
        404:
          description: "The catalog or the role does not exist"

  /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/principal-roles:
    parameters:
      - name: catalogName
        in: path
        required: true
        description: The name of the catalog where the catalog role resides
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
      - name: catalogRoleName
        in: path
        required: true
        description: The name of the catalog role
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: listAssigneePrincipalRolesForCatalogRole
      description: List the PrincipalRoles to which the target catalog role has been assigned
      responses:
        200:
          description: List the PrincipalRoles to which the target catalog role has been assigned
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PrincipalRoles"
        403:
          description: "The caller does not have permission to list principal roles"
        404:
          description: "The catalog or catalog role does not exist"

  /catalogs/{catalogName}/catalog-roles/{catalogRoleName}/grants:
    parameters:
      - name: catalogName
        in: path
        required: true
        description: The name of the catalog where the role will receive the grant
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
      - name: catalogRoleName
        in: path
        required: true
        description: The name of the role receiving the grant (must exist)
        schema:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
    get:
      operationId: listGrantsForCatalogRole
      description: List the grants the catalog role holds
      responses:
        200:
          description: List of all grants given to the role in this catalog
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GrantResources"
    put:
      operationId: addGrantToCatalogRole
      description: Add a new grant to the catalog role
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AddGrantRequest"
      responses:
        201:
          description: "Successful response"
        403:
          description: "The principal is not authorized to create grants"
        404:
          description: "The catalog or the role does not exist"
    post:
      operationId: revokeGrantFromCatalogRole
      description:
        Delete a specific grant from the role. This may be a subset or a superset of the grants the role has. In case of
        a subset, the role will retain the grants not specified. If the `cascade` parameter is true, grant revocation
        will have a cascading effect - that is, if a principal has specific grants on a subresource, and grants are revoked
        on a parent resource, the grants present on the subresource will be revoked as well. By default, this behavior
        is disabled and grant revocation only affects the specified resource.
      parameters:
        - name: cascade
          in: query
          schema:
            type: boolean
            default: false
          description: If true, the grant revocation cascades to all subresources.
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RevokeGrantRequest"
      responses:
        201:
          description: "Successful response"
        403:
          description: "The principal is not authorized to create grants"
        404:
          description: "The catalog or the role does not exist"

components:
  securitySchemes:
    OAuth2:
      type: oauth2
      description: Uses OAuth 2 with client credentials flow
      flows:
        implicit:
          authorizationUrl: "{scheme}://{host}/api/v1/oauth/tokens"
          scopes: {}

  schemas:
    Catalogs:
      type: object
      description: A list of Catalog objects
      properties:
        catalogs:
          type: array
          items:
            $ref: "#/components/schemas/Catalog"
      required:
        - catalogs

    CreateCatalogRequest:
      type: object
      description: Request to create a new catalog
      properties:
        catalog:
          $ref: "#/components/schemas/Catalog"
      required:
        - catalog

    Catalog:
      type: object
      description: A catalog object. A catalog may be internal or external. External catalogs are managed entirely by
        an external catalog interface. Third party catalogs may be other Iceberg REST implementations or other services
        with their own proprietary APIs
      properties:
        type:
          type: string
          enum:
            - INTERNAL
            - EXTERNAL
          description: the type of catalog - internal or external
          default: INTERNAL
        name:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
          description: The name of the catalog
        properties:
          type: object
          properties:
            default-base-location:
              type: string
          additionalProperties:
            type: string
          required:
            - default-base-location
        createTimestamp:
          type: integer
          format: "int64"
          description: The creation time represented as unix epoch timestamp in milliseconds
        lastUpdateTimestamp:
          type: integer
          format: "int64"
          description: The last update time represented as unix epoch timestamp in milliseconds
        entityVersion:
          type: integer
          description: The version of the catalog object used to determine if the catalog metadata has changed
        storageConfigInfo:
          $ref: "#/components/schemas/StorageConfigInfo"
      required:
        - name
        - type
        - storageConfigInfo
        - properties
      discriminator:
        propertyName: type
        mapping:
          INTERNAL: "#/components/schemas/PolarisCatalog"
          EXTERNAL: "#/components/schemas/ExternalCatalog"


    PolarisCatalog:
      type: object
      allOf:
        - $ref: "#/components/schemas/Catalog"
      description: The base catalog type - this contains all the fields necessary to construct an INTERNAL catalog

    ExternalCatalog:
      description: An externally managed catalog
      type: object
      allOf:
        - $ref: "#/components/schemas/Catalog"
        - type: object
          properties:
            connectionConfigInfo:
              $ref: "#/components/schemas/ConnectionConfigInfo"

    ConnectionConfigInfo:
      type: object
      description: A connection configuration representing a remote catalog service. IMPORTANT - Specifying a
        ConnectionConfigInfo in an ExternalCatalog is currently an experimental API and is subject to change.
      properties:
        connectionType:
          type: string
          enum:
            - ICEBERG_REST
            - HADOOP
            - HIVE
          description: The type of remote catalog service represented by this connection
        uri:
          type: string
          description: URI to the remote catalog service
        authenticationParameters:
          $ref: "#/components/schemas/AuthenticationParameters"
        serviceIdentity:
          $ref: '#/components/schemas/ServiceIdentityInfo'
      required:
        - connectionType
      discriminator:
        propertyName: connectionType
        mapping:
          ICEBERG_REST: "#/components/schemas/IcebergRestConnectionConfigInfo"
          HADOOP: "#/components/schemas/HadoopConnectionConfigInfo"
          HIVE: "#/components/schemas/HiveConnectionConfigInfo"

    IcebergRestConnectionConfigInfo:
      type: object
      description: Configuration necessary for connecting to an Iceberg REST Catalog
      allOf:
        - $ref: '#/components/schemas/ConnectionConfigInfo'
      properties:
        remoteCatalogName:
          type: string
          description: The name of a remote catalog instance within the remote catalog service; in some older systems
            this is specified as the 'warehouse' when multiple logical catalogs are served under the same base
            uri, and often translates into a 'prefix' added to all REST resource paths

    HadoopConnectionConfigInfo:
      type: object
      description: Configuration necessary for connecting to a Hadoop Catalog
      allOf:
        - $ref: '#/components/schemas/ConnectionConfigInfo'
      properties:
        warehouse:
          type: string
          description: The file path to where this catalog should store tables
    
    HiveConnectionConfigInfo:
      type: object
      description: Configuration necessary for connecting to a Hive Catalog
      allOf:
        - $ref: '#/components/schemas/ConnectionConfigInfo'
      properties:
        warehouse:
          type: string
          description: The warehouse location for the hive catalog.

    AuthenticationParameters:
      type: object
      description: Authentication-specific information for a connection
      properties:
        authenticationType:
          type: string
          enum:
            - OAUTH
            - BEARER
            - SIGV4
            - IMPLICIT
          description: The type of authentication to use when connecting to the remote rest service
      required:
        - authenticationType
      discriminator:
        propertyName: authenticationType
        mapping:
          OAUTH: "#/components/schemas/OAuthClientCredentialsParameters"
          BEARER: "#/components/schemas/BearerAuthenticationParameters"
          SIGV4: "#/components/schemas/SigV4AuthenticationParameters"
          IMPLICIT: "#/components/schemas/ImplicitAuthenticationParameters"

    OAuthClientCredentialsParameters:
      type: object
      description: OAuth authentication based on client_id/client_secret
      allOf:
        - $ref: '#/components/schemas/AuthenticationParameters'
      properties:
        tokenUri:
          type: string
          description: Token server URI
        clientId:
          type: string
          description: oauth client id
        clientSecret:
          type: string
          format: password
          description: oauth client secret (input-only)
        scopes:
          type: array
          items:
            type: string
          description: oauth scopes to specify when exchanging for a short-lived access token

    BearerAuthenticationParameters:
      type: object
      description: Bearer authentication directly embedded in request auth headers
      allOf:
        - $ref: '#/components/schemas/AuthenticationParameters'
      properties:
        bearerToken:
          type: string
          format: password
          description: Bearer token (input-only)

    SigV4AuthenticationParameters:
      type: object
      description: AWS Signature Version 4 authentication
      allOf:
        - $ref: '#/components/schemas/AuthenticationParameters'
      properties:
        roleArn:
          type: string
          description: The aws IAM role arn assumed by polaris userArn when signing requests
          example: "arn:aws:iam::123456789001:role/role-that-has-remote-catalog-access"
        roleSessionName:
          type: string
          description: The role session name to be used by the SigV4 protocol for signing requests
          example: "polaris-remote-catalog-access"
        externalId:
          type: string
          description: An optional external id used to establish a trust relationship with AWS in the trust policy
          example: "external-id-1234"
        signingRegion:
          type: string
          description: Region to be used by the SigV4 protocol for signing requests
          example: "us-west-2"
        signingName:
          type: string
          description: The service name to be used by the SigV4 protocol for signing requests, the default signing name is "execute-api" is if not provided
          example: "glue"
      required:
        - roleArn
        - signingRegion

    ImplicitAuthenticationParameters:
      type: object
      description: Polaris does not explicitly accept any authentication parameters for the connection. Authentication 
        parameters found in the environment and/or configuration files will be used for this connection.
      allOf:
        - $ref: '#/components/schemas/AuthenticationParameters'

    StorageConfigInfo:
      type: object
      description: A storage configuration used by catalogs
      properties:
        storageType:
          type: string
          enum:
            - S3
            - GCS
            - AZURE
            - FILE
          description: The cloud provider type this storage is built on. FILE is supported for testing purposes only
        allowedLocations:
          type: array
          items:
            type: string
          example: "For AWS [s3://bucketname/prefix/], for AZURE [abfss://container@storageaccount.blob.core.windows.net/prefix/], for GCP [gs://bucketname/prefix/]"
        storageName:
          type: string
          description: An optional name referencing a server-side storage configuration
      required:
        - storageType
      discriminator:
        propertyName: storageType
        mapping:
          S3: "#/components/schemas/AwsStorageConfigInfo"
          AZURE: "#/components/schemas/AzureStorageConfigInfo"
          GCS: "#/components/schemas/GcpStorageConfigInfo"
          FILE: "#/components/schemas/FileStorageConfigInfo"

    AwsStorageConfigInfo:
      type: object
      description: aws storage configuration info
      allOf:
        - $ref: '#/components/schemas/StorageConfigInfo'
        - type: object
          properties:
            roleArn:
              type: string
              description: the aws role arn that grants privileges on the S3 buckets
              example: "arn:aws:iam::123456789001:principal/abc1-b-self1234"
            externalId:
              type: string
              description: an optional external id used to establish a trust relationship with AWS in the trust policy
            userArn:
              type: string
              description: the aws user arn used to assume the aws role
              example: "arn:aws:iam::123456789001:user/abc1-b-self1234"
            currentKmsKey:
              type: string
              description: the aws kms key arn used to encrypt s3 data
              example: "arn:aws:kms::123456789001:key/01234578"
            allowedKmsKeys:
              type: array
              description: The list of kms keys that this catalog and its clients are allowed to use for reading s3 data
              items:
                type: string
              example: ["arn:aws:kms::123456789001:key/01234578"]
            region:
              type: string
              description: the aws region where data is stored
              example: "us-east-2"
            endpoint:
              type: string
              description: >-
                endpoint for S3 requests (optional). Clients always see this value (if it is set). Polaris Servers
                may be configured to use a different endpoint URI via the `endpointInternal` property.
              example: "https://s3.example.com:1234"
            stsEndpoint:
              type: string
              description: >-
                endpoint for STS requests made by the Polaris Server (optional). If not set, defaults to
                'endpointInternal' (which in turn defaults to `endpoint`).
              example: "https://sts.example.com:1234"
            stsUnavailable:
              type: boolean
              description: >-
                if set to `true`, instructs Polaris Servers to avoid using the STS endpoints when obtaining credentials
                for accessing data and metadata files within the related catalog. Setting this property to `true`
                effectively disables vending storage credentials to clients. This setting is intended for configuring
                catalogs with S3-compatible storage implementations that do not support STS.
            endpointInternal:
              type: string
              description: >-
                endpoint for S3 requests made by the Polaris Server (optional). If set, Polaris Service will use
                this value instead of `endpoint`. If not set, defaults to `endpoint`. Iceberg REST API clients never
                see this value.
              example: "https://s3.internal.example.com:1234"
            pathStyleAccess:
              type: boolean
              description: >- 
                Whether S3 requests to files in this catalog should use 'path-style addressing for buckets'.
              example: true
              default: false
            kmsUnavailable:
              type: boolean
              description: >-
                if set to `true`, instructs Polaris Servers to avoid adding KMS key policies.

    AzureStorageConfigInfo:
      type: object
      description: azure storage configuration info
      allOf:
        - $ref: '#/components/schemas/StorageConfigInfo'
        - type: object
          properties:
            tenantId:
              type: string
              description: the tenant id that the storage accounts belong to
            multiTenantAppName:
              type: string
              description: the name of the azure client application
            consentUrl:
              type: string
              description: URL to the Azure permissions request page
            hierarchical:
              type: boolean
              description: >-
                If set to `true`, instructs Polaris Servers to scope SAS tokens down to the most specific path
                in the storage container (in most cases the table's base location). This flag should be set only
                if hierarchical namespace is enabled in the Azure storage account. Using this feature with 
                non-hierarchical storage will lead to storage authorization errors in runtime in most cases.
          required:
            - tenantId

    GcpStorageConfigInfo:
      type: object
      description: gcp storage configuration info
      allOf:
        - $ref: '#/components/schemas/StorageConfigInfo'
        - type: object
          properties:
            gcsServiceAccount:
              type: string
              description: a Google cloud storage service account

    FileStorageConfigInfo:
      type: object
      description: file storage configuration info
      allOf:
        - $ref: '#/components/schemas/StorageConfigInfo'

    ServiceIdentityInfo:
      type: object
      description: Identity metadata for the Polaris service used to access external resources.
      readOnly: true
      properties:
        identityType:
          type: string
          enum:
            - AWS_IAM
          description: The type of identity used to access external resources
      required:
        - identityType
      discriminator:
        propertyName: identityType
        mapping:
          AWS_IAM: "#/components/schemas/AwsIamServiceIdentityInfo"

    AwsIamServiceIdentityInfo:
      type: object
      allOf:
        - $ref: '#/components/schemas/ServiceIdentityInfo'
      properties:
        iamArn:
          type: string
          description: The ARN of the IAM user or IAM role Polaris uses to assume roles and then access external resources.
          example: "arn:aws:iam::111122223333:user/polaris-service-user"
      required:
        - iamArn

    UpdateCatalogRequest:
      description: Updates to apply to a Catalog. Any fields which are required in the Catalog
        will remain unaltered if omitted from the contents of this Update request.
      type: object
      properties:
        currentEntityVersion:
          type: integer
          description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.
        properties:
          type: object
          additionalProperties:
            type: string
        storageConfigInfo:
          $ref: "#/components/schemas/StorageConfigInfo"

    Principals:
      description: A list of Principals
      type: object
      properties:
        principals:
          type: array
          items:
            $ref: "#/components/schemas/Principal"
      required:
        - principals

    PrincipalWithCredentials:
      description: A user with its client id and secret. This type is returned when a new principal is created or when its
        credentials are rotated
      type: object
      properties:
        principal:
          $ref: "#/components/schemas/Principal"
        credentials:
          type: object
          properties:
            clientId:
              type: string
            clientSecret:
              type: string
              format: password
      required:
        - principal
        - credentials

    CreatePrincipalRequest:
      type: object
      properties:
        principal:
          $ref: '#/components/schemas/Principal'
        credentialRotationRequired:
          type: boolean
          description: If true, the initial credentials can only be used to call rotateCredentials

    Principal:
      description: A Polaris principal.
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
        clientId:
          type: string
          description: The output-only OAuth clientId associated with this principal if applicable
        properties:
          type: object
          additionalProperties:
            type: string
        createTimestamp:
          type: integer
          format: "int64"
        lastUpdateTimestamp:
          type: integer
          format: "int64"
        entityVersion:
          type: integer
          description: The version of the principal object used to determine if the principal metadata has changed
      required:
        - name

    UpdatePrincipalRequest:
      description: Updates to apply to a Principal
      type: object
      properties:
        currentEntityVersion:
          type: integer
          description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.
        properties:
          type: object
          additionalProperties:
            type: string
      required:
        - currentEntityVersion
        - properties

    ResetPrincipalRequest:
      type: object
      properties:
        clientId:
          type: string
          description: >
            Optional client ID to set for the principal.
            Must be a valid client ID previously generated by this service.
        clientSecret:
          type: string
          description: >
            Optional client secret to set for the principal.
            Polaris service implementations may impose extra requirements on what is accepted as a secret (special chars, length, etc.)

    PrincipalRoles:
      type: object
      properties:
        roles:
          type: array
          items:
            $ref: "#/components/schemas/PrincipalRole"
      required:
        - roles

    GrantPrincipalRoleRequest:
      type: object
      properties:
        principalRole:
          $ref: '#/components/schemas/PrincipalRole'

    CreatePrincipalRoleRequest:
      type: object
      properties:
        principalRole:
          $ref: '#/components/schemas/PrincipalRole'

    PrincipalRole:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
          description: The name of the role
        federated:
          type: boolean
          description: Whether the principal role is a federated role (that is, managed by an external identity provider)
          default: false
        properties:
          type: object
          additionalProperties:
            type: string
        createTimestamp:
          type: integer
          format: "int64"
        lastUpdateTimestamp:
          type: integer
          format: "int64"
        entityVersion:
          type: integer
          description: The version of the principal role object used to determine if the principal role metadata has changed
      required:
        - name

    UpdatePrincipalRoleRequest:
      description: Updates to apply to a Principal Role
      type: object
      properties:
        currentEntityVersion:
          type: integer
          description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.
        properties:
          type: object
          additionalProperties:
            type: string
      required:
        - currentEntityVersion
        - properties

    CatalogRoles:
      type: object
      properties:
        roles:
          type: array
          items:
            $ref: "#/components/schemas/CatalogRole"
          description: The list of catalog roles
      required:
        - roles

    GrantCatalogRoleRequest:
      type: object
      properties:
        catalogRole:
          $ref: '#/components/schemas/CatalogRole'

    CreateCatalogRoleRequest:
      type: object
      properties:
        catalogRole:
          $ref: '#/components/schemas/CatalogRole'

    CatalogRole:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 256
          pattern: '^(?!\s*[s|S][y|Y][s|S][t|T][e|E][m|M]\$).*$'
          description: The name of the role
        properties:
          type: object
          additionalProperties:
            type: string
        createTimestamp:
          type: integer
          format: "int64"
        lastUpdateTimestamp:
          type: integer
          format: "int64"
        entityVersion:
          type: integer
          description: The version of the catalog role object used to determine if the catalog role metadata has changed
      required:
        - name

    UpdateCatalogRoleRequest:
      description: Updates to apply to a Catalog Role
      type: object
      properties:
        currentEntityVersion:
          type: integer
          description: The version of the object onto which this update is applied; if the object changed, the update will fail and the caller should retry after fetching the latest version.
        properties:
          type: object
          additionalProperties:
            type: string
      required:
        - currentEntityVersion
        - properties

    ViewPrivilege:
      type: string
      enum:
        - CATALOG_MANAGE_ACCESS
        - VIEW_DROP
        - VIEW_LIST
        - VIEW_READ_PROPERTIES
        - VIEW_WRITE_PROPERTIES
        - VIEW_FULL_METADATA

    TablePrivilege:
      type: string
      enum:
        - CATALOG_MANAGE_ACCESS
        - TABLE_DROP
        - TABLE_LIST
        - TABLE_READ_PROPERTIES
        - TABLE_WRITE_PROPERTIES
        - TABLE_READ_DATA
        - TABLE_WRITE_DATA
        - TABLE_FULL_METADATA
        - TABLE_ATTACH_POLICY
        - TABLE_DETACH_POLICY
        - TABLE_ASSIGN_UUID
        - TABLE_UPGRADE_FORMAT_VERSION
        - TABLE_ADD_SCHEMA
        - TABLE_SET_CURRENT_SCHEMA
        - TABLE_ADD_PARTITION_SPEC
        - TABLE_ADD_SORT_ORDER
        - TABLE_SET_DEFAULT_SORT_ORDER
        - TABLE_ADD_SNAPSHOT
        - TABLE_SET_SNAPSHOT_REF
        - TABLE_REMOVE_SNAPSHOTS
        - TABLE_REMOVE_SNAPSHOT_REF
        - TABLE_SET_LOCATION
        - TABLE_SET_PROPERTIES
        - TABLE_REMOVE_PROPERTIES
        - TABLE_SET_STATISTICS
        - TABLE_REMOVE_STATISTICS
        - TABLE_REMOVE_PARTITION_SPECS
        - TABLE_MANAGE_STRUCTURE

    PolicyPrivilege:
      type: string
      enum:
        - CATALOG_MANAGE_ACCESS
        - POLICY_READ
        - POLICY_DROP
        - POLICY_WRITE
        - POLICY_LIST
        - POLICY_FULL_METADATA
        - POLICY_ATTACH
        - POLICY_DETACH

    NamespacePrivilege:
      type: string
      enum:
        - CATALOG_MANAGE_ACCESS
        - CATALOG_MANAGE_CONTENT
        - CATALOG_MANAGE_METADATA
        - NAMESPACE_CREATE
        - TABLE_CREATE
        - VIEW_CREATE
        - NAMESPACE_DROP
        - TABLE_DROP
        - VIEW_DROP
        - NAMESPACE_LIST
        - TABLE_LIST
        - VIEW_LIST
        - NAMESPACE_READ_PROPERTIES
        - TABLE_READ_PROPERTIES
        - VIEW_READ_PROPERTIES
        - NAMESPACE_WRITE_PROPERTIES
        - TABLE_WRITE_PROPERTIES
        - VIEW_WRITE_PROPERTIES
        - TABLE_READ_DATA
        - TABLE_WRITE_DATA
        - NAMESPACE_FULL_METADATA
        - TABLE_FULL_METADATA
        - VIEW_FULL_METADATA
        - POLICY_CREATE
        - POLICY_WRITE
        - POLICY_READ
        - POLICY_DROP
        - POLICY_LIST
        - POLICY_FULL_METADATA
        - NAMESPACE_ATTACH_POLICY
        - NAMESPACE_DETACH_POLICY
        - TABLE_ASSIGN_UUID
        - TABLE_UPGRADE_FORMAT_VERSION
        - TABLE_ADD_SCHEMA
        - TABLE_SET_CURRENT_SCHEMA
        - TABLE_ADD_PARTITION_SPEC
        - TABLE_ADD_SORT_ORDER
        - TABLE_SET_DEFAULT_SORT_ORDER
        - TABLE_ADD_SNAPSHOT
        - TABLE_SET_SNAPSHOT_REF
        - TABLE_REMOVE_SNAPSHOTS
        - TABLE_REMOVE_SNAPSHOT_REF
        - TABLE_SET_LOCATION
        - TABLE_SET_PROPERTIES
        - TABLE_REMOVE_PROPERTIES
        - TABLE_SET_STATISTICS
        - TABLE_REMOVE_STATISTICS
        - TABLE_REMOVE_PARTITION_SPECS
        - TABLE_MANAGE_STRUCTURE

    CatalogPrivilege:
      type: string
      enum:
        - CATALOG_MANAGE_ACCESS
        - CATALOG_MANAGE_CONTENT
        - CATALOG_MANAGE_METADATA
        - CATALOG_READ_PROPERTIES
        - CATALOG_WRITE_PROPERTIES
        - NAMESPACE_CREATE
        - TABLE_CREATE
        - VIEW_CREATE
        - NAMESPACE_DROP
        - TABLE_DROP
        - VIEW_DROP
        - NAMESPACE_LIST
        - TABLE_LIST
        - VIEW_LIST
        - NAMESPACE_READ_PROPERTIES
        - TABLE_READ_PROPERTIES
        - VIEW_READ_PROPERTIES
        - NAMESPACE_WRITE_PROPERTIES
        - TABLE_WRITE_PROPERTIES
        - VIEW_WRITE_PROPERTIES
        - TABLE_READ_DATA
        - TABLE_WRITE_DATA
        - NAMESPACE_FULL_METADATA
        - TABLE_FULL_METADATA
        - VIEW_FULL_METADATA
        - POLICY_CREATE
        - POLICY_WRITE
        - POLICY_READ
        - POLICY_DROP
        - POLICY_LIST
        - POLICY_FULL_METADATA
        - CATALOG_ATTACH_POLICY
        - CATALOG_DETACH_POLICY
        - TABLE_ASSIGN_UUID
        - TABLE_UPGRADE_FORMAT_VERSION
        - TABLE_ADD_SCHEMA
        - TABLE_SET_CURRENT_SCHEMA
        - TABLE_ADD_PARTITION_SPEC
        - TABLE_ADD_SORT_ORDER
        - TABLE_SET_DEFAULT_SORT_ORDER
        - TABLE_ADD_SNAPSHOT
        - TABLE_SET_SNAPSHOT_REF
        - TABLE_REMOVE_SNAPSHOTS
        - TABLE_REMOVE_SNAPSHOT_REF
        - TABLE_SET_LOCATION
        - TABLE_SET_PROPERTIES
        - TABLE_REMOVE_PROPERTIES
        - TABLE_SET_STATISTICS
        - TABLE_REMOVE_STATISTICS
        - TABLE_REMOVE_PARTITION_SPECS
        - TABLE_MANAGE_STRUCTURE

    AddGrantRequest:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/GrantResource'

    RevokeGrantRequest:
      type: object
      properties:
        grant:
          $ref: '#/components/schemas/GrantResource'

    ViewGrant:
      allOf:
        - $ref: '#/components/schemas/GrantResource'
        - type: object
          properties:
            namespace:
              type: array
              items:
                type: string
            viewName:
              type: string
              minLength: 1
              maxLength: 256
            privilege:
              $ref: '#/components/schemas/ViewPrivilege'
          required:
            - namespace
            - viewName
            - privilege

    TableGrant:
      allOf:
        - $ref: '#/components/schemas/GrantResource'
        - type: object
          properties:
            namespace:
              type: array
              items:
                type: string
            tableName:
              type: string
              minLength: 1
              maxLength: 256
            privilege:
              $ref: '#/components/schemas/TablePrivilege'
          required:
            - namespace
            - tableName
            - privilege

    PolicyGrant:
      allOf:
        - $ref: '#/components/schemas/GrantResource'
        - type: object
          properties:
            namespace:
              type: array
              items:
                type: string
            policyName:
              type: string
            privilege:
              $ref: '#/components/schemas/PolicyPrivilege'
          required:
            - namespace
            - policyName
            - privilege

    NamespaceGrant:
      allOf:
        - $ref: '#/components/schemas/GrantResource'
        - type: object
          properties:
            namespace:
              type: array
              items:
                type: string
            privilege:
              $ref: '#/components/schemas/NamespacePrivilege'
          required:
            - namespace
            - privilege


    CatalogGrant:
      allOf:
        - $ref: '#/components/schemas/GrantResource'
        - type: object
          properties:
            privilege:
              $ref: '#/components/schemas/CatalogPrivilege'
          required:
            - privilege

    GrantResource:
      type: object
      discriminator:
        propertyName: type
        mapping:
          catalog: '#/components/schemas/CatalogGrant'
          namespace: '#/components/schemas/NamespaceGrant'
          table: '#/components/schemas/TableGrant'
          view: '#/components/schemas/ViewGrant'
          policy: '#/components/schemas/PolicyGrant'
      properties:
        type:
          type: string
          enum:
            - catalog
            - namespace
            - table
            - view
            - policy
      required:
        - type

    GrantResources:
      type: object
      properties:
        grants:
          type: array
          items:
            $ref: "#/components/schemas/GrantResource"
      required:
        - grants