# 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.0
info:
  title: Ozone Recon REST API
  license:
    url: http://www.apache.org/licenses/LICENSE-2.0.html
    name: Apache 2.0 License
servers:
  - url: /api/v1/
tags:
  - name: Containers
    description: APIs to fetch information about the available containers. **Admin Only**
  - name: Volumes
    description: APIs to fetch information about the available volumes. **Admin Only**
  - name: Buckets
    description: APIs to fetch information about the available buckets. **Admin Only**
  - name: Keys
    description: APIs to fetch information about the available keys. **Admin Only**
  - name: Containers and Keys
    description: APIs to fetch information about the available containers and keys. **Admin Only**
  - name: Blocks Metadata
    description: APIs to fetch metadata for the blocks available. **Admin Only**
  - name: Namespace Metadata
    description: APIs to fetch metadata for the namespace. **Admin Only**
  - name: Cluster State
    description: APIs to fetch data about the cluster state
  - name: Datanodes
    description: APIs to fetch data about the Datanodes
  - name: Pipelines
    description: APIs to fetch data about the Pipelines
  - name: Tasks
    description: APIs to fetch data about status of Recon Tasks
  - name: Utilization
    description: APIs to fetch data about space utilization
  - name: Metrics
    description: APIs to fetch data about various metrics from Prometheus
    externalDocs:
      description: Prometheus API docs
      url: https://prometheus.io/docs/prometheus/latest/querying/api/
  - name: Storage Distribution
    description: APIs to fetch data about storage distribution across datanodes. **Admin Only**
  - name: Pending Deletion
    description: APIs to fetch data about pending deletions by component (SCM, OM, or Datanodes). **Admin Only**
