{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/sap-hana/refs/heads/main/json-schema/sap-hana-database-schema.json",
  "title": "SAP HANA Cloud Database Instance",
  "description": "An SAP HANA Cloud database instance representing an in-memory, column-oriented, relational database deployed on SAP Business Technology Platform. Each instance provides a fully managed SAP HANA database with configurable memory, vCPU, and storage resources, along with optional services such as the script server for predictive analysis, the JSON document store for semi-structured data, and the data provisioning server for smart data integration. Instances are provisioned within SAP BTP subaccounts and managed through the SAP HANA Cloud REST API or SAP HANA Cloud Central cockpit.",
  "type": "object",
  "required": ["id", "name", "service_plan_id"],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "The unique identifier assigned to the SAP HANA Cloud service instance during provisioning. This UUID is used in all API operations to reference the specific database instance and remains constant throughout the instance lifecycle."
    },
    "name": {
      "type": "string",
      "description": "The user-defined name of the SAP HANA Cloud database instance. Must be unique within the SAP BTP subaccount and is used for identification in the SAP HANA Cloud Central cockpit, API responses, and service bindings. The name appears as the instance label in monitoring dashboards and alert notifications.",
      "minLength": 1,
      "maxLength": 64
    },
    "service_plan_id": {
      "type": "string",
      "format": "uuid",
      "description": "The identifier of the SAP BTP service plan used to provision this instance. The service plan determines the instance type (e.g., hana for SAP HANA database, hana-td for SAP HANA database with data tiering, relational-data-lake for SAP HANA Cloud data lake) and the available configuration options and resource tiers."
    },
    "service_plan_name": {
      "type": "string",
      "description": "The human-readable name of the service plan used for this instance, indicating the database type and tier.",
      "enum": [
        "hana",
        "hana-td",
        "relational-data-lake",
        "data-lake",
        "adaptive-server",
        "admin-api-access"
      ]
    },
    "platform_id": {
      "type": "string",
      "description": "The platform identifier indicating the SAP BTP runtime environment where the instance is deployed. Typically cloud-foundry for Cloud Foundry-based environments or kubernetes for Kyma-based environments.",
      "enum": [
        "cloud-foundry",
        "kubernetes"
      ]
    },
    "context": {
      "$ref": "#/$defs/InstanceContext"
    },
    "parameters": {
      "$ref": "#/$defs/InstanceConfiguration"
    },
    "labels": {
      "type": "object",
      "description": "Key-value labels assigned to the instance for organization, filtering, and governance purposes within the SAP BTP subaccount. Labels can be used to categorize instances by environment, team, project, or other organizational dimensions.",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the SAP HANA Cloud service instance was initially provisioned. Set automatically during instance creation and remains constant throughout the instance lifecycle."
    },
    "updated_at": {
      "type": "string",
      "format": "date-time",
      "description": "ISO 8601 timestamp when the SAP HANA Cloud service instance was last modified. Updated automatically whenever instance configuration, state, or metadata is changed through the API or cockpit."
    },
    "ready": {
      "type": "boolean",
      "description": "Indicates whether the SAP HANA Cloud instance has completed provisioning and is ready to accept database connections. An instance is not ready during initial provisioning, scaling operations, or error recovery."
    },
    "usable": {
      "type": "boolean",
      "description": "Indicates whether the SAP HANA Cloud instance is currently operational and accepting database connections. An instance may be provisioned (ready) but not usable if it has been intentionally stopped to conserve resources."
    },
    "last_operation": {
      "$ref": "#/$defs/LastOperation"
    },
    "provisioningState": {
      "type": "string",
      "description": "The current provisioning lifecycle state of the instance, reflecting whether the underlying infrastructure has been fully set up, is being modified, or is being removed.",
      "enum": [
        "Provisioned",
        "Provisioning",
        "Deprovisioning",
        "Error"
      ]
    },
    "operationalState": {
      "type": "string",
      "description": "The current running state of the database instance. A Started instance is running and accepting connections, while a Stopped instance retains all data but does not consume compute resources.",
      "enum": [
        "Started",
        "Starting",
        "Stopped",
        "Stopping",
        "Error"
      ]
    },
    "connectionEndpoints": {
      "$ref": "#/$defs/ConnectionEndpoints"
    },
    "alerts": {
      "type": "array",
      "description": "The list of currently active alerts for this database instance, monitoring conditions such as memory pressure, disk usage, long-running statements, and connection limits.",
      "items": {
        "$ref": "#/$defs/AlertEvent"
      }
    },
    "metrics": {
      "$ref": "#/$defs/InstanceMetrics"
    }
  },
  "$defs": {
    "InstanceContext": {
      "type": "object",
      "description": "Platform-specific context information identifying where the SAP HANA Cloud instance is deployed within the SAP BTP organizational hierarchy.",
      "properties": {
        "subaccount_id": {
          "type": "string",
          "description": "The SAP BTP subaccount identifier where the instance is provisioned. The subaccount determines the available entitlements, resource quotas, and administrative boundaries."
        },
        "organization_guid": {
          "type": "string",
          "description": "The Cloud Foundry organization GUID associated with the instance deployment, applicable when the instance is provisioned in a Cloud Foundry environment."
        },
        "space_guid": {
          "type": "string",
          "description": "The Cloud Foundry space GUID where the instance is bound, applicable for Cloud Foundry deployments and used to scope service bindings and access control."
        },
        "instance_name": {
          "type": "string",
          "description": "The display name of the instance within the platform context, which may differ from the service instance name in multi-environment scenarios."
        },
        "region": {
          "type": "string",
          "description": "The SAP BTP region identifier where the instance is deployed (e.g., eu10, us10, ap10), determining the geographic location of the database and available data center resources."
        },
        "landscapeLabel": {
          "type": "string",
          "description": "The landscape label identifying the specific SAP BTP landscape within the region, used for infrastructure-level routing and resource isolation."
        }
      }
    },
    "InstanceConfiguration": {
      "type": "object",
      "description": "The configuration parameters defining the resource allocation, enabled features, security settings, and operational behavior of an SAP HANA Cloud database instance.",
      "properties": {
        "data": {
          "type": "object",
          "description": "The core database configuration data.",
          "properties": {
            "edition": {
              "type": "string",
              "description": "The SAP HANA Cloud edition determining the available features, performance characteristics, and commercial terms. The cloud edition provides standard capabilities, while the enterprise edition includes advanced features such as native storage extension and multi-zone high availability.",
              "enum": [
                "cloud",
                "enterprise"
              ]
            },
            "memory": {
              "type": "integer",
              "description": "The amount of memory in gigabytes allocated to the SAP HANA in-memory column store. Memory determines the maximum amount of data that can be held in memory for high-performance analytical and transactional processing. Available sizes range from 30 GB to several terabytes depending on the service plan.",
              "minimum": 30
            },
            "vcpu": {
              "type": "integer",
              "description": "The number of virtual CPUs allocated to the SAP HANA database instance for query processing, data loading, and background operations. vCPU count scales proportionally with memory allocation.",
              "minimum": 2
            },
            "storage": {
              "type": "integer",
              "description": "The amount of persistent disk storage in gigabytes allocated for SAP HANA native storage extension (NSE), enabling warm data tiering that extends the effective data capacity beyond in-memory limits."
            },
            "systempassword": {
              "type": "string",
              "format": "password",
              "description": "The password for the SYSTEM database user, which has full administrative privileges. Required during instance creation and updatable through instance modification. Never returned in API responses.",
              "writeOnly": true
            },
            "whitelistIPs": {
              "type": "array",
              "description": "List of IP addresses or CIDR ranges permitted to establish database connections to the instance. When configured, only connections originating from these addresses are allowed. An empty array blocks all external IP-based connections, requiring SAP BTP connectivity service or private link for access.",
              "items": {
                "type": "string",
                "description": "An IPv4 address or CIDR range (e.g., 192.168.1.0/24)"
              }
            },
            "enabledservices": {
              "$ref": "#/$defs/EnabledServices"
            },
            "serviceStopped": {
              "type": "boolean",
              "description": "Controls the running state of the SAP HANA Cloud instance. When set to true, the instance is stopped and no longer consumes compute resources (vCPU and memory) while retaining all persisted data on disk. When set to false, the instance is started and resumes normal operation. Useful for cost optimization in non-production environments.",
              "default": false
            },
            "availabilityZone": {
              "type": "string",
              "description": "The availability zone within the SAP BTP region where the database instance is deployed. Availability zones provide fault isolation within a region."
            },
            "slaLevel": {
              "type": "string",
              "description": "The service level agreement tier applied to the instance, determining availability guarantees, support response times, and disaster recovery capabilities.",
              "enum": [
                "standard",
                "premium"
              ]
            },
            "scriptServerGroupSize": {
              "type": "integer",
              "description": "The number of script server nodes in the script server group, applicable when the script server is enabled. More nodes allow parallel execution of AFL procedures.",
              "minimum": 0
            },
            "replicaCount": {
              "type": "integer",
              "description": "The number of read replicas for the database instance. Read replicas provide horizontal read scaling and improved availability by maintaining synchronized copies of the database.",
              "minimum": 0
            }
          }
        }
      }
    },
    "EnabledServices": {
      "type": "object",
      "description": "Optional database services that can be enabled on the SAP HANA Cloud instance to extend its capabilities beyond the core relational database engine.",
      "properties": {
        "scriptserver": {
          "type": "boolean",
          "description": "Enables the SAP HANA script server for running application function libraries (AFL), including the Predictive Analysis Library (PAL) for machine learning, the Business Function Library (BFL), and R integration for statistical computing. The script server runs in a separate process and requires additional memory allocation.",
          "default": false
        },
        "docstore": {
          "type": "boolean",
          "description": "Enables the SAP HANA JSON Document Store for storing, indexing, and querying semi-structured JSON documents alongside relational data. The document store supports collection-based data organization with SQL-based querying of JSON properties.",
          "default": false
        },
        "dpserver": {
          "type": "boolean",
          "description": "Enables the SAP HANA data provisioning server for SAP HANA Smart Data Integration (SDI), providing real-time and batch data replication from source systems, data transformation, and data quality services through remote source adapters.",
          "default": false
        }
      }
    },
    "ConnectionEndpoints": {
      "type": "object",
      "description": "Network connection endpoints for accessing the SAP HANA Cloud database instance through various protocols and interfaces.",
      "properties": {
        "host": {
          "type": "string",
          "description": "The fully qualified hostname for connecting to the SAP HANA database instance (e.g., xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.hana.trial-us10.hanacloud.ondemand.com)."
        },
        "port": {
          "type": "integer",
          "description": "The port number for SQL/MDX connections to the SAP HANA database, typically 443 for encrypted connections through SAP HANA Cloud.",
          "default": 443
        },
        "sqlEndpoint": {
          "type": "string",
          "description": "The complete JDBC/ODBC connection string including host and port for establishing SQL connections to the database."
        },
        "httpsEndpoint": {
          "type": "string",
          "format": "uri",
          "description": "The HTTPS endpoint URL for accessing the SAP HANA database through HTTP-based interfaces such as OData, REST, or the XS engine."
        }
      }
    },
    "LastOperation": {
      "type": "object",
      "description": "Details about the most recent operation performed on the SAP HANA Cloud service instance, providing status tracking for asynchronous provisioning, update, and delete operations.",
      "properties": {
        "type": {
          "type": "string",
          "description": "The type of operation that was performed on the instance.",
          "enum": [
            "create",
            "update",
            "delete"
          ]
        },
        "state": {
          "type": "string",
          "description": "The current execution state of the operation. Operations are processed asynchronously, transitioning from in progress to either succeeded or failed.",
          "enum": [
            "succeeded",
            "in progress",
            "failed"
          ]
        },
        "description": {
          "type": "string",
          "description": "A human-readable description of the current operation status, including progress details or error messages if the operation has failed."
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when the operation was initiated."
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when the operation status was last updated by the platform."
        }
      }
    },
    "AlertEvent": {
      "type": "object",
      "description": "An alert event triggered when a monitored metric or condition on the SAP HANA Cloud instance crosses a configured threshold. Alerts cover database health indicators including memory usage, disk utilization, connection counts, long-running statements, backup status, and license expiration.",
      "properties": {
        "alertId": {
          "type": "string",
          "description": "The unique identifier of the individual alert event occurrence."
        },
        "alertRuleId": {
          "type": "string",
          "description": "The identifier of the alert rule definition that generated this event."
        },
        "alertName": {
          "type": "string",
          "description": "The human-readable name describing the alert condition (e.g., Memory Usage, Disk Usage, Long-Running Statements, Inactive Connections)."
        },
        "alertState": {
          "type": "string",
          "description": "The current state of the alert. Active alerts represent ongoing conditions that require attention, while Resolved alerts have returned to normal operating parameters.",
          "enum": [
            "Active",
            "Resolved"
          ]
        },
        "severity": {
          "type": "string",
          "description": "The severity level indicating the urgency and impact of the alert condition. High severity alerts typically indicate conditions that may cause service disruption if not addressed.",
          "enum": [
            "High",
            "Medium",
            "Low",
            "Information"
          ]
        },
        "description": {
          "type": "string",
          "description": "A detailed description of the alert condition, including the specific metric, current value, and threshold that was exceeded."
        },
        "triggeredAt": {
          "type": "string",
          "format": "date-time",
          "description": "ISO 8601 timestamp when the alert condition was first detected and the alert event was created."
        },
        "resolvedAt": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "ISO 8601 timestamp when the alert condition was resolved and the metric returned to normal operating range. Null if the alert is currently active."
        },
        "currentValue": {
          "type": "number",
          "format": "double",
          "description": "The current value of the monitored metric at the time of the alert or the most recent evaluation."
        },
        "thresholdValue": {
          "type": "number",
          "format": "double",
          "description": "The configured threshold value that was crossed to trigger the alert."
        },
        "unit": {
          "type": "string",
          "description": "The unit of measurement for the metric and threshold values (e.g., percent, GB, count, seconds)."
        }
      }
    },
    "InstanceMetrics": {
      "type": "object",
      "description": "Current and historical performance metrics for the SAP HANA Cloud database instance, providing insight into resource utilization, workload characteristics, and operational health.",
      "properties": {
        "cpuUsagePercent": {
          "type": "number",
          "format": "double",
          "description": "The current CPU utilization as a percentage of allocated vCPU resources. Sustained high CPU usage may indicate the need for scaling or query optimization.",
          "minimum": 0,
          "maximum": 100
        },
        "memoryUsedGB": {
          "type": "number",
          "format": "double",
          "description": "The amount of allocated memory currently in use by the database in gigabytes, including column store data, row store data, and internal data structures.",
          "minimum": 0
        },
        "memoryAllocatedGB": {
          "type": "number",
          "format": "double",
          "description": "The total memory allocated to the database instance in gigabytes, representing the maximum in-memory data capacity.",
          "minimum": 0
        },
        "diskUsedGB": {
          "type": "number",
          "format": "double",
          "description": "The amount of persistent disk storage currently consumed in gigabytes, including data files, log files, and trace files.",
          "minimum": 0
        },
        "diskAllocatedGB": {
          "type": "number",
          "format": "double",
          "description": "The total persistent disk storage allocated to the instance in gigabytes.",
          "minimum": 0
        },
        "activeConnections": {
          "type": "integer",
          "description": "The current number of active database connections from applications, tools, and internal services.",
          "minimum": 0
        },
        "totalConnections": {
          "type": "integer",
          "description": "The total number of database connections including both active and idle connections.",
          "minimum": 0
        },
        "statementsPerSecond": {
          "type": "number",
          "format": "double",
          "description": "The current rate of SQL statement executions per second across all connections.",
          "minimum": 0
        },
        "longRunningStatements": {
          "type": "integer",
          "description": "The number of currently executing SQL statements that have exceeded the long-running statement threshold configured in the alert rules.",
          "minimum": 0
        },
        "columnStoreUnloads": {
          "type": "integer",
          "description": "The number of column store table unload events that have occurred due to memory pressure, indicating potential memory sizing issues.",
          "minimum": 0
        },
        "lastBackupTimestamp": {
          "type": ["string", "null"],
          "format": "date-time",
          "description": "ISO 8601 timestamp of the most recent successful database backup. Null if no backup has been completed."
        }
      }
    }
  }
}