paths:
  /containers:
    get:
      tags:
        - Containers
      summary: Get all Container Metadata information
      operationId: getContainerInfo
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerMetadata'
  /containers/deleted:
    get:
      tags:
        - Containers
      summary: Return all DELETED containers in SCM
      operationId: getSCMDeletedContainers
      responses:
        200:
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedContainers'
  /containers/missing:
    get:
      tags:
        - Containers
      summary: Get the MissingContainerMetadata for all missing containers
      operationId: getMissingContainers
      parameters:
        - name: limit
          in: query
          description: Limit of the number of results returned
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MissingContainerMetadata'
  /containers/{id}/replicaHistory:
    get:
      tags:
        - Containers
      summary: Get all the Replica history for a given container id
      operationId: getReplicaHistoryForContainer
      parameters:
        - name: id
          in: path
          description: ID of the container for which we want ContainerHistory
          required: true
          schema:
            type: integer
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReplicaHistory'
  /containers/unhealthy:
    get:
      tags:
        - Containers
      summary: Get UnhealthyContainerMetadata for all the unhealthy containers
      operationId: getUnhealthyContainers
      parameters:
        - name: batchNum
          in: query
          description: Size of the batch for the result. It will give us results from **(limit + 1) to (2 * limit)**
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Limit of the number of results returned
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnhealthyContainerMetadata'
  /containers/unhealthy/{state}:
    get:
      tags:
        - Containers
      summary: Returns UnhealthyContainerMetadata for all the unhealthy containers with the specified state
      operationId: getUnhealthyContainersWithState
      parameters:
        - name: state
          in: path
          description: State of the container which is one of **MISSING**, **MIS_REPLICATED**, **UNDER_REPLICATED**, **OVER_REPLICATED**
          required: true
          schema:
            type: string
            example: MISSING
        - name: batchNum
          in: query
          description: Size of the batch for the result. It will give us results from **(limit + 1) to (2 * limit)**
          required: false
          schema:
            type: integer
        - name: limit
          in: query
          description: Limit of the number of results returned
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnhealthyContainerMetadata'
  /containers/mismatch:
    get:
      tags:
        - Containers
      summary: Returns the list of mis-matched containers between OM and SCM
      operationId: getContainerMisMatchInsights
      parameters:
        - name: prevKey
          in: query
          description: Stores the previous key after which to fetch the data
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
        - name: missingIn
          in: query
          description: Filters by where a given container is missing i.e. in OM or SCM
          required: false
          schema:
            type: string
            default: SCM
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MismatchedContainers'
  /containers/mismatch/deleted:
    get:
      tags:
        - Containers
      summary: Returns the list of DELETED containers in SCM that are present in OM
      operationId: getOmContainersDeletedInSCM
      parameters:
        - name: prevKey
          in: query
          description: Stores the previous key after which to fetch the data
          required: false
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletedMismatchedContainers'
  /volumes:
    get:
      tags:
        - Volumes
      summary: Returns the set of all volumes present
      operationId: getVolumes
      parameters:
        - name: prevKey
          in: query
          description: Stores the previous key after which to fetch the data
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Volumes'
  /buckets:
    get:
      tags:
        - Buckets
      summary: Returns the set of all buckets across all volumes
      operationId: getBuckets
      parameters:
        - name: volume
          in: query
          description: Stores the name of the volumes whose buckets to fetch
          required: false
          schema:
            type: string
        - name: prevKey
          in: query
          description: Stores the previous key after which to fetch the data
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Buckets'
  /keys/open:
    get:
      tags:
        - Keys
      summary: Returns the set of keys/files which are open
      operationId: getOpenKeyInfo
      parameters:
        - name: prevKey
          in: query
          description: Stores the previous key after which to fetch the data.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
        - name: startPrefix
          in: query
          description: Will return keys matching this prefix
          schema:
            type: integer
        - name: includeFso
          in: query
          description: Boolean value to determine whether to include FSO keys or not
          required: false
          schema:
            type: boolean
            default: false
        - name: includeNonFso
          in: query
          description: Boolean value to determine whether to include non-FSO keys or not
          required: false
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenKeys'
  /keys/open/summary:
    get:
      tags:
        - Keys
      summary: Returns the summary of all open keys info
      operationId: getOpenKeySummary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenKeysSummary'

  /keys/deletePending:
    get:
      tags:
        - Keys
      summary: Returns the set of keys/files which are pending for deletion
      operationId: getDeletedKeyInfo
      parameters:
        - name: prevKey
          in: query
          description: Stores the previous key after which to fetch the data.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
        - name: startPrefix
          in: query
          description: Will return keys matching this prefix
          schema:
            type: string
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePendingKeys'
  /keys/deletePending/dirs:
    get:
      tags:
        - Keys
      summary: Returns the set of keys/files which are pending for deletion
      operationId: getDeletedDirInfo
      parameters:
        - name: prevKey
          in: query
          description: Stores the previous key after which to fetch the data.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePendingDirs'
  /keys/deletePending/summary:
    get:
      tags:
        - Keys
      summary: Returns the summary of all keys pending deletion info
      operationId: getDeletedKeySummary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePendingSummary'
  /keys/deletePending/dirs/summary:
    get:
      tags:
        - Keys
      summary: Retrieves the summary of deleted directories.
      operationId: getDeletedDirectorySummary
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  totalDeletedDirectories:
                    type: integer
  /containers/{id}/keys:
    get:
      tags:
        - Containers and Keys
      summary: Get the Key metadata for all keys present in the given container ID
      operationId: getKeysForContainer
      parameters:
        - name: id
          in: path
          description: ID of the container for which we want Key Metadata
          required: true
          schema:
            type: integer
        - name: prevKey
          in: query
          description: Only return keys that are present after the given key prevKey prefix
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Limit of the number of results returned
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeyMetadata'
  /blocks/deletePending:
    get:
      tags:
        - Blocks Metadata
      summary: Fetch the list of blocks pending for deletion
      operationId: getBlocksPendingDeletion
      parameters:
        - name: prevKey
          in: query
          description: Only returns the list of blocks pending for deletion, that are present after the given block id (prevKey).
          example: 4
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Stores the limit for the number of results to fetch
          required: false
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeletePendingBlocks'
  /namespace/summary:
    get:
      tags:
        - Namespace Metadata
      summary: Returns a basic summary of the path, including entity type and aggregate count of objects under the path.
      operationId: getBasicInfo
      parameters:
        - name: path
          in: query
          description: The path request in string without any protocol prefix.
          example: /volume1/bucket1
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful operation<br>
            #### **Note**:
            #### status can be either **OK** if path exists else **PATH_NOT_FOUND**
            #### If **any num parameter is -1**, the path request is not applicable to such an entity type.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceMetadataResponse'
  /namespace/usage:
    get:
      tags:
        - Namespace Metadata
      summary: Returns namespace usage of all sub-paths under the path.
      operationId: getDiskUsage
      parameters:
        - name: path
          in: query
          description: The path request in string without any protocol prefix.
          example: /volume1/bucket1
          required: true
          schema:
            type: string
        - name: files
          in: query
          description: This boolean has a default value of false. When set to true, it calculates the namespace usage for keys within the specified path and also provides a list of their corresponding sub-paths.
          example: true
          required: false
          schema:
            type: boolean
        - name: replica
          in: query
          description: A boolean with a default value of false. If set to true, computes namespace usage with replicated size of keys.
          example: true
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: |
            Successful operation<br>
            #### **Note**:
            #### The below example response is for the sample endpoint: **namespace/usage?path=/vol1/bucket1&files=true&replica=true**
            #### status can be either **OK** if path exists else **PATH_NOT_FOUND**
            #### If files is set to **false**, sub-path **/vol1/bucket1/key1-1 is omitted**.
            #### If replica is set to **false**, **sizeWithReplica returns -1**.
            #### If the path’s entity type cannot have direct keys (Root, Volume), sizeDirectKey returns -1.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataDiskUsage'
  /namespace/quota:
    get:
      tags:
        - Namespace Metadata
      summary: Returns the quota allowed and used under the path. Only volumes and buckets have quota. Other types are not applicable to the quota request.
      operationId: getQuotaUsage
      parameters:
        - name: path
          in: query
          description: The path request in string without any protocol prefix.
          example: /volume1/bucket1
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful operation<br>
            #### **Note**:
            #### status can be either **OK** if path exists else **PATH_NOT_FOUND**, **TYPE_NOT_APPLICABLE** if path exists, but the path’s entity type is not applicable to the request.
            #### If **quota is not set, "allowed" returns -1**
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataQuota'
  /namespace/dist:
    get:
      tags:
        - Namespace Metadata
      summary: Returns the file size distribution of all keys under the path.
      operationId: getFileSizeDistribution
      parameters:
        - name: path
          in: query
          description: The path request in string without any protocol prefix.
          example: /
          required: true
          schema:
            type: string
      responses:
        '200':
          description: |
            Successful operation<br>
            #### **Note**:
            #### status can be either **OK** if path exists else **PATH_NOT_FOUND**, **TYPE_NOT_APPLICABLE** if path exists, but the path is a key, which does not have a file size distribution.
            #### Recon keeps track of all keys with size from **1 KB to 1 PB**.
            #### For keys **smaller than 1 KB, map to the first bin (index)**, for **keys larger than 1 PB, map to the last bin (index)**.
            #### Each **index of dist** is mapped to a file size range (e.g. **1 MB - 2 MB**).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataSpaceDist'
  /clusterState:
    get:
      tags:
        - Cluster State
      summary: Returns the summary of the current state of the Ozone cluster.
      operationId: getClusterState
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClusterState'
  /datanodes:
    get:
      tags:
        - Datanodes
      summary: Returns all the datanodes in the cluster.
      operationId: getDatanodes
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatanodesSummary'
  /datanodes/decommission/info:
    get:
      tags:
        - Datanodes
      summary: Returns all the datanodes in the decommissioning state
      operationId: getDecommissioningDatanodes
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatanodesDecommissionInfo'
  /datanodes/decommission/info/datanode:
    get:
      tags:
        - Datanodes
      summary: Returns info of a specific datanode for which decommissioning is initiated
      operationId: getDecommissionInfoForDatanode
      parameters:
        - name: uuid
          in: query
          description: The uuid of the datanode being decommissioned.
          required: false
          schema:
            type: string
        - name: ipAddress
          in: query
          description: The ipAddress of the datanode being decommissioned.
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatanodesDecommissionInfo'
  /datanodes/remove:
    put:
      tags:
        - Datanodes
      summary: Removes datanodes from Recon's memory and nodes table in Recon DB.
      operationId: removeDatanodes
      requestBody:
        description: List of datanodes to be removed
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: string
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemovedDatanodesResponse'

  /pipelines:
    get:
      tags:
        - Pipelines
      summary: Returns all the pipelines in the cluster.
      operationId: getPipelines
      responses:
        '200':
          description: |
            Successful Operation<br>
            #### **Note**: The following sample response shows only one pipeline in the array
            #### but since the pipeline totalCount is 5, there are 4 more pipelines expected in the array
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PipelinesSummary'
  /task/status:
    get:
      tags:
        - Tasks
      summary: Returns the status of all the Recon tasks.
      operationId: getTaskTimes
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TasksStatus'
  /utilization/fileCount:
    get:
      tags:
        - Utilization
      summary: Returns the file counts within different file ranges with fileSize in the response object being the upper cap for file size range.
      operationId: getFileCounts
      parameters:
        - name: volume
          in: query
          description: Filters the results based on the given volume name.
          example: sampleVol
          required: false
          schema:
            type: string
        - name: bucket
          in: query
          description: Filters the results based on the given bucket name.
          example: sampleBucket
          required: false
          schema:
            type: string
        - name: fileSize
          in: query
          description: |
            Filters the results based on the given file size.<br>
            The smallest file size being tracked for count is 1 KB i.e. 1024 bytes.
          example: 1024
          required: false
          schema:
            type: number
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileSizeUtilization'
  /utilization/containerCount:
    get:
      tags:
        - Utilization
      summary: Returns the container counts within the given container size.
      operationId: getContainerCounts
      parameters:
        - name: containerSize
          in: query
          description: |
            Filters the results based on the given containerSize.<br>
            The smallest container size being tracked for count is 512 MB i.e. 512000000 bytes.
          example: 512000000
          required: false
          schema:
            type: number
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContainerUtilization'
  /metrics/query:
    get:
      tags:
        - Metrics
      summary: This is a proxy endpoint for Prometheus, and helps to fetch different metrics for Ozone
      operationId: getMetricsResponse
      parameters:
        - name: query
          in: query
          description: The query in a Prometheus query format for which to fetch results
          example: ratis_leader_election_electionCount
          required: true
          schema:
            type: string
          allowReserved: true
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsQuery'
  /storageDistribution:
    get:
      tags:
        - Storage Distribution
      summary: Retrieves storage capacity distribution across datanodes including global storage, namespace, and used space breakdown
      operationId: getStorageDistribution
      responses:
        '200':
          description: Successful Operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorageCapacityDistributionResponse'
        '500':
          description: Internal server error while retrieving storage distribution
          content:
            text/plain:
              schema:
                type: string
  /storageDistribution/download:
    get:
      tags:
        - Storage Distribution
      summary: Downloads per-datanode storage and pending deletion statistics as a CSV file
      operationId: downloadDataNodeStorageDistribution
      description: |
        Triggers or polls a background metrics collection task across all datanodes.
        - If collection is **not yet finished**, returns **HTTP 202** with a JSON status response.
        - If collection is **finished**, returns **HTTP 200** with a downloadable CSV file containing
          per-datanode stats: HostName, Datanode UUID, Filesystem Capacity, Filesystem Used Space,
          Filesystem Remaining Space, Ozone Capacity, Ozone Used Space, Ozone Remaining Space,
          PreAllocated Container Space, Reserved Space, Minimum Free Space, Pending Block Size.
      responses:
        '200':
          description: CSV file with storage and pending deletion statistics per datanode
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '202':
          description: Metrics collection is still in progress or has not started; returns current collection status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataNodeMetricsServiceResponse'
        '500':
          description: Internal server error - metrics data missing despite FINISHED collection status
          content:
            text/plain:
              schema:
                type: string
  /pendingDeletion:
    get:
      tags:
        - Pending Deletion
      summary: Returns pending deletion information for the specified component (scm, om, or dn)
      operationId: getPendingDeletionByComponent
      description: |
        Returns pending deletion data for a specific component:
        - **scm**: Returns block-level pending deletion stats from the Storage Container Manager.
        - **om**: Returns a map of pending deletion sizes (pendingDirectorySize, pendingKeySize) from the Object Manager.
        - **dn**: Triggers or polls a background metrics collection task across all datanodes. Returns **HTTP 202** if collection is in progress, or **HTTP 200** with per-datanode pending block sizes if finished.
      parameters:
        - name: component
          in: query
          description: Component to query — one of `scm`, `om`, or `dn`
          example: scm
          required: true
          schema:
            type: string
            enum:
              - scm
              - om
              - dn
        - name: limit
          in: query
          description: Maximum number of datanode results to return (only applicable when component=dn)
          example: 10
          required: false
          schema:
            type: integer
            minimum: 1
      responses:
        '200':
          description: |
            Successful Operation. Response schema depends on the `component` parameter:
            - **scm** → `ScmPendingDeletion`
            - **om** → `OmPendingDeletion`
            - **dn** → `DataNodeMetricsServiceResponse` (only when collection is FINISHED)
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/ScmPendingDeletion'
                  - $ref: '#/components/schemas/OmPendingDeletion'
                  - $ref: '#/components/schemas/DataNodeMetricsServiceResponse'
        '202':
          description: Datanode metrics collection is still in progress or not yet started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataNodeMetricsServiceResponse'
        '400':
          description: Bad request — `component` parameter is missing, empty, or not one of `scm`, `om`, `dn`; or `limit` is less than 1
          content:
            text/plain:
              schema:
                type: string

components:
  schemas:
    Volumes:
      type: object
      properties:
        totalCount:
          type: integer
        volumes:
          type: array
          items:
            type: object
            properties:
              metadata:
                type: object
              name:
                type: string
              quotaInBytes:
                type: integer
              quotaInNamespace:
                type: integer
              usedNamespace:
                type: integer
              creationTime:
                type: integer
              modificationTime:
                type: integer
              acls:
                $ref: "#/components/schemas/ACL"
              admin:
                type: string
              owner:
                type: string
              volume:
                type: string
    Buckets:
      type: object
      properties:
        totalCount:
          type: integer
        buckets:
          type: array
          items:
            type: object
            properties:
              versioningEnabled:
                type: boolean
              metadata:
                type: object
              name:
                type: string
              quotaInBytes:
                type: integer
              quotaInNamespace:
                type: integer
              usedNamespace:
                type: integer
              creationTime:
                type: integer
              modificationTime:
                type: integer
              acls:
                $ref: "#/components/schemas/ACL"
              volumeName:
                type: string
              storageType:
                type: string
              versioning:
                type: boolean
              usedBytes:
                type: integer
              encryptionInfo:
                type: object
                properties:
                  version:
                    type: string
                  suite:
                    type: string
                  keyName:
                    type: string
              replicationConfigInfo:
                type: object
                nullable: true
              sourceVolume:
                type: string
                nullable: true
              sourceBucket:
                type: string
                nullable: true
              bucketLayout:
                type: string
              owner:
                type: string
    ContainerMetadata:
      type: object
      properties:
        data:
          type: object
          properties:
            totalCount:
              type: integer
              example: 3
            prevKey:
              type: integer
              example: 3019
            containers:
              type: array
              items:
                type: object
                properties:
                  ContainerID:
                    type: integer
                    example: 1
                  NumberOfKeys:
                    type: integer
                    example: 834
                  pipelines:
                    type: string
                    nullable: true
                xml:
                  name: containerMetadata
              example:
                - ContainerID: 1
                  NumberOfKeys: 834
                  pipelines: null
                - ContainerID: 2
                  NumberOfKeys: 833
                  pipelines: null
                - ContainerID: 3
                  NumberOfKeys: 833
                  pipelines: null
      xml:
        name: containerMetadataResponse
    DeletedContainers:
      type: array
      items:
        type: object
        properties:
          containerId:
            type: integer
          pipelineId:
            type: object
            properties:
              id:
                type: string
          containerState:
            type: string
          stateEnterTime:
            type: integer
          lastUsed:
            type: integer
          replicationConfig:
            type: object
            properties:
              replicationType:
                type: string
              replicationFactor:
                type: string
              replicationNodes:
                type: integer
          replicationFactor:
            type: string
    KeyMetadata:
      type: object
      properties:
        totalCount:
          type: integer
          example: 7
        lastKey:
          type: string
          example: /vol1/buck1/file1
        keys:
          type: array
          items:
            type: object
            properties:
              Volume:
                type: string
                example: vol-1-73141
              Bucket:
                type: string
                example: bucket-3-35816
              Key:
                type: string
                example: key-0-43637
              CompletePath:
                type: string
                example: /vol1/buck1/dir1/dir2/file1
              DataSize:
                type: integer
                example: 1000
              Versions:
                type: array
                items:
                  type: integer
                example: [0]
              Blocks:
                type: object
                properties:
                  0:
                    type: array
                    items:
                      type: object
                      properties:
                        containerID:
                          type: integer
                        localID:
                          type: number
                    example:
                      - containerID: 1
                        localID: 105232659753992201
              CreationTime:
                type: string
                format: date-time
                example: 2020-11-18T18:09:17.722Z
              ModificationTime:
                type: string
                format: date-time
                example: 2020-11-18T18:09:30.405Z
    ReplicaHistory:
      type: object
      properties:
        containerID:
          type: integer
          example: 1
        datanodeUuid:
          type: string
          example: 841be80f-0454-47df-b676
        datanodeHost:
          type: string
          example: localhost-1
        firstSeenTime:
          type: number
          example: 1605724047057
        lastSeenTime:
          type: number
          example: 1605731201301
        lastBcsId:
          type: integer
          example: 123
        state:
          type: string
          example: OPEN
    MissingContainerMetadata:
      type: object
      properties:
        totalCount:
          type: integer
          example: 26
        containers:
          type: array
          items:
            type: object
            properties:
              containerID:
                type: integer
                example: 1
              missingSince:
                type: number
                example: 1605731029145
              keys:
                type: integer
                example: 7
              pipelineID:
                type: string
                example: 88646d32-a1aa-4e1a
              replicas:
                type: array
                items:
                  $ref: "#/components/schemas/ReplicaHistory"
    UnhealthyContainerMetadata:
      type: object
      properties:
        missingCount:
          type: integer
          example: 2
        underReplicatedCount:
          type: integer
          example: 0
        overReplicatedCount:
          type: integer
          example: 0
        misReplicatedCount:
          type: integer
          example: 0
        containers:
          type: array
          items:
            type: object
            properties:
              containerID:
                type: integer
                example: 1
              containerState:
                type: string
                example: MISSING
              unhealthySince:
                type: number
                example: 1605731029145
              expectedReplicaCount:
                type: integer
                example: 3
              actualReplicaCount:
                type: integer
                example: 0
              replicaDeltaCount:
                type: integer
                example: 3
              reason:
                type: string
                example: null
              keys:
                type: integer
                example: 7
              pipelineID:
                type: string
                example: 88646d32-a1aa-4e1a
              replicas:
                type: array
                items:
                  $ref: "#/components/schemas/ReplicaHistory"
    MismatchedContainers:
      type: object
      properties:
        lastKey:
          type: integer
          example: 21
        containerDiscrepancyInfo:
          type: array
          items:
            type: object
            properties:
              containerId:
                type: integer
                example: 11
              numberOfKeys:
                type: integer
                example: 1
              pipelines:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 1202e6bb-b7c1-4a85-8067-61374b069adb
                    replicationConfig:
                      type: object
                      properties:
                        replicationFactor:
                          type: string
                          example: THREE
                        requiredNodes:
                          type: integer
                          example: 3
                        replicationType:
                          type: string
                          example: RATIS
                    healthy:
                      type: boolean
                      example: true
              existsAt:
                type: string
                example: OM
          example:
            - containerId: 2
              numberOfKeys: 2
              pipelines:
                - id:
                    id: 1202e6bb-b7c1-4a85-8067-61374b069adb
                  replicationConfig:
                    replicationFactor: ONE
                    requiredNodes: 1
                    replicationType: RATIS
                  healthy: true
              existsAt: OM
            - containerId: 11
              numberOfKeys: 2
              pipelines:
                - id:
                    id: 1202e6bb-b7c1-4a85-8067-61374b069adb
                  replicationConfig:
                    replicationFactor: TWO
                    requiredNodes: 2
                    replicationType: RATIS
                  healthy: true
                - id:
                    id: 1202e6bb-b7c1-4a85-8067-613724nn
                  replicationConfig:
                    replicationFactor: ONE
                    requiredNodes: 1
                    replicationType: RATIS
                  healthy: true
              existsAt: SCM
    DeletedMismatchedContainers:
      type: object
      properties:
        lastKey:
          type: integer
          example: 21
        containerDiscrepancyInfo:
          type: array
          items:
            type: object
            properties:
              containerId:
                type: integer
                example: 11
              numberOfKeys:
                type: integer
                example: 1
              pipelines:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: object
                      properties:
                        id:
                          type: string
                          example: 1202e6bb-b7c1-4a85-8067-61374b069adb
                    replicationConfig:
                      type: object
                      properties:
                        replicationFactor:
                          type: string
                          example: THREE
                        requiredNodes:
                          type: integer
                          example: 3
                        replicationType:
                          type: string
                          example: RATIS
                    healthy:
                      type: boolean
                      example: true
              existsAt:
                type: string
                example: OM
          example:
            - containerId: 2
              numberOfKeys: 2
              pipelines:
                - id:
                    id: 1202e6bb-b7c1-4a85-8067-61374b069adb
                  replicationConfig:
                    replicationFactor: ONE
                    requiredNodes: 1
                    replicationType: RATIS
                  healthy: true
            - containerId: 11
              numberOfKeys: 2
              pipelines:
                - id:
                    id: 1202e6bb-b7c1-4a85-8067-61374b069adb
                  replicationConfig:
                    replicationFactor: TWO
                    requiredNodes: 2
                    replicationType: RATIS
                  healthy: true
                - id:
                    id: 1202e6bb-b7c1-4a85-8067-613724nn
                  replicationConfig:
                    replicationFactor: ONE
                    requiredNodes: 1
                    replicationType: RATIS
                  healthy: true
    OpenKeysSummary:
      type: object
      properties:
        totalUnreplicatedDataSize:
          type: integer
        totalReplicatedDataSize:
          type: integer
        totalOpenKeys:
          type: integer
    OpenKeys:
      type: object
      required: ['lastKey', 'replicatedDataSize', 'unreplicatedDataSize', 'status']
      properties:
        lastKey:
          type: string
          example: /vol1/fso-bucket/dir1/dir2/file2
        replicatedDataSize:
          type: integer
          example: 13824
        unreplicatedDataSize:
          type: integer
          example: 4608
        status:
          type: string
        fso:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              key:
                type: string
              inStateSince:
                type: number
              size:
                type: integer
              replicatedSize:
                type: integer
              replicationInfo:
                type: object
                properties:
                  replicationFactor:
                    type: string
                    example: THREE
                  requiredNodes:
                    type: integer
                    example: 3
                  replicationType:
                    type: string
                    example: RATIS
              creationTime:
                type: integer
              modificationTime:
                type: integer
              isKey:
                type: boolean
        nonFSO:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              key:
                type: string
              inStateSince:
                type: number
              size:
                type: integer
              replicatedSize:
                type: integer
              replicationInfo:
                type: object
                properties:
                  replicationFactor:
                    type: string
                    example: THREE
                  requiredNodes:
                    type: integer
                    example: 3
                  replicationType:
                    type: string
                    example: RATIS
              creationTime:
                type: integer
              modificationTime:
                type: integer
              isKey:
                type: boolean
    OMKeyInfoList:
      type: array
      items:
        type: object
        properties:
          metadata:
            type: object
          objectID:
            type: number
          updateID:
            type: number
          parentObjectID:
            type: number
          volumeName:
            type: string
          bucketName:
            type: string
          keyName:
            type: string
          dataSize:
            type: number
          keyLocationVersions:
            type: array
            items:
              $ref: "#/components/schemas/VersionLocation"
          creationTime:
            type: number
          modificationTime:
            type: number
          replicationConfig:
            type: object
            properties:
              replicationFactor:
                type: string
              requiredNodes:
                type: integer
              replicationType:
                type: string
          fileChecksum:
            type: number
            nullable: true
          fileName:
            type: string
          ownerName:
            type: string
          acls:
            $ref: "#/components/schemas/ACL"
          tags:
            type: object
          expectedDataGeneration:
            type: string
            nullable: true
          file:
            type: boolean
          path:
            type: string
          generation:
            type: integer
          replicatedSize:
            type: number
          fileEncryptionInfo:
            type: string
            nullable: true
          objectInfo:
            type: string
          latestVersionLocations:
            $ref: "#/components/schemas/VersionLocation"
          hsync:
            type: boolean
    VersionLocation:
      type: object
      properties:
        version:
          type: integer
        locationVersionMap:
          type: object
          properties:
            0:
              $ref: "#/components/schemas/LocationList"
        multipartKey:
          type: boolean
        blocksLatestVersionOnly:
          $ref: "#/components/schemas/LocationList"
        locationListCount:
          type: integer
        locationLists:
          type: array
          items:
            $ref: "#/components/schemas/LocationList"
        locationList:
          $ref: "#/components/schemas/LocationList"
    LocationList:
      type: array
      items:
        type: object
        properties:
          blockID:
            type: object
            properties:
              containerBlockID:
                type: object
                properties:
                  containerID:
                    type: integer
                  localID:
                    type: integer
              blockCommitSequenceID:
                type: integer
              replicaIndex:
                type: integer
                nullable: true
              containerID:
                type: integer
              localID:
                type: integer
          length:
            type: integer
          offset:
            type: integer
          token:
            type: string
            nullable: true
          createVersion:
            type: integer
          pipeline:
            type: string
            nullable: true
          partNumber:
            type: integer
          underConstruction:
            type: boolean
          blockCommitSequenceId:
            type: integer
          containerID:
            type: integer
          localID:
            type: integer
    DeletePendingKeys:
      type: object
      properties:
        lastKey:
          type: string
          example: sampleVol/bucketOne/key_one
        replicatedDataSize:
          type: number
          example: 300000000
        unreplicatedDataSize:
          type: number
          example: 100000000
        deletedKeyInfo:
          type: array
          items:
            type: object
            properties:
              omKeyInfoList:
                $ref: "#/components/schemas/OMKeyInfoList"
              totalSize:
                type: object
                properties:
                  63:
                    type: integer
                    example: 189
        status:
          type: string
          example: OK
    DeletePendingSummary:
      type: object
      properties:
        totalUnreplicatedDataSize:
          type: integer
        totalReplicatedDataSize:
          type: integer
        totalDeletedKeys:
          type: integer
    ACL:
      type: object
      properties:
        type:
          type: string
        name:
          type: string
        aclScope:
          type: string
        aclList:
          type: array
          items:
            type: string
    DeletePendingDirs:
      type: object
      properties:
        lastKey:
          type: string
          example: vol1/bucket1/bucket1/dir1
        replicatedDataSize:
          type: integer
          example: 13824
        unreplicatedDataSize:
          type: integer
          example: 4608
        deletedDirInfo:
          type: array
          items:
            type: object
            properties:
              path:
                type: string
              key:
                type: string
              inStateSince:
                type: number
              size:
                type: integer
              replicatedSize:
                type: integer
              replicationInfo:
                type: object
                properties:
                  replicationFactor:
                    type: string
                    example: THREE
                  requiredNodes:
                    type: integer
                    example: 3
                  replicationType:
                    type: string
                    example: RATIS
              creationTime:
                type: integer
              modificationTime:
                type: integer
              isKey:
                type: boolean
        status:
          type: string
          example: OK
    DeletePendingBlocks:
      type: object
      properties:
        OPEN:
          type: array
          items:
            type: object
            properties:
              containerId:
                type: number
                example: 100
              localIDList:
                type: array
                items:
                  type: integer
                example:
                  - 1
                  - 2
                  - 3
                  - 4
              localIDCount:
                type: integer
                example: 4
              txID:
                type: number
                example: 1
    NamespaceMetadataResponse:
      type: object
      properties:
        status:
          type: string
          example: OK
        type:
          type: string
          example: BUCKET
        numVolume:
          type: number
          example: -1
        numBucket:
          type: integer
          example: 100
        numDir:
          type: number
          example: 50
        numKey:
          type: number
          example: 400
    MetadataDiskUsage:
      type: object
      properties:
        status:
          type: string
          example: OK
        path:
          type: string
          example: /vol1/bucket1
        size:
          type: number
          example: 150000
        sizeWithReplica:
          type: number
          example: 450000
        subPathCount:
          type: number
          example: 4
        subPaths:
          type: array
          items:
            type: object
            properties:
              key:
                type: boolean
              path:
                type: string
              size:
                type: number
              sizeWithReplica:
                type: number
              isKey:
                type: boolean
            example:
              - key: false
                path: /vol1/bucket1/dir1-1
                size: 30000
                sizeWithReplica: 90000
                isKey: false
              - key: false
                path: /vol1/bucket1/dir1-2
                size: 30000
                sizeWithReplica: 90000
                isKey": false
              - key: false
                path: /vol1/bucket1/dir1-3
                size: 30000
                sizeWithReplica: 90000
                isKey": false
              - key: true
                path: /vol1/bucket1/key1-1
                size: 30000
                sizeWithReplica: 90000
                isKey": true
        sizeDirectKey:
          type: number
          example: 10000
    MetadataQuota:
      type: object
      properties:
        status:
          type: string
          example: OK
        allowed:
          type: number
          example: 200000
        used:
          type: number
          example: 160000
    MetadataSpaceDist:
      type: object
      properties:
        status:
          type: string
          example: OK
        dist:
          type: array
          items:
            type: integer
          example:
            - 0
            - 0
            - 10
            - 20
            - 0
            - 30
            - 0
            - 100
            - 40
    DataNodeStorageReport:
      type: object
      properties:
        datanodeUuid:
          type: string
          example: 841be80f-0454-47df-b676
        hostName:
          type: string
          example: ozone-datanode-1
        capacity:
          type: number
          example: 270429917184
        used:
          type: number
          example: 358805504
        remaining:
          type: number
          example: 270071111680
        committed:
          type: number
          example: 27007111
        minimumFreeSpace:
          type: number
          example: 20480
        reserved:
          type: number
          example: 31457280
        filesystemCapacity:
          type: number
          example: 270461374464
        filesystemUsed:
          type: number
          example: 390262784
        filesystemAvailable:
          type: number
          example: 270071111680
      ClusterStorageReport:
        type: object
        properties:
          capacity:
            type: number
            example: 270429917184
          used:
            type: number
            example: 358805504
          remaining:
            type: number
            example: 270071111680
          committed:
            type: number
            example: 27007111
          minimumFreeSpace:
            type: number
            example: 20480
          reserved:
            type: number
            example: 31457280
          filesystemCapacity:
            type: number
            example: 270461374464
          filesystemUsed:
            type: number
            example: 390262784
          filesystemAvailable:
            type: number
            example: 270071111680
    ClusterState:
      type: object
      properties:
        deletedDirs:
          type: integer
        missingContainers:
          type: integer
        openContainers:
          type: integer
        deletedContainers:
          type: integer
        keysPendingDeletion:
          type: integer
        scmServiceId:
          type: string
        omServiceId:
          type: string
        pipelines:
          type: integer
          example: 5
        totalDatanodes:
          type: integer
          example: 4
        healthyDatanodes:
          type: integer
          example: 4
        storageReport:
          $ref: "#/components/schemas/ClusterStorageReport"
        containers:
          type: integer
          example: 26
        volumes:
          type: integer
          example: 6
        buckets:
          type: integer
          example: 26
        keys:
          type: integer
          example: 25
    DatanodesSummary:
      type: object
      properties:
        totalCount:
          type: integer
          example: 4
        datanodes:
          type: array
          items:
            type: object
            properties:
              buildDate:
                type: string
              layoutVersion:
                type: integer
              networkLocation:
                type: string
              opState:
                type: string
              revision:
                type: string
              setupTime:
                type: integer
              version:
                type: string
              uuid:
                type: string
                example: f8f8cb45-3ab2-4123
              hostname:
                type: string
                example: localhost-1
              state:
                type: string
                example: HEALTHY
              lastHeartbeat:
                type: number
                example: 1605738400544
              storageReport:
                $ref: "#/components/schemas/DataNodeStorageReport"
              pipelines:
                type: array
                items:
                  type: object
                  properties:
                    pipelineID:
                      type: string
                    replicationType:
                      type: string
                    replicationFactor:
                      type: integer
                    leaderNode:
                      type: string
                example:
                  - pipelineID: b9415b20-b9bd-4225
                    replicationType: RATIS
                    replicationFactor: 3
                    leaderNode: localhost-2
                  - pipelineID: 3bf4a9e9-69cc-4d20
                    replicationType: RATIS
                    replicationFactor: 1
                    leaderNode: localhost-1
              containers:
                type: integer
                example: 17
              leaderCount:
                type: integer
                example: 1
    RemovedDatanodesResponse:
      type: object
      properties:
        datanodesResponseMap:
          type: object
          properties:
            removedDatanodes:
              type: object
              properties:
                totalCount:
                  type: integer
                datanodes:
                  type: array
                  items:
                    type: object
                    properties:
                      uuid:
                        type: string
                      hostname:
                        type: string
                      state:
                        type: string
                      pipelines:
                        type: string
                        nullable: true
    DatanodesDecommissionInfo:
      type: object
      properties:
        DatanodesDecommissionInfo:
          type: array
          items:
            type: object
            properties:
              containers:
                type: object
              metrics:
                type: object
                properties:
                  decommissionStartTime:
                    type: string
                  numOfUnclosedContainers:
                    type: integer
                  numOfUnclosedPipelines:
                    type: integer
                  numOfUnderReplicatedContainers:
                    type: integer
                nullable: true
              datanodeDetails:
                $ref: "#/components/schemas/DatanodeDetails"
    ByteString:
      type: object
      properties:
        string:
          type: string
        bytes:
          type: object
          properties:
            validUtf8:
              type: boolean
            empty:
              type: boolean
    DatanodeDetails:
      type: object
      properties:
        level:
          type: integer
        parent:
          type: string
          nullable: true
        cost:
          type: integer
        uuid:
          type: string
        uuidString:
          type: string
        ipAddress:
          type: string
        hostName:
          type: string
        ports:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              value:
                type: integer
        certSerialId:
          type: integer
        version:
          type: string
          nullable: true
        setupTime:
          type: string
        revision:
          type: string
          nullable: true
        buildDate:
          type: string
          nullable: true
        persistedOpState:
          type: string
        persistedOpStateExpiryEpochSec:
          type: integer
        initialVersion:
          type: integer
        currentVersion:
          type: integer
        decommissioned:
          type: boolean
        maintenance:
          type: boolean
        ipAddressAsByteString:
          $ref: '#/components/schemas/ByteString'
        hostNameAsByteString:
          $ref: '#/components/schemas/ByteString'
        networkName:
          type: string
        networkLocation:
          type: string
        networkFullPath:
          type: string
        numOfLeaves:
          type: integer
        networkNameAsByteString:
          $ref: '#/components/schemas/ByteString'
        networkLocationAsByteString:
          $ref: '#/components/schemas/ByteString'
    PipelinesSummary:
      type: object
      properties:
        totalCount:
          type: integer
          example: 5
        pipelines:
          type: array
          items:
            type: object
            properties:
              pipelineId:
                type: string
                example: b9415b20-b9bd-4225
              status:
                type: string
                example: OPEN
              leaderNode:
                type: string
                example: localhost-1
              datanodes:
                type: array
                items:
                  $ref: '#/components/schemas/DatanodeDetails'
              lastLeaderElection:
                type: integer
                example: 0
              duration:
                type: number
                example: 23166128
              leaderElections:
                type: integer
                example: 0
              replicationType:
                type: string
                example: RATIS
              replicationFactor:
                type: integer
                example: 3
              containers:
                type: integer
                example: 3
    TasksStatus:
      type: array
      items:
        type: object
        properties:
          taskName:
            type: string
          lastUpdatedTimestamp:
            type: number
          lastUpdatedSeqNumber:
            type: number
      example:
        - taskName: OmDeltaRequest
          lastUpdatedTimestamp: 1605724099147
          lastUpdatedSeqNumber: 186
        - taskName: OmDeltaRequest
          lastUpdatedTimestamp: 1605724103892
          lastUpdatedSeqNumber: 188
    FileSizeUtilization:
      type: array
      items:
        type: object
        properties:
          volume:
            type: string
          bucket:
            type: string
          fileSize:
            type: number
          count:
            type: integer
        example:
          - volume: vol-2-04168
            bucket: bucket-0-11685
            fileSize: 1024
            count: 1
          - volume: vol-2-04168
            bucket: bucket-1-41795
            fileSize: 1024
            count: 1
          - volume: vol-2-04168
            bucket: bucket-2-93377
            fileSize: 1024
            count: 1
          - volume: vol-2-04168
            bucket: bucket-3-50336
            fileSize: 1024
            count: 2
    ContainerUtilization:
      type: array
      items:
        type: object
        properties:
          containerSize:
            type: number
          count:
            type: number
      example:
        - containerSize: 2147483648
          count: 9
        - containerSize: 1073741824
          count: 3
    MetricsQuery:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            resultType:
              type: string
              example: vector
            result:
              type: array
              items:
                type: object
                properties:
                  metric:
                    type: object
                    properties:
                      __name__:
                        type: string
                        example: ratis_leader_election_electionCount
                      exported_instance:
                        type: string
                        example: 33a5ac1d-8c65-4c74-a0b8-9314dfcccb42
                      group:
                        type: string
                        example: group-03CA9397D54B
                      instance:
                        type: string
                        example: ozone_datanode_1:9882
                      job:
                        type: string
                        example: ozone
                  value:
                    oneOf:
                      - type: string
                      - type: number
                    example:
                      - 1599159384.455
                      - "5"
    StorageCapacityDistributionResponse:
      type: object
      description: Aggregated storage capacity distribution report for the cluster
      properties:
        globalStorage:
          $ref: '#/components/schemas/GlobalStorageReport'
        globalNamespace:
          $ref: '#/components/schemas/GlobalNamespaceReport'
        usedSpaceBreakdown:
          $ref: '#/components/schemas/UsedSpaceBreakDown'
        dataNodeUsage:
          type: array
          description: Per-datanode storage usage reports
          items:
            $ref: '#/components/schemas/DataNodeStorageReport'
    GlobalStorageReport:
      type: object
      description: |
        Aggregated storage metrics across all datanodes in the cluster.

        **Storage Hierarchy:**
        - `totalFileSystemCapacity` = `totalOzoneCapacity` + `totalReservedSpace`
        - `totalOzoneCapacity` = `totalOzoneUsedSpace` + `totalOzoneFreeSpace`
      properties:
        totalFileSystemCapacity:
          type: integer
          format: int64
          description: Total OS-reported filesystem capacity across all datanodes (bytes)
          example: 270461374464
        totalReservedSpace:
          type: integer
          format: int64
          description: Space reserved and not available for Ozone allocation (bytes)
          example: 31457280
        totalOzoneCapacity:
          type: integer
          format: int64
          description: Portion of filesystem capacity available for Ozone — equals filesystem capacity minus reserved space (bytes)
          example: 270429917184
        totalOzoneUsedSpace:
          type: integer
          format: int64
          description: Space currently consumed by Ozone data (bytes)
          example: 358805504
        totalOzoneFreeSpace:
          type: integer
          format: int64
          description: Remaining allocatable space within Ozone capacity (bytes)
          example: 270071111680
        totalOzoneCommittedSpace:
          type: integer
          format: int64
          description: Space pre-allocated for containers but not yet fully utilized (bytes)
          example: 27007111
        totalMinimumFreeSpace:
          type: integer
          format: int64
          description: Minimum free space that must be maintained as per configuration (bytes)
          example: 20480
    GlobalNamespaceReport:
      type: object
      description: High-level metadata summary of the global namespace
      properties:
        totalUsedSpace:
          type: integer
          format: int64
          description: |
            Total space utilized in the namespace (bytes). Includes committed data,
            open keys, and data pending deletion.
          example: 500000000
        totalKeys:
          type: integer
          format: int64
          description: Total number of keys (files) in the namespace across all volumes and buckets
          example: 10000
    UsedSpaceBreakDown:
      type: object
      description: Breakdown of used storage space by lifecycle category
      properties:
        openKeyBytes:
          $ref: '#/components/schemas/OpenKeyBytesInfo'
        finalizedKeyBytes:
          type: integer
          format: int64
          description: Space occupied by written (closed) keys with replica overhead (bytes)
          example: 450000000
    OpenKeyBytesInfo:
      type: object
      description: Breakdown of storage space occupied by open (uncommitted) keys
      properties:
        openKeyAndFileBytes:
          type: integer
          format: int64
          description: Total replicated bytes for open non-multipart keys and files
          example: 13824
        multipartOpenKeyBytes:
          type: integer
          format: int64
          description: Total replicated bytes for in-progress multipart upload keys
          example: 4096
        totalOpenKeyBytes:
          type: integer
          format: int64
          description: Sum of openKeyAndFileBytes and multipartOpenKeyBytes
          example: 17920
    DataNodeMetricsServiceResponse:
      type: object
      description: Response from a background per-datanode metrics collection task
      properties:
        status:
          type: string
          enum:
            - NOT_STARTED
            - IN_PROGRESS
            - FINISHED
            - FAILED
          description: Current status of the metric collection task
          example: FINISHED
        totalPendingDeletionSize:
          type: integer
          format: int64
          description: Total size of blocks pending deletion across all queried datanodes (bytes)
          example: 1048576
        pendingDeletionPerDataNode:
          type: array
          nullable: true
          description: Per-datanode pending deletion metrics; null if collection is not finished
          items:
            $ref: '#/components/schemas/DatanodePendingDeletionMetrics'
        totalNodesQueried:
          type: integer
          description: Total number of datanodes queried during the collection task
          example: 4
        totalNodeQueriesFailed:
          type: integer
          format: int64
          description: Number of datanode queries that failed during collection
          example: 0
    DatanodePendingDeletionMetrics:
      type: object
      description: Pending deletion block metrics for a single datanode
      properties:
        hostName:
          type: string
          description: Hostname of the datanode
          example: ozone-datanode-1
        datanodeUuid:
          type: string
          description: UUID of the datanode
          example: 841be80f-0454-47df-b676-a1234567890a
        pendingBlockSize:
          type: integer
          format: int64
          description: Total size of blocks pending deletion on this datanode (bytes)
          example: 262144
    ScmPendingDeletion:
      type: object
      description: Block-level pending deletion statistics from the Storage Container Manager
      properties:
        totalBlocksize:
          type: integer
          format: int64
          description: Total unreplicated size of all blocks pending deletion in SCM (bytes)
          example: 10485760
        totalReplicatedBlockSize:
          type: integer
          format: int64
          description: Total replicated size of all blocks pending deletion in SCM (bytes)
          example: 31457280
        totalBlocksCount:
          type: integer
          format: int64
          description: Total number of blocks pending deletion in SCM
          example: 500
    OmPendingDeletion:
      type: object
      description: |
        Map of pending deletion sizes by category at the OM level (values in bytes).
        Common keys: `pendingDirectorySize`, `pendingKeySize`.
      additionalProperties:
        type: integer
        format: int64
      example:
        pendingDirectorySize: 204800
        pendingKeySize: 1048576